Configuration Reference
Ephor follows the 12-factor app methodology. All runtime configuration is provided through environment variables.
Database
| Variable | Default | Description |
|---|---|---|
SPRING_DATASOURCE_URL | jdbc:postgresql://localhost:5432/ephor | JDBC connection URL |
SPRING_DATASOURCE_USERNAME | ephor | Database username |
SPRING_DATASOURCE_PASSWORD | ephor | Database password |
Ephor requires PostgreSQL. Other databases are not supported.
Authentication
| Variable | Default | Description |
|---|---|---|
AUTH_ENABLED | true | Enable authentication enforcement |
AUTH_DEV_ENABLED | false | Bypass authentication with a development user. Never enable in production. |
AUTH_PROVIDER | oauth2-proxy | Authentication provider |
AUTH_LOGIN_URL | /oauth2/start | Redirect URL for unauthenticated users |
AUTH_LOGOUT_URL | /oauth2/sign_out | Redirect URL after logout |
Development User
Only effective when AUTH_DEV_ENABLED=true.
| Variable | Default | Description |
|---|---|---|
AUTH_DEV_USERNAME | dev-user | Username for the development user |
AUTH_DEV_EMAIL | dev@localhost | Email for the development user |
AUTH_DEV_GROUPS | ephor-admins,developers,security-team | Comma-separated groups |
AUTH_DEV_DISPLAY_NAME | Development User | Display name |
User Directory
| Variable | Default | Description |
|---|---|---|
EPHOR_USER_DIRECTORY_PROVIDER | internal | Provider for user/group sync. Options: internal, keycloak, github, none |
Keycloak Provider
Used when EPHOR_USER_DIRECTORY_PROVIDER=keycloak.
| Variable | Description |
|---|---|
KEYCLOAK_SERVER_URL | Base URL of the Keycloak server |
KEYCLOAK_REALM | Keycloak realm name |
KEYCLOAK_CLIENT_ID | Client ID for API access |
KEYCLOAK_CLIENT_SECRET | Client secret for API access |
KEYCLOAK_SYNC_INTERVAL | Sync interval in milliseconds (default: 900000 / 15 minutes) |
The Keycloak service account needs the following realm roles: view-users, manage-users, query-users, query-groups, query-realms.
GitHub Provider
Used when EPHOR_USER_DIRECTORY_PROVIDER=github.
| Variable | Description |
|---|---|
GITHUB_ORG | GitHub organization name |
GITHUB_TOKEN | Personal access token with read:org scope |
GITHUB_SYNC_INTERVAL | Sync interval in milliseconds (default: 1800000 / 30 minutes) |
Team-to-group mappings are configured via Spring Boot relaxed binding. By default, GitHub team slugs are used directly as group names.
Logging
| Variable | Default | Description |
|---|---|---|
LOGGING_STRUCTURED_FORMAT_CONSOLE | (none) | Set to ecs or logstash for structured JSON logging. Leave unset for human-readable output. |
Server
| Variable | Default | Description |
|---|---|---|
PORT | 8080 | Port the API listens on |