Skip to main content

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.

note

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.

VariableDefaultMeaning
DELEGARIS_TAGlatestWhich image tag to run. Set a version, such as 0.9.0, to stay on it. See Docker image tags.
DELEGARIS_PORT8080The host port the container is published on.

Web server​

VariableDefaultMeaning
PUBLIC_URLhttp://localhost:8080The 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_HEADERSfalseTake 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_HOST0.0.0.0The address the server listens on inside the container.
LISTEN_PORT8080The port the server listens on inside the container.
LOG_LEVELINFOHow much the container logs: DEBUG, INFO, WARNING or ERROR.

Storage and running more than one copy​

VariableDefaultMeaning
DATABASE_URLSQLite file in DATA_DIRpostgresql://user:password@host:5432/delegaris to keep everything in PostgreSQL, so two or more copies can share it. See High availability.
DATA_DIR/dataWhere 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_KEYmade once, kept in the databaseSigns 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_KEYmade once, kept in /data/encryption.keyEncrypts 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_NAMEthe host nameHow this copy is named in logs and in /healthz. Under Docker the host name is the container ID.
LEASE_SECONDS90With several copies: how long after the active copy stops renewing the timed-work lease another copy takes over.
UI_DIRset in the imageWhere the web interface files are. Leave it alone.

Sign-in: general​

VariableDefaultMeaningIn the web UI
AUTH_PROVIDERSevery provider that is filled inWhich 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_USERNAMEadminThe 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_HOURS8How long a sign-in lasts.No
LOGIN_MAX_FAILURES5Failed 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_SECONDS300The 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.

VariableDefaultMeaning
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_URLfound through DNSDomain controllers, with scheme and port, comma separated: ldaps://dc1.ad.example.com:636,ldaps://dc2.ad.example.com:636.
LDAP_BASE_DNmade from the domainWhere to search for people, such as DC=ad,DC=example,DC=com. Required if LDAP_DOMAIN is not set.
LDAP_GROUP_BASE_DNsame as LDAP_BASE_DNWhere to search for groups, if different.
LDAP_USER_FILTERmatches sAMAccountName or userPrincipalNameThe LDAP filter that finds a person by what they type. Must contain {username}.
LDAP_START_TLSfalseUse STARTTLS on port 389 instead of LDAPS.
LDAP_TLS_VERIFYtrueCheck 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_INSECUREfalseAllow plain, unencrypted LDAP. Passwords then cross the network in clear text. For labs only.
LDAP_NESTED_GROUPStrueCount membership of groups inside groups.
LDAP_TIMEOUT_SECONDS10How 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.

VariableDefaultMeaning
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_ISSUERmade from the tenant IDFor another OpenID Connect provider, such as AD FS: its issuer address, in place of OIDC_TENANT_ID.
OIDC_SCOPESopenid profile emailAdd User.Read if people are in more than 200 groups, so membership can be read from Microsoft Graph.
OIDC_GROUPS_CLAIMgroupsThe token claim that carries group memberships. The roles claim is always read as well.
OIDC_USERNAME_CLAIMpreferred_usernameThe token claim used as the person's sign-in name.
OIDC_BUTTON_LABELSign in with MicrosoftThe label on the sign-in button.
OIDC_AUTO_SIGN_INfalseSend 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​

VariableDefaultMeaning
AWS_DEFAULT_REGIONSeu-west-2Regions 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_SECONDS30How 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_WORKERS16How many AWS calls the service makes at once when listing accounts and regions.
AWS_STARTUP_CHECKtrueLog 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.

VariableMeaning
AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEYAn IAM user's keys, for when no IAM role can be used. Keys saved under Accounts in the web UI override these.
AWS_SESSION_TOKENThe session token that goes with temporary keys.
AWS_PROFILE, AWS_SHARED_CREDENTIALS_FILE, AWS_CONFIG_FILEA mounted AWS CLI profile. The lines are in docker-compose.yml, commented out.
AWS_EC2_METADATA_DISABLEDtrue stops the service using the EC2 instance role.
AWS_ENDPOINT_URLSends 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​

VariableDefaultMeaningIn the web UI
SCHEDULE_TAG_KEYSScheduleThe tag key (or keys) your scheduler reads.Settings > Schedules, Schedule tag
KEEP_ON_MAX_HOURS24The furthest ahead someone may keep a resource on.Settings > Schedules, Longest keep-on, in hours
KEEP_ON_WARN_MINUTES15How long before the end of a keep-on the person is reminded.Settings > Schedules, Reminder, in minutes before
TIMEZONEEurope/LondonThe time zone schedule hours are written in. The nightly backup and the weekly summary also run by it.Settings > Schedules, Time zone
REQUIRE_REASONfalseMake people give a reason when they keep something on.Settings > Schedules
APPROVAL_EXPIRES_HOURS8How long a request for approval waits for a decision before it lapses.Settings > Approvals, Requests expire after, in hours
GROUP_STEP_TIMEOUT_MINUTES20How long a server group start or stop waits on one step before the run fails.No
KEEP_ON_POLL_SECONDS30How often the background loop looks for work that has fallen due: keep-ons ending, bookings, group steps, approvals expiring.No
KEEP_ON_GIVE_UP_MINUTES120How 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_WORKERtrueWhether 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​

VariableDefaultMeaning
BACKUP_ENABLEDtrueTake a copy of the SQLite database every night. Does nothing with PostgreSQL; use the database's own backups.
BACKUP_HOUR2The hour the backup runs, in the TIMEZONE time zone.
BACKUP_KEEP14How 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_PREFIXdelegaris/The folder (key prefix) in the bucket.

See Backups and health.

Slack​

See Slack for creating the Slack app.

VariableDefaultMeaningIn 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_URLhttps://slack.com/apiThe 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.

VariableDefaultMeaning
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.