Skip to main content

Getting Started with the App

How to configure and run the Chompardo App frontend locally with OIDC authentication against the Identity service.

Prerequisites​

  • Node.js >= 18.0
  • pnpm 9.0.0 or later
  • Infrastructure running (docker compose up -d)
  • Identity app set up and running (see Getting Started)
  • mkcert CA trusted (run mkcert -install)

Configuration​

1. Set up your .env​

Copy the example file:

cp apps/app/.env.local.example apps/app/.env.local

2. Seed the OAuth client​

The App needs an OAuth client registered in the Identity service. Run the seed script:

cd apps/identity && pnpm seed:oauth-client

This outputs a client_id and client_secret. Copy them into apps/app/.env.

3. Generate a session secret​

The session secret is used to HMAC-sign cookies. It must be at least 32 characters:

openssl rand -hex 32

Add the output to SESSION_SECRET in apps/app/.env.

4. Complete the .env​

Your apps/app/.env should look like this:

# --- OIDC (Identity Service) ---
OAUTH_CLIENT_ID=<from seed script>
OAUTH_CLIENT_SECRET=<from seed script>
OAUTH_ISSUER=https://main-identity.chompardo.dev
APP_BASE_URL=https://main.chompardo.dev
SESSION_SECRET=<from openssl rand -hex 32>
SESSION_TTL_SECONDS=86400
VALKEY_URL=redis://localhost:6379

# --- TLS ---
NODE_EXTRA_CA_CERTS=$(mkcert -CAROOT)/rootCA.pem

# --- Logging ---
LOG_LEVEL=info

# --- OpenTelemetry ---
OTEL_SERVICE_NAME=app
# ... (see .env.example for full OTEL config)

Environment variables​

VariableRequiredDefaultDescription
OAUTH_CLIENT_IDYes—OAuth client ID from the seed script
OAUTH_CLIENT_SECRETYes—OAuth client secret from the seed script
OAUTH_ISSUERYes—Identity service URL
APP_BASE_URLYes—App's own URL (must match OAuth redirect)
SESSION_SECRETYes—HMAC signing key, min 32 chars
SESSION_TTL_SECONDSNo2592000Session lifetime (default 30 days)
VALKEY_URLYes—Valkey/Redis connection URL
NODE_EXTRA_CA_CERTSYes—Path to mkcert root CA cert for local dev
LOG_LEVELNoinfoPino log level

Running the App​

pnpm dev --filter=app

Or run everything together:

pnpm dev

The app is available at:

URLDescription
http://localhost:3001Direct access
https://main.chompardo.devVia Traefik (HTTPS)

Auth Flows​

Visiting the App directly​

  1. The middleware detects no session and redirects you to /auth/login
  2. /auth/login redirects to the Identity service's authorize endpoint
  3. Identity shows the login page (or auto-completes if you already have a session)
  4. After signing in, Identity redirects back to /auth/callback
  5. The callback exchanges the authorization code for tokens and creates a server-side session
  6. You're redirected to the home page, signed in

Signing in at Identity directly​

  1. Visit main-identity.chompardo.dev and sign in
  2. Identity redirects to main.chompardo.dev (configured via DEFAULT_REDIRECT_URL)
  3. The App middleware detects no session and starts the OIDC flow
  4. Since Identity already has a session, the authorize flow auto-completes
  5. You end up signed in at the App without seeing the login page again

Signing out​

  1. Click "Sign out" in the App
  2. The App clears the server-side session and cookie
  3. The App calls Identity's end-session endpoint server-side (fire-and-forget)
  4. The browser is redirected to Identity's login page
  5. After signing in again, you're redirected to the App via DEFAULT_REDIRECT_URL

See the Authentication Architecture for the full technical details.

Troubleshooting​

"Invalid environment variables" on startup​

The app validates all environment variables at startup using Zod. If any required variable is missing or malformed, the process exits with an error showing which fields failed. Check your .env against the table above.

unable to get local issuer certificate​

The App makes server-to-server HTTPS calls to Identity through Traefik. Node.js doesn't trust the mkcert CA by default. Ensure:

  • NODE_EXTRA_CA_CERTS=$(mkcert -CAROOT)/rootCA.pem is set in your .env.local
  • The mkcert CA is trusted by running mkcert -install
  • You restarted the App after adding the env var

This also applies to the Identity app (for JWKS self-fetch during logout).

"Authentication session expired. Please try signing in again."​

PKCE data is stored as flash data in the session. If the session expired or the flash data was already consumed (e.g., by a duplicate callback request), the OIDC flow cannot complete. Refresh the page to restart the flow.

Session lost after server restart​

Sessions are stored in Valkey. If Valkey was restarted (e.g., docker compose down -v), all sessions are lost — you'll need to sign in again.

OAuth client not found after docker compose down -v​

Wiping Docker volumes deletes all databases. Re-run migrations and re-seed:

cd apps/identity && pnpm run migrate && pnpm seed:oauth-client

Then copy the new credentials into apps/app/.env.