Trax API

Open-source media tracking backend (TV/movies via Trakt later, plus books and more).

Stack

• Go + Chi (package-by-feature)
• PostgreSQL 16
• Redis 7
• sqlc + golang-migrate
• JWT access tokens + hashed refresh tokens

Quick start

cp .env.example .env
make up
make migrate
make sqlc   # only needed after changing SQL
make run

Default .env.example maps Postgres to host port 5433 and Redis to 6380 (to avoid clashes with other local stacks). API listens on HTTP_ADDR (default :8080 in example; change if needed).

Endpoints (v1)

Method	Path	Auth
GET	/health	no
GET	/ready	no
POST	/v1/auth/register	no
POST	/v1/auth/login	no
POST	/v1/auth/refresh	no
POST	/v1/auth/logout	no
GET	/v1/users/me	Bearer access token

Register example

curl -s localhost:8080/v1/auth/register \
  -H 'content-type: application/json' \
  -d '{"email":"you@example.com","password":"password1","display_name":"You"}'

Tests

make up
make migrate
make test

Unit tests run without Docker. Integration tests skip if Postgres/Redis are unavailable.

Layout

cmd/api/                  entrypoint
internal/core/            health/ready
internal/user/            auth + profile
internal/platform/        config, db, http helpers, jwt
db/migrations/            SQL migrations
db/queries/               sqlc queries
tests/integration/        HTTP integration tests

Deploy with Docker

Option A — everything on one machine

cp .env.example .env
# Edit JWT secrets (min 32 chars)

make deploy

curl -s http://localhost:8080/health
curl -s http://localhost:8080/ready

Option B — Postgres/Redis on a separate server (recommended for production)

1. Data server (copy the repo or at least Compose + .env, then):

cp .env.example .env
# Set strong POSTGRES_PASSWORD and REDIS_PASSWORD
# Bind POSTGRES_PORT / REDIS_PORT as needed

make deploy-infra
# docker compose -f docker-compose.infra.yml up -d

Firewall that host so only the API server can reach Postgres and Redis ports.

2. API server .env must point at the data host:

DATABASE_URL=postgres://trax:YOUR_PG_PASSWORD@DATA_SERVER_IP:5432/trax?sslmode=disable
REDIS_URL=redis://:YOUR_REDIS_PASSWORD@DATA_SERVER_IP:6379/0
JWT_ACCESS_SECRET=...at-least-32-chars...
JWT_REFRESH_SECRET=...at-least-32-chars...
API_PORT=8080

Then:

make deploy-api
# docker compose -f docker-compose.api.yml up -d --build

Migrations run automatically before the API starts (migrate service).

3. Verify from the API server:

curl -s http://localhost:8080/ready
# expect postgres and redis "up"

Stop each side independently:

make down-api      # API server
make down-infra    # data server

File	Purpose
docker-compose.yml	Local all-in-one
docker-compose.infra.yml	Data server (Postgres + Redis)
docker-compose.api.yml	API server (migrate + api)

Local development (API on host)

make up-deps
make migrate
make run

Useful commands

docker compose ps
make logs-api
docker compose -f docker-compose.api.yml up -d --build api

Contributing

See CONTRIBUTING.md for setup, conventions, and pull request guidelines.

License

Licensed under the Apache License 2.0.

Contributors

Thanks to everyone who has contributed to Trax API.