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
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
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.yamltemplate creates one with what it needs:sts:AssumeRoleonDelegarisRole,pricing:GetProductsfor cost estimates, and optionallys3:PutObjecton 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 loginworks: 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/backupswith 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 /healthzreports 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:
| Part | What to create |
|---|---|
| Database | RDS for PostgreSQL, Multi-AZ, the smallest instance class, automated backups on |
| Compute | Two EC2 instances in two Availability Zones, in an Auto Scaling group of two, each running the container |
| Identity | The hub-role.yaml instance profile on both |
| Configuration | One .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 point | An 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.