Identity.Base Docs

Local Development

The upstream Identity repository ships a Dockerfile and a local Compose stack for the identity API, PostgreSQL, and MailHog. This is the fastest way to validate health checks, email flows, and the sample clients before you move to real environments.

1. Copy the environment file

bash 
cp .env.example .env

2. Run the local stack

bash 
docker compose -f docker-compose.local.yml --env-file .env up --build

3. Verify health

bash 
curl http://localhost:8080/healthz | jq

What the stack includes

  • `identity-api` on `http://localhost:8080`.
  • `postgres` with a persisted volume for the identity store.
  • `mailhog` on `http://localhost:8025` for inspecting email traffic during development.

Common problems

  • MailJet validation errors usually mean the expected `MAILJET__*` values are empty when the package is enabled.
  • Database failures usually mean the connection string is using the wrong hostname inside Docker. Use `postgres`, not `localhost`, from the container.
  • External login callback problems usually mean the provider callback URL does not match the hostname used by your local stack.