Skip to main content

Quick start: Docker Compose

Delegaris is one Docker image, goodhallsolutions/delegaris. Docker Compose is the recommended way to run it. The host needs two files: docker-compose.yml and an .env file with your settings.

This page gets a single copy running with the local administrator sign-in, which is enough to connect AWS accounts and look around. Directory sign-in, HTTPS and the rest come after.

Prerequisites​

  • Docker Engine with the Compose plugin.
  • A small Linux host on linux/amd64, which is what the published image is built for. One container is light: a machine the size of an AWS t3.small is plenty.
  • Outbound access to the AWS APIs. Later, also to your domain controllers on port 636 (for Active Directory sign-in) and to slack.com (for Slack).

If the host is an EC2 instance and you want the container to use the instance's IAM role, read Docker on EC2 as well.

Step 1: create docker-compose.yml​

Make a folder for Delegaris and save this as docker-compose.yml in it:

services:
delegaris:
image: goodhallsolutions/delegaris:${DELEGARIS_TAG:-latest}
restart: unless-stopped
env_file: .env
# On an EC2 instance, the container only gets the instance's IAM role if the
# instance's metadata hop limit is 2. The alternative is to share the host's
# network: uncomment the next line and remove "ports:".
# network_mode: host
ports:
- "${DELEGARIS_PORT:-8080}:8080"
# To sign in to AWS with an AWS CLI profile from the host instead, uncomment
# these and the matching volume below.
# environment:
# AWS_SHARED_CREDENTIALS_FILE: /aws/credentials
# AWS_CONFIG_FILE: /aws/config
# AWS_PROFILE: delegaris
volumes:
- delegaris-data:/data
# - /home/ec2-user/.aws:/aws:ro
# Uncomment if your domain controllers use an internal CA (see LDAP_CA_CERT_FILE):
# - ./certs/corp-root-ca.pem:/certs/corp-root-ca.pem:ro
read_only: true
tmpfs:
- /tmp
cap_drop:
- ALL
security_opt:
- no-new-privileges:true

volumes:
delegaris-data:

The container runs as an unprivileged user with a read-only file system; the only place it writes is the /data volume.

Step 2: create .env​

In the same folder, create .env:

# The address people type into their browser. For a first look over plain HTTP,
# use the host's own address and port.
PUBLIC_URL=http://delegaris-host.corp.example:8080

# Turns on the local administrator sign-in (user name: admin).
LOCAL_ADMIN_PASSWORD=choose-a-long-password

# Regions to look in, for accounts that do not list their own.
AWS_DEFAULT_REGIONS=eu-west-2

PUBLIC_URL matters more than it looks: it decides whether the sign-in cookie is marked Secure, the redirect address for Microsoft Entra ID, and the links in Slack and Teams messages. Set it to exactly the address people will use. When you put Delegaris behind HTTPS, change it to the https:// address; see Behind a reverse proxy.

The service will not start without at least one way to sign in. LOCAL_ADMIN_PASSWORD is the quickest. Every other setting is listed in Configuration.

tip

Keep .env readable only by the people who administer the host (chmod 600 .env). It holds passwords.

Step 3: start it​

docker compose pull
docker compose up -d

This runs the latest tag. To stay on a known version, set DELEGARIS_TAG in .env; see Docker image tags.

Check the log:

docker compose logs -f delegaris

You should see a line like this, followed by one saying which AWS identity the service found (or why it found none):

Delegaris 0.9.0 starting as 3f2a1c9e0b7d; database: SQLite file /data/delegaris.db; sign-in providers: local

A warning that the local administrator sign-in is enabled is expected; it appears at every start while LOCAL_ADMIN_PASSWORD is set. If PUBLIC_URL is not https://, the log also warns that session cookies are not marked Secure.

If the configuration cannot work (no sign-in provider at all, LDAP without TLS, and so on), the service exits at once and the log lists each problem under Configuration problems. With restart: unless-stopped, Docker keeps starting it again, and it keeps exiting with the same log, until the setting is fixed. Fix .env and run docker compose up -d again.

docker compose ps shows the container as healthy once it answers on /healthz.

Step 4: sign in​

Open the address you gave as PUBLIC_URL and sign in as admin with the password from .env.

The first page to visit is Accounts. The top of it shows how the service signs in to AWS, and Add an account connects the first account. See How Delegaris reaches AWS and Adding accounts.

Where your data lives​

Everything Delegaris stores is in the delegaris-data volume, mounted at /data: accounts, access rules, keep-ons in progress, the tag values it has taken off resources, and the activity log. It is a single SQLite file, /data/delegaris.db, with nightly backups beside it in /data/backups. See Backups and health.

To run two or more copies for resilience, they share a PostgreSQL database instead. See High availability.

Next steps​