Configuration reference
Delegaris reads its settings from environment variables. With the standard docker-compose.yml, they go in the .env file next to it. Change .env, then run docker compose up -d to restart the container with the new values. With the Linux package, they go in /etc/delegaris/delegaris.env; change it, then run sudo systemctl restart delegaris.
Many settings can also be changed in the web interface. For those, the environment gives the starting value: once an administrator saves a value under Settings, the saved value applies on every copy of the service, without a restart, and the environment value is no longer used. The tables below say where that is the case.
Names are not case sensitive. Lists are comma separated. Values shown as (empty) are off or unset by default.
The service checks its configuration when it starts. If something cannot work (no way to sign in at all, LDAP without TLS, only one of TLS_CERT_FILE and TLS_KEY_FILE, no regions), it exits and the log lists each problem under Configuration problems. Docker (with restart: unless-stopped) or systemd keeps starting it again until the setting is fixed.
Docker Compose
These are read by docker-compose.yml, not by the service.
| Variable | Default | Meaning |
|---|---|---|
DELEGARIS_TAG | latest | Which image tag to run. Set a version, such as 0.9.0, to stay on it. See Docker image tags. |
DELEGARIS_PORT | 8080 | The host port the container is published on. |
Web server
| Variable | Default | Meaning |
|---|---|---|
PUBLIC_URL | http://localhost:8080 | The address people type into their browser, not the container's own. Decides whether cookies are marked Secure (only for https://), the Entra ID redirect address (<PUBLIC_URL>/auth/oidc/callback) and the links in Slack and Teams messages. |
TRUST_PROXY_HEADERS | false | Take the visitor's address from X-Forwarded-For (the right-most entry), for the activity log, sign-in throttling and where API tokens were last used from. Set to true behind a reverse proxy or load balancer. |
TLS_CERT_FILE, TLS_KEY_FILE | (empty) | A certificate and key file inside the container, to serve HTTPS directly instead of behind a proxy. Set both or neither. |
LISTEN_HOST | 0.0.0.0 | The address the server listens on inside the container. |
LISTEN_PORT | 8080 | The port the server listens on inside the container. |
LOG_LEVEL | INFO | How much the container logs: DEBUG, INFO, WARNING or ERROR. |
Storage and running more than one copy
| Variable | Default | Meaning |
|---|---|---|
DATABASE_URL | SQLite file in DATA_DIR | postgresql://user:password@host:5432/delegaris to keep everything in PostgreSQL, so two or more copies can share it. See High availability. |
DATA_DIR | /data | Where the SQLite database and its nightly backups are kept. Already set in the image (and to /var/lib/delegaris by the Linux package); leave it alone. |
SECRET_KEY | made once, kept in the database | Signs the short-lived cookies and tokens used during sign-in (the Entra ID handshake and the step between password and two-step code). If unset, one is generated and stored in the database, so every copy sharing it agrees. |
ENCRYPTION_KEY | made once, kept in /data/encryption.key | Encrypts the secrets kept in the database (AWS keys, the directory password, the Entra secret, authenticator secrets and so on). Any passphrase works; openssl rand -base64 32 makes a good one. Must be the same on every copy that shares a database. Keep a copy with your backups. |
NODE_NAME | the host name | How this copy is named in logs and in /healthz. Under Docker the host name is the container ID. |
LEASE_SECONDS | 90 | With several copies: how long after the active copy stops renewing the timed-work lease another copy takes over. |
UI_DIR | set in the image | Where the web interface files are. Leave it alone. |
Sign-in: general
| Variable | Default | Meaning | In the web UI |
|---|---|---|---|
AUTH_PROVIDERS | every provider that is filled in | Which ways in are switched on: ldap, oidc, local, demo. The local administrator stays on whenever LOCAL_ADMIN_PASSWORD is set, whatever this says. | Settings > Sign-in, Ways in |
ADMIN_GROUPS | (empty) | Groups whose members administer the service: AD group names, or Entra ID group object IDs or app roles. | Settings > Sign-in, Administrator groups |
ADMIN_USERS | (empty) | Individual sign-in names who administer the service. | Settings > Sign-in, Administrator users |
LOCAL_ADMIN_USERNAME | admin | The user name of the local administrator. | No |
LOCAL_ADMIN_PASSWORD | (empty) | Turns on the local administrator: the break-glass way in. Keep it set, with the password kept safe and two-step sign-in on; unset it only if you do not want a break-glass account. See Local administrator. | No |
SESSION_TTL_HOURS | 8 | How long a sign-in lasts. | No |
LOGIN_MAX_FAILURES | 5 | Failed sign-ins allowed per user name within the window before further attempts are refused. A single address is allowed five times as many. | No |
LOGIN_FAILURE_WINDOW_SECONDS | 300 | The window those failures are counted over. | No |
DEMO_USERS | (empty) | Demos and testing only. Password accounts with made-up groups: name:password:Group One,Group Two, optionally followed by :email; several separated by ;. Passwords cannot contain : or ;. Never set this on a real deployment. | No |
Sign-in: Active Directory
The simple form needs only LDAP_DOMAIN, LDAP_BIND_DN and LDAP_BIND_PASSWORD. The domain controllers are then found through the domain's DNS SRV records and the whole domain is searched. The other settings override parts of that for unusual directories. See Active Directory.
All of these except LDAP_TIMEOUT_SECONDS can be set under Settings > Sign-in instead, which overrides the environment. There, the CA certificate is pasted as PEM text rather than given as a file.
| Variable | Default | Meaning |
|---|---|---|
LDAP_DOMAIN | (empty) | The domain's DNS name, such as ad.example.com. |
LDAP_BIND_DN | (empty) | The service account: a plain name (svc-delegaris), user@domain or a full DN. An ordinary domain user is enough; it only reads. |
LDAP_BIND_PASSWORD | (empty) | That account's password. |
LDAP_URL | found through DNS | Domain controllers, with scheme and port, comma separated: ldaps://dc1.ad.example.com:636,ldaps://dc2.ad.example.com:636. |
LDAP_BASE_DN | made from the domain | Where to search for people, such as DC=ad,DC=example,DC=com. Required if LDAP_DOMAIN is not set. |
LDAP_GROUP_BASE_DN | same as LDAP_BASE_DN | Where to search for groups, if different. |
LDAP_USER_FILTER | matches sAMAccountName or userPrincipalName | The LDAP filter that finds a person by what they type. Must contain {username}. |
LDAP_START_TLS | false | Use STARTTLS on port 389 instead of LDAPS. |
LDAP_TLS_VERIFY | true | Check the domain controllers' certificates. The log warns when this is off. |
LDAP_CA_CERT_FILE | (empty) | A PEM file, mounted into the container, with the CA that issued the domain controllers' certificates. Needed for an internal CA. |
LDAP_ALLOW_INSECURE | false | Allow plain, unencrypted LDAP. Passwords then cross the network in clear text. For labs only. |
LDAP_NESTED_GROUPS | true | Count membership of groups inside groups. |
LDAP_TIMEOUT_SECONDS | 10 | How long to wait for a domain controller. |
Sign-in: Microsoft Entra ID
See Microsoft Entra ID for the app registration. All of these except OIDC_USERNAME_CLAIM can be set under Settings > Sign-in instead.
| Variable | Default | Meaning |
|---|---|---|
OIDC_TENANT_ID | (empty) | The directory (tenant) ID. |
OIDC_CLIENT_ID | (empty) | The application (client) ID. Setting it switches Entra ID sign-in on. |
OIDC_CLIENT_SECRET | (empty) | The client secret. |
OIDC_ISSUER | made from the tenant ID | For another OpenID Connect provider, such as AD FS: its issuer address, in place of OIDC_TENANT_ID. |
OIDC_SCOPES | openid profile email | Add User.Read if people are in more than 200 groups, so membership can be read from Microsoft Graph. |
OIDC_GROUPS_CLAIM | groups | The token claim that carries group memberships. The roles claim is always read as well. |
OIDC_USERNAME_CLAIM | preferred_username | The token claim used as the person's sign-in name. |
OIDC_BUTTON_LABEL | Sign in with Microsoft | The label on the sign-in button. |
OIDC_AUTO_SIGN_IN | false | Send people straight to Microsoft instead of showing the sign-in page. Only applies when Entra ID is the only way in (the local administrator does not count). /?manual=1 still shows the page. |
AWS
| Variable | Default | Meaning |
|---|---|---|
AWS_DEFAULT_REGIONS | eu-west-2 | Regions scanned for accounts that do not list their own. At least one is required. The first is also where the service calls AWS STS. |
INVENTORY_CACHE_SECONDS | 30 | How long a region's list of resources is reused before AWS is asked again. Raise it if AWS API rate limits ever show. |
AWS_MAX_WORKERS | 16 | How many AWS calls the service makes at once when listing accounts and regions. |
AWS_STARTUP_CHECK | true | Log the service's own AWS identity, or why it has none, when it starts. |
The service finds its own AWS credentials the same way the AWS CLI does, so the standard AWS variables also work. See The service's own identity.
| Variable | Meaning |
|---|---|
AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY | An IAM user's keys, for when no IAM role can be used. Keys saved under Accounts in the web UI override these. |
AWS_SESSION_TOKEN | The session token that goes with temporary keys. |
AWS_PROFILE, AWS_SHARED_CREDENTIALS_FILE, AWS_CONFIG_FILE | A mounted AWS CLI profile. The lines are in docker-compose.yml, commented out. |
AWS_EC2_METADATA_DISABLED | true stops the service using the EC2 instance role. |
AWS_ENDPOINT_URL | Sends every AWS call to another address. Used by the demo stack to talk to a simulated AWS. Do not set it on a real deployment. |
Keeping on, schedules and approvals
| Variable | Default | Meaning | In the web UI |
|---|---|---|---|
SCHEDULE_TAG_KEYS | Schedule | The tag key (or keys) your scheduler reads. | Settings > Schedules, Schedule tag |
KEEP_ON_MAX_HOURS | 24 | The furthest ahead someone may keep a resource on. | Settings > Schedules, Longest keep-on, in hours |
KEEP_ON_WARN_MINUTES | 15 | How long before the end of a keep-on the person is reminded. | Settings > Schedules, Reminder, in minutes before |
TIMEZONE | Europe/London | The time zone schedule hours are written in. The nightly backup and the weekly summary also run by it. | Settings > Schedules, Time zone |
REQUIRE_REASON | false | Make people give a reason when they keep something on. | Settings > Schedules |
APPROVAL_EXPIRES_HOURS | 8 | How long a request for approval waits for a decision before it lapses. | Settings > Approvals, Requests expire after, in hours |
GROUP_STEP_TIMEOUT_MINUTES | 20 | How long a server group start or stop waits on one step before the run fails. | No |
KEEP_ON_POLL_SECONDS | 30 | How often the background loop looks for work that has fallen due: keep-ons ending, bookings, group steps, approvals expiring. | No |
KEEP_ON_GIVE_UP_MINUTES | 120 | How long a stop that keeps failing at the end of a keep-on is retried before the service gives up and records the failure. | No |
KEEP_ON_WORKER | true | Whether this copy runs the background loop at all. Leave it on. With it off, this copy does no timed work, has no Slack buttons, and stops picking up sign-in, notification and AWS identity changes saved by other copies. | No |
Backups
| Variable | Default | Meaning |
|---|---|---|
BACKUP_ENABLED | true | Take a copy of the SQLite database every night. Does nothing with PostgreSQL; use the database's own backups. |
BACKUP_HOUR | 2 | The hour the backup runs, in the TIMEZONE time zone. |
BACKUP_KEEP | 14 | How many nightly backups to keep in /data/backups. |
BACKUP_S3_BUCKET | (empty) | Also upload each backup to this S3 bucket, with the service's own AWS identity. It then needs s3:PutObject on the bucket. |
BACKUP_S3_PREFIX | delegaris/ | The folder (key prefix) in the bucket. |
See Backups and health.
Slack
See Slack for creating the Slack app.
| Variable | Default | Meaning | In the web UI |
|---|---|---|---|
SLACK_BOT_TOKEN | (empty) | The bot token (xoxb-…) of a Slack app with the scopes chat:write and users:read.email. | No |
SLACK_APP_TOKEN | (empty) | An app-level token (xapp-…) with connections:write, for Socket Mode. Adds the +1 hour and +2 hours buttons to reminders and Approve and Decline buttons to approval requests. | No |
SLACK_FALLBACK_CHANNEL | (empty) | A channel (ID or #name) for messages to people Slack cannot find by email. The app must be a member of it. | No |
SLACK_SUMMARY_CHANNEL | (empty) | Where the weekly summary is posted on Monday mornings. | Settings > Notifications, Weekly summary channel |
SLACK_ALERT_CHANNEL | (empty) | Where alerts go when credentials, timed stops or backups fail. Empty uses the fallback channel. | Settings > Notifications, Alerts channel |
SLACK_APPROVALS_CHANNEL | (empty) | Where every request for approval is posted, as well as to the approvers directly. | Settings > Approvals, Approvals channel |
LOCAL_ADMIN_EMAIL | (empty) | An email address for the local administrator, so it can receive Slack messages while you test. | No |
SLACK_API_URL | https://slack.com/api | The Slack API address. Only for testing. | No |
Microsoft Teams and webhooks
All three are starting values; once saved under Settings > Notifications, the saved values apply. See Teams and webhooks.
| Variable | Default | Meaning |
|---|---|---|
TEAMS_WEBHOOK_URL | (empty) | A Teams channel's Workflows "when a webhook request is received" address. |
WEBHOOK_URL | (empty) | Any address that should receive every event as JSON. |
WEBHOOK_SECRET | (empty) | When set, each webhook post carries an X-Delegaris-Signature: sha256=… HMAC of its body. |
Settings that are only in the web UI
Some things have no environment variable and are set only under Settings: friendly names, protected resources, separate start and stop tags, the two-step sign-in policy, administrator and auditor roles given to groups, who may have API tokens, the activity log export to S3, and branding.