Standalone Server

Run Athena Auth as a standalone auth service with Docker, Docker Compose, or bare metal.

Athena Auth can run in two modes:

Embedded library in your Rust application (see Axum Integration)
Standalone auth server using the built-in server binary

This guide covers standalone deployment with Docker Compose, Dockerfile, and bare-metal.

What the standalone server provides

When you run server, Athena Auth exposes:

Auth API under AUTH_BASE_PATH (default /api/auth)
Health endpoints (for example /api/auth/health with default base path)
OpenAPI JSON (/api/auth/reference/openapi.json with default base path)
Static admin/docs UI at /admin/ and /admin/docs.html
Optional bootstrap config at /admin/api-config.json

Configuration

Required environment variables

Variable	Description	Example
`DATABASE_URL`	PostgreSQL connection string	`postgresql://postgres:postgres@localhost:5432/athena_auth`
`JWT_SECRET`	Signing secret, minimum 32 characters	`replace_with_long_random_secret`

Common runtime variables

Variable	Default	Notes
`HOST`	`0.0.0.0`	Bind interface
`PORT`	`3000`	Listen port
`BASE_URL`	`http://localhost:{PORT}`	Public base URL used for links/origin defaults
`AUTH_BASE_PATH`	`/api/auth`	Where auth routes are mounted
`TRUSTED_ORIGINS`	(empty)	Comma-separated origins for cross-origin browser use
`DOCS_API_ORIGIN`	`BASE_URL`	Optional override for `/admin/api-config.json`
`DATABASE_KEY`	(empty)	Optional (for gateway-style backends), unused for local PostgreSQL

Optional passkey variables

PASSKEY_RP_ID, PASSKEY_RP_NAME, PASSKEY_ORIGIN, PASSKEY_ALLOW_INSECURE.

If your docs UI or frontend is served from a different origin than the API, add that origin to TRUSTED_ORIGINS.

Option 1: Docker Compose (recommended local setup)

From the repository root:

docker compose up --build

This starts both:

postgres (PostgreSQL 16)
athena-auth (standalone server on http://localhost:3000)

Verify:

curl http://localhost:3000/api/auth/health
curl http://localhost:3000/api/auth/reference/openapi.json
open http://localhost:3000/admin/docs.html

If you changed AUTH_BASE_PATH, update the URL paths accordingly.

Option 2: Dockerfile image (standalone container)

Build the image:

docker build -t athena-auth .

Run it (pointing to an existing PostgreSQL instance):

docker run --rm -p 3000:3000 \
  -e DATABASE_URL=postgresql://postgres:postgres@host.docker.internal:5432/athena_auth \
  -e DATABASE_KEY="" \
  -e JWT_SECRET=replace_with_long_random_secret_minimum_32_chars \
  -e BASE_URL=http://localhost:3000 \
  -e AUTH_BASE_PATH=/api/auth \
  athena-auth

Then validate:

curl http://localhost:3000/api/auth/health

Option 3: Bare-metal / VM (run binary directly)

Copy environment defaults and update values:

cp .env.example .env

Make sure PostgreSQL is running and schema is initialized.
Start the server from the repository root:

cargo run --bin server --features server

Validate:

curl http://localhost:3000/api/auth/health
curl http://localhost:3000/api/auth/reference/openapi.json

Open docs/admin UI:

http://localhost:3000/admin/
http://localhost:3000/admin/docs.html

Production notes

Use a strong random JWT_SECRET (32+ characters).
Use managed PostgreSQL credentials and TLS where applicable.
Set BASE_URL to your public HTTPS origin.
Set TRUSTED_ORIGINS explicitly for browser clients.
Keep AUTH_BASE_PATH stable so API clients and docs stay aligned.

Next steps

API Playground — run interactive requests against your standalone server
API Routes — endpoint list and behavior
Security — production hardening guidance

Standalone Server

On this page