Local quickstart#

Start an instance from the private checkout or the supplied local image bundle. This guide keeps the development email inbox and operator endpoints private.

Requirements#

• Docker with Compose and the supplied ARM64 images, or Go and PostgreSQL to build the service from source.
• Access to ProudAuth's checkout or the image deployment directory.
• An application-provided sign-in interface for browser login.

Start the image deployment#

From the checkout:

cd docker-deploy
./init-env.sh
./load-images.sh
./start.sh

Skip load-images.sh if the images are already loaded. This deployment never pulls images. It starts PostgreSQL 18, the server, worker and API explorer, then creates realm main once. Its PostgreSQL volume survives a normal shutdown.

The default development API is http://localhost:8080. An existing .env can select an HTTPS origin and the tunnel profile. Check your own .env locally; never share its database password or root key.

Check the instance#

curl --fail http://localhost:8080/health/ready
curl --fail http://localhost:8080/realms/main/.well-known/openid-configuration
curl --fail http://localhost:8080/realms/main/jwks

For the public demonstration, use:

curl --fail https://auth.proudauth.com/health/ready
curl --fail https://auth.proudauth.com/realms/main/.well-known/openid-configuration

Use the discovery document's exact issuer when configuring a client or verifier. Changing a process's public origin does not migrate an existing realm's issuer.

Create the first administrator#

The first administrator is provisioned through the trusted operator channel, not through an anonymous public API:

docker compose exec server /usr/local/bin/identity-cli bootstrap \
  -realm main -email [email protected] -username admin

Treat the one-time setup output as a credential. Complete setup and enroll MFA through the headless interaction API. The development email sink is available only on the loopback operator listener. Follow the complete bootstrap runbook and headless authentication guide. Administrative API calls require a valid MFA-backed administrator session.

Connect an application#

1. Register its OAuth client, exact redirect URIs and allowed browser origins.
2. Register the API audience and scopes it needs.
3. Use authorization code with PKCE S256 for user sign-in, or client credentials for services. The OAuth password grant is not provided.
4. Validate issuer, audience, token type and organization in your API.
5. Choose offline, strict-online or bounded-state revocation behavior deliberately.

Continue with OAuth and OIDC, SDKs and the API reference.

Before production#

Use the production installation runbook: real SMTP, production mode, separated database roles, HTTPS, secret references, private operator access, backups and restore drills. Keep the root key separately from database backups. The local development profile is not a production profile.

docker compose down stops the instance while preserving its database volume. Adding -v deletes that volume and all identity data.