Quick Start¶
Run the full stack locally from auth-engine-infra/compose/.
Steps
1 Configure .env → 2 Start Compose → 3 Run migrations → 4 Smoke test
1. Prerequisites¶
| Requirement | Notes |
|---|---|
| Docker + Docker Compose | Required |
| OpenSSL | Optional — openssl rand -hex 32 for secrets |
2. Configure environment¶
cd auth-engine-infra/compose
cp env.local.example .env
Set SECRET_KEY and JWT_SECRET_KEY to unique 32+ character values (defaults work for local only).
3. Start the stack¶
docker compose up -d --build
| Service | URL |
|---|---|
| API | http://localhost:8000 |
| Swagger | http://localhost:8000/docs |
| Frontend | http://localhost:3000 |
Images build from GitHub (Q-Niranjan/auth-engine, Q-Niranjan/auth-engine-frontend) unless you override AUTH_ENGINE_SRC / AUTH_ENGINE_FRONTEND_SRC in .env.
4. Run migrations¶
docker exec authengine-api auth-engine migrate
On first startup the API seeds RBAC roles and a super admin from SUPERADMIN_EMAIL / SUPERADMIN_PASSWORD in .env.
5. Smoke test¶
- Call
GET /api/v1/healthin Swagger. - Log in at http://localhost:3000/login with super admin credentials.
- Platform routes (
/platform/*) need a platform-scoped role; tenant routes need a tenant selected in the dashboard.
6. OAuth providers (optional)¶
Set GOOGLE_*, GITHUB_*, or MICROSOFT_* in .env. Local redirect URIs:
http://localhost:8000/api/v1/auth/oauth/google/callback
http://localhost:8000/api/v1/auth/oauth/github/callback
http://localhost:8000/api/v1/auth/oauth/microsoft/callback
7. Run without Docker (alternative)¶
Backend — cloned auth-engine repo:
uv sync
auth-engine migrate
auth-engine run
Frontend — auth-engine-frontend:
cp .env.example .env.local
npm ci && npm run dev
NEXT_PUBLIC_API_URL=http://localhost:8000/api/v1
NEXT_PUBLIC_APP_URL=http://localhost:3000
Next¶
| Step | Guide |
|---|---|
| Understand the system | Architecture |
| Deploy to production | Deployment |
| OAuth / OIDC integration | OAuth2 / OIDC Guides |
| REST endpoints | API Reference |