Configuration & Environment
How to configure a Workloom registry deployment.
Environment Variables
Workloom uses a typed environment variable registry. Variables are categorized by type:
- public — safe to expose to browser clients
- secret — server-only credentials
- connection — server-only connection strings
Required Variables
| Variable | Type | Description |
|---|---|---|
DATABASE_URL | connection | PostgreSQL connection string |
AUTH_SECRET | secret | JWT/session signing secret |
Authentication
| Variable | Description |
|---|---|
AUTH_OIDC_ISSUER | OIDC provider issuer URL |
AUTH_OIDC_CLIENT_ID | OIDC client ID |
AUTH_OIDC_CLIENT_SECRET | OIDC client secret |
AUTH_OIDC_ROLE_SCOPE | OAuth scope for role claims |
AUTH_OIDC_ROLE_CLAIM | JWT claim containing user groups |
AUTH_OIDC_DEFAULT_ROLE | Fallback role (default: developer) |
AUTH_OIDC_AUTO_PROVISION_ORG | Org slug for automatic membership |
AUTH_GITHUB_ID / AUTH_GITHUB_SECRET | GitHub OAuth (optional) |
AUTH_GOOGLE_ID / AUTH_GOOGLE_SECRET | Google OAuth (optional) |
Role Mapping
Map external IdP group names to Workloom's internal roles. Patterns support * glob matching.
| Variable | Example |
|---|---|
ROLE_MAP_OWNER | cto,org-owner |
ROLE_MAP_ADMIN | platform-admin,infra-admin,dev-lead-* |
ROLE_MAP_MAINTAINER | team-lead-*,release-mgr |
ROLE_MAP_DEVELOPER | backend-eng,frontend-eng,platform-eng |
ROLE_MAP_VIEWER | contractor-*,intern-* |
These are defaults — organizations can override mappings in the database via the role_mappings table.
Object Storage (S3)
| Variable | Description |
|---|---|
S3_BUCKET | Bucket name for package uploads |
S3_REGION | AWS region (default: us-east-1) |
S3_ENDPOINT | Custom endpoint (for MinIO, R2, etc.) |
S3_ACCESS_KEY_ID | Access key |
S3_SECRET_ACCESS_KEY | Secret key |
S3_FORCE_PATH_STYLE | Set true for MinIO/path-style URLs |
S3_URL_TTL_SECONDS | Presigned URL expiry (seconds) |
Server
| Variable | Description |
|---|---|
PORT | API server port (default: 3001) |
API_PORT | Port for Next.js proxy rewrites |
NODE_ENV | development, production, or test |
WL_REGISTRY_URL | Registry URL for CLI operations |
File Loading Precedence
Environment files are loaded in order (later overrides earlier):
.env— base defaults.env.local— local overrides (gitignored).env.${ENV}— environment-specific (e.g.,.env.production).env.${ENV}.local— environment-specific local overrides
Variable interpolation (${VAR_NAME}) is supported via dotenv-expand.
Minimal .env.local for Development
DATABASE_URL=postgres://localhost:5432/workloom
AUTH_SECRET=dev-secret-change-in-production
# Optional: enable OIDC
AUTH_OIDC_ISSUER=https://your-idp.example.com
AUTH_OIDC_CLIENT_ID=your-client-id
AUTH_OIDC_CLIENT_SECRET=your-client-secret
AUTH_OIDC_ROLE_CLAIM=groups
AUTH_OIDC_AUTO_PROVISION_ORG=my-org
# S3 (MinIO for local dev)
S3_BUCKET=workloom-dev
S3_ENDPOINT=http://localhost:9000
S3_ACCESS_KEY_ID=minioadmin
S3_SECRET_ACCESS_KEY=minioadmin
S3_FORCE_PATH_STYLE=true