Deploy on one server
This is the complete production shape for one server: web, database, persistent data, and a combined worker share one Docker host. Trellum is distributed under AGPL-3.0-only. You can use the published release images or build the images from the matching source tag:
- Pull the release images (fastest — nothing builds on your machine). The Compose file and operational scripts come from the same tagged source checkout, so the install has everything it needs.
- Build from source (AGPL-3.0-only; no image registry required). Compose builds both images from the checkout.
Either way, also check the requirements from the overview first.
The default storage needs Docker Engine 26+. Docker Engine 25 can use the host-folder setup below with report isolation enabled. Configure that setup before any build-and-start command.
Option A: Pull the published images
Use the matching v0.11.0 source tag, which includes
docker-compose.release.yml. The matching source checkout also supplies backup and upgrade
scripts and the other files needed to operate the installation. This path
requires Docker Compose v2.24 or newer.
Set TRELLUM_VERSION in .env to the exact published tag. The release overlay
uses that value for both images and removes the source build definitions. It
ignores TRELLUM_IMAGE and TRELLUM_RUNNER_IMAGE, so stale local image
settings cannot change the selected release.
1. Get the matching Compose files
TRELLUM_VERSION=v0.11.0
git clone --depth 1 --branch "$TRELLUM_VERSION" https://github.com/trellumhq/trellum.git
cd trellum
cp .env.example .env
cat >> .env <<EOF
TRELLUM_VERSION=$TRELLUM_VERSION
COMPOSE_FILE=docker-compose.yml:docker-compose.release.yml
EOF
Fill in the other required settings in step 2, then verify both signatures as described in Verify what you received. The commands below pull the matched portal and runner images before startup.
Option B: Build from source
The source build is the complete product. docker-compose.yml already
knows how to build the image itself; there is no separate Dockerfile step.
Clone and prepare .env
TRELLUM_VERSION=v0.11.0
git clone --depth 1 --branch "$TRELLUM_VERSION" https://github.com/trellumhq/trellum.git
cd trellum
cp .env.example .env
Fill in the settings (below), then build and start
Run bash scripts/check-docker.sh before starting (or add --bind-data for
the host-folder setup). Fill in .env using the settings required for this
install path from
step 2
below, then build and start with:
GIT_SHA=$(git rev-parse HEAD) \
GIT_BRANCH=$(git rev-parse --abbrev-ref HEAD) \
BUILD_TIME=$(date -u +%FT%TZ) \
docker compose up -d --build
The GIT_SHA / GIT_BRANCH / BUILD_TIME variables are optional but worth
setting: without them a self-built image reports its own version as
unknown on /api/version and in manage.py doctor, which is the first
thing an upgrade or support conversation asks for. Leave TRELLUM_IMAGE
unset — the default (trellum:dev) is the tag docker compose build already
produces.
Running a second, independent instance on the same host (a staging build, or validating a change before it replaces production)? Give it its own compose project name, port and image tags so the two never share containers, volumes or images:
docker compose -p trellum-staging up -d --build
# .env: TRELLUM_PORT=8060, TRELLUM_IMAGE=trellum-staging:dev,
# TRELLUM_RUNNER_IMAGE=trellum-staging-runner:dev
-p always overrides the project name compose would otherwise pick, so this
is safe to run from the same checkout as an existing instance. Tear the extra
instance down with docker compose -p trellum-staging down -v — never bare
down from a directory that also serves a production instance.
2. Fill in the settings
Open .env and set these required values. Everything else has a working default
and is covered in the
configuration reference.
| Setting | What it is |
|---|---|
TRELLUM_VERSION |
For Option A, the exact published release tag selected for both images. |
TRELLUM_IMAGE / TRELLUM_RUNNER_IMAGE |
Option B image tags when building from source. Option A's release overlay sets both image names from TRELLUM_VERSION. |
PORTAL_BASE_URL |
The public address people will visit, e.g. https://bi.example.com. Used to build links in invitation and password-reset emails, and to decide whether cookies are marked secure. |
ALLOWED_HOSTS |
The hostnames the portal will answer on. A request arriving under any other name is refused, which is what stops someone pointing their own domain at your instance. |
POSTGRES_PASSWORD |
The password for the bundled database. Any strong value; you will not type it again. |
SECRET_ENCRYPTION_KEY |
Encrypts the credentials the portal stores for you — data source passwords, repository tokens, SSO secrets. |
SESSION_SECRET_KEY |
Signs session cookies and the one-time links in invitation and password-reset emails, so they cannot be forged. |
DOCKER_GID |
A number identifying the group on your machine that is allowed to use Docker. The worker runs each report build in its own throwaway container, so it needs that permission. See finding it below. |
Generate the two keys with:
# SECRET_ENCRYPTION_KEY
python -c "import base64,os; print(base64.urlsafe_b64encode(os.urandom(32)).decode())"
# SESSION_SECRET_KEY
python -c "import secrets; print(secrets.token_urlsafe(50))"
Finding DOCKER_GID
On most Linux hosts:
getent group docker | cut -d: -f3
That prints a number — often 988, 999 or 130. Put that number in .env.
If it prints nothing, the group has another name or does not exist. Ask the Docker socket itself which group owns it, which is always correct:
stat -c '%g' /var/run/docker.sock
Platform notes:
- Docker Desktop (macOS, Windows) — there is no host
dockergroup. Use thestatcommand above inside the Docker VM, or simply setDOCKER_GID=0; the socket is owned by root there. Docker Desktop is a development setup, not how you should run this in production. - Rootless Docker — use
stat -c '%g' $XDG_RUNTIME_DIR/docker.sock. - Podman — use the socket path from
podman info --format '{{.Host.RemoteSocket.Path}}'.
Note
We ask for this rather than working it out ourselves because Docker grants group membership when it creates the container, before any of our code runs — and the portal deliberately starts as an unprivileged user, so it cannot give itself the permission afterwards.
Danger
Back up SECRET_ENCRYPTION_KEY somewhere separate from your database
backups. Lose it and every stored credential becomes unreadable; keep both
in one place and a single leak exposes everything.
3. Start it
Check the daemon before changing the stack. For default named-volume storage:
bash scripts/check-docker.sh
For the host-folder setup, use bash scripts/check-docker.sh --bind-data.
For Option A, pull and start the release images without building them locally:
docker compose pull
docker compose up -d --no-build
Because COMPOSE_FILE is saved in .env, later pull, backup and restart
commands keep using the release overlay. With host-folder storage,
set COMPOSE_FILE=docker-compose.yml:docker-compose.release.yml:docker-compose.bind-data.yml.
With an external database, append docker-compose.external-db.yml as well.
Upgrade helper compatibility
This path selects images with TRELLUM_VERSION. The current upgrade and
rollback helpers change TRELLUM_IMAGE and TRELLUM_RUNNER_IMAGE, which
this overlay ignores;
those helpers cannot switch the selected release without adaptation.
Follow the limitations in the upgrade guide
and verify any upgrade/rollback procedure on a separate instance first.
For Option B, the docker compose up -d --build command in that section has
already started the stack.
Services start in order: the database, then a one-shot schema migration, then the sandbox image, then the web server and the report worker.
Docker 25 with host-folder storage
Use matching deployment files and images from a release containing this feature. Adding this override to an earlier image does not change its worker version check.
This Linux setup keeps report builds in isolated containers. Each build gets only its own directories, its studio project, and authorized shared data. The worker accepts API 1.44 (Docker 25) for bind mounts; named volumes still need API 1.45 (Docker 26) for their subdirectory mounts. Use a maintained, patched engine; versions older than Docker 25 are not supported.
For a new installation, prepare an empty directory on the Docker daemon's host, owned by the application's user. Use a separate directory for each independent installation:
bash scripts/check-docker.sh --bind-data
sudo install -d -o 10001 -g 10001 -m 0750 /srv/trellum/data
For Option A, add these settings to .env (the order keeps the release
selection and host-folder storage active for every Compose command):
COMPOSE_FILE=docker-compose.yml:docker-compose.release.yml:docker-compose.bind-data.yml
TRELLUM_DATA_HOST_PATH=/srv/trellum/data
For Option B, use COMPOSE_FILE=docker-compose.yml:docker-compose.bind-data.yml
instead; the source-build path does not include the release overlay.
Leave TRELLUM_DATA_VOLUME unset. The override clears it on workers and
runners so they discover the host folder. TRELLUM_DATA_HOST_PATH must be
an absolute path on the daemon host, not a path on a remote client machine.
If the host enforces SELinux, ensure its policy allows all Trellum containers
to share this directory; do not disable SELinux to work around permissions.
Verify the merged configuration with docker compose --profile split config
before starting. Every /data mount must be a bind to the same directory;
the backup service's mount remains read-only. The override preserves the
backup volume and the worker/runner Docker sockets. It refuses to create a
missing host directory automatically.
Then continue with the normal pull and startup commands. Keeping
COMPOSE_FILE in .env ensures later backups, upgrades and restarts keep using
this storage. Explicit -f arguments override that setting: if you use them,
include -f docker-compose.release.yml and -f docker-compose.bind-data.yml
for Option A, or the bind-data override alone for Option B. With an external
database, append :docker-compose.external-db.yml to COMPOSE_FILE.
Moving an existing named volume
Changing the mount does not move existing files. Before adding the override:
- Verify a current database backup and data archive, following Backups. Keep the existing named volume.
- Record the volume backing
/datafrom the existing web container:docker inspect "$(docker compose ps -q web)" --format '{{json .Mounts}}'. Use the actual volume name; a custom Compose project changes its prefix. - Stop every service that can write data, including workers and runners on
other hosts. Drain active builds first. Use
docker compose --profile split stopfor a single-host installation. Do not usedown -v. - Prepare an empty destination directory. Copy the recorded volume into
it while stopped, preserving ownership, permissions and symlinks. For
example, replace
ACTUAL_DATA_VOLUMEbelow and use an already available Trellum image that includescpanddiff:
bash
sudo install -d -o 10001 -g 10001 -m 0750 /srv/trellum/data
docker run --rm --user 0 --entrypoint sh \
--mount type=volume,src=ACTUAL_DATA_VOLUME,dst=/from,readonly \
--mount type=bind,src=/srv/trellum/data,dst=/to \
YOUR_TRELLUM_IMAGE -ec 'cp -a /from/. /to/; diff -qr /from /to'
- After verifying the copy and its ownership, add the
.envsettings above, run the compatibility check and inspect the merged Compose configuration. Start with an image containing this compatibility change, then verifymanage.py doctor, a report build and publication, and a new backup.
Retain the old volume until validation finishes. If reverting after writes have resumed, stop the services and reconcile the newer files first; simply pointing back at the old volume would discard those newer writes.
4. Harden the sandbox network
Report builds run your code in throwaway containers. On a cloud VM this step is mandatory — it blocks those containers from the instance metadata endpoint and from services on the host:
sudo docker/harden-sandbox-net.sh
Warning
Skipping this on a cloud VM leaves the instance metadata endpoint reachable from report code. Run it before the first build.
See Report sandboxing for exactly what a build container can and cannot reach.
5. First run
Open your address. A portal with no accounts sends you straight to a setup wizard:
- Welcome — what the next few steps do.
- Readiness — the same checks as
manage.py doctor. A failing check is shown with what to do about it, but never blocks setup — a portal whose worker hasn't started yet still installs. - Organization — name and slug. The slug is permanent: it keys the directory tree the organization's data lives under.
- Your account — the instance operator, and an admin of the organization from the previous step.
- Instance settings (skippable) — instance name, public URL, and mail delivery, with a button to send a test email. Everything here stays editable afterward under System.
- Done — the hub, with a getting-started checklist.
The wizard is open to whoever reaches a user-less instance first, so set the portal up before exposing its port — or keep it behind your reverse proxy until step 4 is done. It closes permanently the moment an account exists.
For an unattended install, skip the wizard entirely:
docker compose exec web python manage.py bootstrap \
--email ops@example.com --password '...' --org-name "Acme" --org-slug acme
Then verify the install end to end:
docker compose exec web python manage.py doctor
doctor checks database connectivity, encryption keys, the data volume, the
sandbox image, and the worker heartbeat, and prints what to fix when something
is off.
Note
A retention: cleanup has never run failure right after a fresh
install is expected, not a problem: cleanup runs on the nightly
CLEANUP_CRON schedule, so a brand-new instance goes green on that check
after its first scheduled run. To clear it immediately instead of
waiting, run docker compose exec web python manage.py cleanup once by
hand (plain, not --dry-run — a dry run deliberately does not record
that cleanup ran, so it will not clear this check).
Next
- Configuration reference — every setting
- Verify what you received — signatures and SBOM
- Connecting a repository — your first reports