Self-hosting Delegaris

A container or a Linux service, a narrow role per account, and your directory for sign-in. This page is the shape of it; the full guide is in the documentation.

What it runs on

Any Linux host that can reach AWS and your directory, running Docker or the Linux package. On AWS, a t3.small EC2 instance is plenty. The Docker image is linux/amd64, built on python:3.12-slim, runs as an unprivileged user, and keeps everything it stores in the /data volume (or in PostgreSQL). On a Graviton (t4g) or other arm64 server, use the Linux package, which runs on x86_64 and arm64.

Install with Docker Compose

docker compose pull
docker compose up -d

The compose file runs goodhallsolutions/delegaris:latest read-only with every capability dropped. A minimal .env to start with sets PUBLIC_URL, a LOCAL_ADMIN_PASSWORD for the first sign-in, and AWS_DEFAULT_REGIONS. Pin a version with DELEGARIS_TAG when you are ready to stay on one. Both files are in the Docker Compose quick start, and every setting is on the Configuration page.

Or install on Linux, without Docker

curl -fsSL https://github.com/Goodhall-Solutions/delegaris/releases/latest/download/install.sh | sudo bash

A native package with its own Python, installed as a hardened systemd service on Ubuntu 22.04 and 24.04, Debian 12, RHEL, Rocky and Alma 9, or Amazon Linux 2023, on x86_64 or arm64. It prints the address and a generated administrator password; running it again upgrades, after backing the database up. sudo /opt/delegaris/uninstall.sh removes it. See Linux and Uninstalling in the docs.

The service's own AWS identity

Delegaris needs an identity of its own only to assume roles in accounts, to read AWS list prices for cost estimates, and (if you want them) to upload backups and the activity log to S3. In order of preference:

  • The instance's IAM role (EC2) or task role (ECS). The iam/hub-role.yaml template creates one with what it needs: sts:AssumeRole on DelegarisRole, pricing:GetProducts for cost estimates, and optionally s3:PutObject on the backup and activity-log buckets. A container only sees the instance role if the instance metadata hop limit is 2; the Accounts page tells you if that is what is wrong, with the one-line fix.
  • IAM Identity Center from your start URL, the way aws sso login works: approve in the browser, pick the accounts to add, and the service renews its credentials itself.
  • Access keys pasted in the UI (or in the environment), including temporary keys with a session token for a quick trial.

Each account

Add an account with its 12-digit ID, choose the services to manage (EC2, RDS, Auto Scaling, ECS, EKS, Redshift, SageMaker, Lightsail) and the regions, and how the service gets in: a role to assume (the iam/member-account-role.yaml template, filled in for you, deployable as a StackSet across many accounts), the account's own access keys, or an Identity Center permission set. Test connection tries it before anything is saved.

Sign-in

Set the LDAP_* variables for Active Directory (LDAPS, a read-only service account, nested groups by default) and/or the OIDC_* variables for Microsoft Entra ID (an app registration with a groups claim), or set them up under Settings > Sign-in, which can also test the directory. Administrators are named under Settings > Sign-in > Administrators, or by ADMIN_GROUPS and ADMIN_USERS in the environment; once the Sign-in settings are saved, the saved lists replace them. Keep LOCAL_ADMIN_PASSWORD set as the break-glass sign-in, with its password kept safe and two-step sign-in on; unset it only if you do not want a break-glass account.

Day-two operations

  • Backups: a copy of the SQLite database is written nightly to /data/backups (/var/lib/delegaris/backups with the Linux package), optionally uploaded to S3. With PostgreSQL, use the database's own backups.
  • Upgrades: pull the new tag and docker compose up -d, or run the Linux installer again; database changes apply on start.
  • Health: GET /healthz reports the version, whether the timed work is running, and with several copies which one holds the lease.
  • Alerts: credentials failing, a stop that could not be finished, a missed backup: to Slack, Teams or the webhook.

Highly available, on AWS

Run two copies against one PostgreSQL database and they take turns at the timed work through a lease; if the active copy's server dies, the other takes over within about two minutes and nothing is lost, only delayed. The shape that survives the loss of an instance, an Availability Zone or the database server:

PartWhat to create
DatabaseRDS for PostgreSQL, Multi-AZ, the smallest instance class, automated backups on
ComputeTwo EC2 instances in two Availability Zones, in an Auto Scaling group of two, each running the container
IdentityThe hub-role.yaml instance profile on both
ConfigurationOne .env for both, kept in SSM Parameter Store, with DATABASE_URL pointing at RDS and the same ENCRYPTION_KEY on every copy (a copy whose key does not match the stored secrets refuses to start)
Entry pointAn Application Load Balancer with an ACM certificate, health check GET /healthz; PUBLIC_URL set to its address and TRUST_PROXY_HEADERS=true

Sessions live in the database, so no stickiness is needed, and a session started on one copy works on the other. The same shape runs on ECS Fargate without instances to look after. The documentation has the details under High availability.

You run the server

Delegaris never has a copy of anything: rules, keep-ons, sessions and the audit log are in your database on your server; the only outbound connections are to AWS, your directory and the notification destinations you set. Back up the volume (or the database) and you have everything.