diff --git a/README.md b/README.md index 0c96290..701eb3e 100644 --- a/README.md +++ b/README.md @@ -14,37 +14,59 @@ It is in early development. - A PostgreSQL connection pool. - PostgreSQL with the pgvector extension, running in Docker Compose. - Database migrations with goose (first migration: the `tenants` table). +- A small Docker image for the API (multi-stage build, distroless, runs as a non-root user). - Automated checks on every pull request: formatting, `go vet`, tests with the race detector, `golangci-lint` (with gosec) and `govulncheck`. ## Requirements -- Go 1.26 or newer +- Go 1.26 or newer (needed for the tests and for `make migrate`) - Docker - `make` and a bash shell (on Windows, use Git Bash) ## Run it locally +First, create your local settings. Open `.env` and replace `change-me` with a password (letters and digits only): + ```bash -# 1. Create your local settings, then open .env and replace "change-me" cp .env.example .env +``` -# 2. Start PostgreSQL in Docker -make db +### Option 1: everything in Docker -# 3. Create the database tables +```bash +# Start PostgreSQL and the API (press Ctrl+C to stop) +make dev +``` + +In another terminal, create the database tables: + +```bash make migrate +``` + +### Option 2: only PostgreSQL in Docker, the API on your machine -# 4. Start the API on http://localhost:8080 -make run +Good for development, because Go recompiles without rebuilding an image. + +```bash +make db # start PostgreSQL +make migrate # create the database tables +make run # start the API ``` -In another terminal: +Do not use both options at the same time: they use the same port (8080). + +### Check that it works + +The API listens on : ```bash curl http://localhost:8080/healthz curl http://localhost:8080/readyz ``` +Both should answer `200` with `{"status":"ok"}`. + Run `make help` to see all commands. ## Tests @@ -57,9 +79,10 @@ make test-race # same, with the race detector (needs a 64-bit C compiler) ## Project layout ```text -backend/ Go code (API, database migrations) -compose.yaml PostgreSQL for local development -Makefile shortcuts for the common commands +backend/ Go code (API, Dockerfile, database migrations) +compose.yaml PostgreSQL and the API for local development +Makefile shortcuts for the common commands +.github/ GitHub Actions workflows (CI) ``` ## License