GeezerVison

The World Wide Web, restored to 800 pixels of glory.

GeezerVison is showing trigger.dev — Docker compose - Trigger.dev

The following instructions will use docker compose to spin up a Trigger.dev instance. Make sure to read the self-hosting overview first. As self-hosted deployments tend to have unique requirements and configurations, we don’t provide specific advice for securing your deployment, scaling up, or improving reliability. Should the burden ever get too much, we’d be happy to see you on Trigger.dev cloud where we deal with these concerns for you. Warning: This guide alone is unlikely to result in a production-ready deployment. Security, scaling, and reliability concerns are not fully addressed here.

What’s new?

Goodbye v3, hello v4! We made quite a few changes:

Much simpler setup. The provider and coordinator are now combined into a single supervisor. No more startup scripts, just docker compose up.
Automatic container cleanup. The supervisor will automatically clean up containers that are no longer needed.
Support for multiple worker machines. This is a big one, and we’re very excited about it! You can now scale your workers horizontally as needed.
Resource limits enforced by default. This means that tasks will be limited to the total CPU and RAM of the machine preset, preventing noisy neighbours.
No direct Docker socket access. The compose file now comes with Docker Socket Proxy by default. Yes, you want this.
No host networking. All containers are now running with network isolation, using only the network access they need.
No checkpoint support. This was only ever experimental when self-hosting and not recommended. It caused a bunch of issues. We decided to focus on the core features instead.
Built-in container registry and object storage. You can now deploy and execute tasks without needing third party services for this.
Improved CLI commands. You don’t need any additional flags to deploy anymore, and there’s a new command to easily switch between profiles.
Whitelisting for GitHub OAuth. Any whitelisted email addresses will now also apply to sign ins via GitHub, unlike v3 where they only applied to magic links.

Requirements

These are the minimum requirements for running the webapp and worker components. They can run on the same, or on separate machines. It’s fine to run everything on the same machine for testing. To be able to scale your workers, you will want to run them separately.

Prerequisites

To run the webapp and worker components, you will need:

Docker 20.10.0+
Docker Compose 2.20.0+

Webapp

This machine will host the webapp, postgres, redis, and related services.

3+ vCPU
6+ GB RAM

Worker

This machine will host the supervisor and all of the runs.

4+ vCPU
8+ GB RAM

How many workers and resources you need will depend on your workloads and concurrency requirements. For example:

10 concurrency x small-1x (0.5 vCPU, 0.5 GB RAM) = 5 vCPU and 5 GB RAM
20 concurrency x small-1x (0.5 vCPU, 0.5 GB RAM) = 10 vCPU and 10 GB RAM
100 concurrency x small-1x (0.5 vCPU, 0.5 GB RAM) = 50 vCPU and 50 GB RAM
100 concurrency x small-2x (1 vCPU, 1 GB RAM) = 100 vCPU and 100 GB RAM

You may need to spin up multiple workers to handle peak concurrency. The good news is you don’t have to know the exact numbers upfront. You can start with a single worker and add more as needed.

Setup

Webapp

Clone the repository

git clone --depth=1 https://github.com/triggerdotdev/trigger.dev
cd trigger.dev/hosting/docker

Create a .env file and generate secrets

cp .env.example .env

# Fills the required secrets in .env with strong, unique values.
# Safe to re-run - it never overwrites a secret you've already set.
./generate-secrets.sh

The stack ships no working default credentials. generate-secrets.sh fills the application secrets and the bundled datastore passwords with strong, unique values. Keep them safe - rotating the encryption key or session secret later will invalidate existing sessions and encrypted data.

Start the webapp

cd webapp
docker compose up -d

Configure the webapp using the environment variables in your .env file, then apply the changes:

docker compose up -d

You should now be able to access the webapp at http://localhost:8030. When logging in, check the container logs for the magic link:

docker compose logs -f webapp

(optional) To initialize a new project, run the following command:

npx trigger.dev@latest init -p <project-ref> -a http://localhost:8030

Worker

Clone the repository

git clone --depth=1 https://github.com/triggerdotdev/trigger.dev
cd trigger.dev/hosting/docker

Create a .env file

cp .env.example .env

Start the worker

cd worker
docker compose up -d

Configure the supervisor using the environment variables in your .env file, including the worker token.

For a split webapp/worker setup, set MANAGED_WORKER_SECRET on the worker to the same value as the webapp’s MANAGED_WORKER_SECRET. Don’t run generate-secrets.sh on the worker host - it would create a mismatched value and the worker would fail to authenticate.

Apply the changes:

docker compose up -d

Repeat as needed for additional workers.

Combined

If you want to run the webapp and worker on the same machine, just replace the up command with the following:

# Run this from the /hosting/docker directory
docker compose -f webapp/docker-compose.yml -f worker/docker-compose.yml up -d

Worker token

When running the combined stack, worker bootstrap is handled automatically. When running the webapp and worker separately, you will need to manually set the worker token. On the first run, the webapp will generate a worker token and store it in a shared volume. It will also print the token to the console. It should look something like this:

==========================
Trigger.dev Bootstrap - Worker Token

WARNING: This will only be shown once. Save it now!

Worker group:
bootstrap

Token:
tr_wgt_fgfAEjsTmvl4lowBLTbP7Xo563UlnVa206mr9uW6

If using docker compose, set:
TRIGGER_WORKER_TOKEN=tr_wgt_fgfAEjsTmvl4lowBLTbP7Xo563UlnVa206mr9uW6

Or, if using a file:
TRIGGER_WORKER_TOKEN=file:///home/node/shared/worker_token

==========================

You can then uncomment and set the TRIGGER_WORKER_TOKEN environment variable in your .env file. Don’t forget to restart the worker container for the changes to take effect:

# Run this from the /hosting/docker/worker directory
docker compose down
docker compose up -d

Creating additional worker groups

To create additional worker groups beyond the bootstrap group, use the admin API endpoint. This requires admin privileges. Making a user admin:

New users: Set ADMIN_EMAILS environment variable (regex pattern) before user creation.
Existing users: Set admin = true in the user table in your database.

Creating a worker group:

api_url=http://localhost:8030
wg_name=my-worker
admin_pat=tr_pat_...

curl -X POST \
  "$api_url/admin/api/v1/workers" \
  -H "Authorization: Bearer $admin_pat" \
  -H "Content-Type: application/json" \
  -d "{\"name\": \"$wg_name\"}"

The response includes a token field if the worker group is newly created.

Registry setup

The registry is used to store and pull deployment images. When testing the stack locally, the defaults should work out of the box. When deploying to production, you will need to set the correct URL and generate secure credentials for the registry.

Default settings

The default settings for the registry are:

Registry: localhost:5000
Username: registry-user
Password: very-secure-indeed

You should change these before deploying to production, especially the password. You can find more information about how to do this in the official registry docs. Note: This will require modifying the default .htpasswd file located at ./hosting/docker/registry/auth.htpasswd of the repo root.

Logging in

When self-hosting, builds run locally. You will have to login to the registry on every machine that runs the deploy command. You should only have to do this once:

docker login -u <username> <registry>

This will prompt for the password. Afterwards, the deploy command should work as expected.

Object storage

This is mainly used for large payloads and outputs. There are a few simple steps to follow to get started.

Default settings

The default settings for the object storage are:

Endpoint: http://localhost:9000
Username: admin
Password: very-safe-password

You should change these before deploying to production, especially the password.

Setup

The packets bucket is created by default. In case this doesn’t work, you can create it manually.

Login to the dashboard: http://localhost:9001
Create a bucket named packets.
For production, you will want to set up a dedicated user and not use the root credentials above.

Authentication

The specific set of variables required will depend on your choice of email transport or alternative login methods like GitHub OAuth.

Magic link

By default, magic link auth is the only login option. If the EMAIL_TRANSPORT env var is not set, the magic links will be logged by the webapp container and not sent via email.

Resend

EMAIL_TRANSPORT=resend
FROM_EMAIL=
REPLY_TO_EMAIL=
RESEND_API_KEY=<your_resend_api_key>

SMTP

Note that setting SMTP_SECURE=false does not mean the email is sent insecurely. This simply means that the connection is secured using the modern STARTTLS protocol command instead of implicit TLS. You should only set this to true when the SMTP server host directs you to do so (generally when using port 465)

EMAIL_TRANSPORT=smtp
FROM_EMAIL=
REPLY_TO_EMAIL=
SMTP_HOST=<your_smtp_server>
SMTP_PORT=587
SMTP_SECURE=false
SMTP_USER=<your_smtp_username>
SMTP_PASSWORD=<your_smtp_password>

AWS SES

Credentials are to be supplied as with any other program using the AWS SDK. In this scenario, you would likely either supply the additional environment variables AWS_REGION, AWS_ACCESS_KEY_ID and AWS_SECRET_ACCESS_KEY or, when running on AWS, use credentials supplied by the EC2 IMDS.

EMAIL_TRANSPORT=aws-ses
FROM_EMAIL=
REPLY_TO_EMAIL=

GitHub OAuth

To authenticate with GitHub, you will need to set up a GitHub OAuth app. It needs a callback URL https://<your_webapp_domain>/auth/github/callback and you will have to set the following env vars:

AUTH_GITHUB_CLIENT_ID=<your_client_id>
AUTH_GITHUB_CLIENT_SECRET=<your_client_secret>

Restricting access

All email addresses can sign up and log in this way. If you would like to restrict this, you can use the WHITELISTED_EMAILS env var. For example:

# every email that does not match this regex will be rejected
WHITELISTED_EMAILS="^(authorized@yahoo\.com|authorized@gmail\.com)$"

This will apply to all auth methods including magic link and GitHub OAuth.

Version locking

There are several reasons to lock the version of your Docker images:

Backwards compatibility. We try our best to maintain compatibility with older CLI versions, but it’s not always possible. If you don’t want to update your CLI, you can lock your Docker images to that specific version.
Ensuring full feature support. Sometimes, new CLI releases will also require new or updated platform features. Running unlocked images can make any issues difficult to debug. Using a specific tag can help here as well.

By default, the images will point at the latest versioned release via the latest tag. You can override this by specifying a different tag in your .env file. For example:

TRIGGER_IMAGE_TAG=v4.5.0

We patch the latest released version line only, so keep an eye on new releases to receive security fixes. See Security & vulnerability reporting. You can also lock the versions of the bundled services, for example with CLICKHOUSE_IMAGE_TAG. If you do, or if you bring your own ClickHouse via CLICKHOUSE_URL, note that Trigger.dev requires ClickHouse 25.8 or newer.

The bundled ClickHouse uses the official clickhouse/clickhouse-server image, and your existing data volume carries over automatically on upgrade. If you pinned CLICKHOUSE_IMAGE_TAG to a Bitnami tag, switch it to an official tag (for example 26.2) — Bitnami tags don’t exist in the official repository.

Trigger.dev 4.5.0 is the last version we officially support for running v3 (SDK v3) tasks. If you still have v3 tasks, pin TRIGGER_IMAGE_TAG to exactly v4.5.0 or migrate to v4. 4.5.1 and later reject v3 triggers and deploys with an upgrade message.

Task events

By default, task events (timeline, logs, spans) are stored in PostgreSQL. For production deployments we recommend storing them in ClickHouse instead, it scales to much higher volumes and avoids unbounded growth of the TaskEvent table. To enable, set on the webapp in your .env:

EVENT_REPOSITORY_DEFAULT_STORE=clickhouse_v2

This only affects new runs; existing runs continue to read from wherever their events were originally stored.

Move from the legacy clickhouse store

The legacy clickhouse store (the task_events_v1 table) is retired. If you set EVENT_REPOSITORY_DEFAULT_STORE=clickhouse, your webapp now writes and reads clickhouse_v2 instead and logs a warning at startup. Events recorded in task_events_v1 stay there but no longer show in the dashboard until you copy them over.

Switch to clickhouse_v2

Switch the store in your .env and restart the webapp:

.env

EVENT_REPOSITORY_DEFAULT_STORE=clickhouse_v2

List the days to copy

List the days that hold legacy events. The bundled ClickHouse container already sets CLICKHOUSE_USER and CLICKHOUSE_PASSWORD, and clickhouse-client reads them, so no credentials are needed:

docker compose exec clickhouse clickhouse-client -q \
  "SELECT toDate(start_time) AS day, count() FROM trigger_dev.task_events_v1 GROUP BY day ORDER BY day"

Save the copy query

Save the copy query as copy-task-events-v1.sql. It copies one day and skips events already in task_events_v2, so it’s safe to run again if it’s interrupted:

copy-task-events-v1.sql

INSERT INTO trigger_dev.task_events_v2
  (environment_id, organization_id, project_id, task_identifier, run_id, start_time,
   trace_id, span_id, parent_span_id, message, kind, status, attributes_text,
   metadata, duration, expires_at, inserted_at)
SELECT
  environment_id, organization_id, project_id, task_identifier, run_id, start_time,
  trace_id, span_id, parent_span_id, message, kind, status, attributes_text,
  metadata, duration, expires_at, toDateTime64(start_time, 3)
FROM trigger_dev.task_events_v1
WHERE toDate(start_time) = {day:Date}
  AND (trace_id, span_id, start_time, kind, status) NOT IN (
    SELECT trace_id, span_id, start_time, kind, status
    FROM trigger_dev.task_events_v2
    WHERE inserted_at >= {day:Date} AND inserted_at < {day:Date} + INTERVAL 8 DAY
      AND toDate(start_time) = {day:Date}
  );

Copy each day

Run it once per day from step 2, oldest first:

docker compose exec -T clickhouse clickhouse-client --param_day=2026-08-01 \
  --multiquery < copy-task-events-v1.sql

Check a copied run

Open a run from one of the copied days and check its trace and logs show.

Copying one day at a time keeps memory use bounded on large tables. A future release removes task_events_v1, so copy anything you want to keep before then.

EVENT_REPOSITORY_V1_REROUTE_ENABLED=0 keeps the legacy store while you migrate. It’s temporary and will be removed in a future release.

Realtime streams

Realtime streams power AI-agent token streaming and run streams. They default to v2, backed by the bundled s2 service — s2-lite, the open-source, self-hostable S2 server. It stores stream data in a persistent volume and is preconfigured in the webapp compose file, so no setup is required. To fall back to the Redis-backed v1 streams, set on the webapp in your .env:

REALTIME_STREAMS_DEFAULT_VERSION=v1

To use a hosted S2 at s2.dev instead of the bundled s2-lite, point the endpoint at your basin and supply an access token:

REALTIME_STREAMS_S2_BASIN=your-basin
REALTIME_STREAMS_S2_ENDPOINT=https://your-basin.b.aws.s2.dev/v1
REALTIME_STREAMS_S2_SKIP_ACCESS_TOKENS=false
REALTIME_STREAMS_S2_ACCESS_TOKEN=your-access-token

See the webapp environment variables for the full list of realtime stream settings.

Troubleshooting

Deployment fails at the push step. The machine running deploy needs registry access. See the registry setup section for more details.
Magic links don’t arrive. The webapp container needs to be able to send emails. You probably need to set up an email transport. See the authentication section for more details. You should check the logs of the webapp container to see the magic link:
# Run this from the /hosting/docker/webapp directory docker compose logs -f webapp
ClickHouse migrations say “no migrations to run” but schema is missing. The goose migration tracker is out of sync. Exec into the webapp container, set the GOOSE env vars (from webapp startup logs), and run goose reset && goose up.
Data Loss Warning: The goose reset command is destructive and will drop the entire schema. Make sure to backup your data and confirm you are running this in a non-production environment before executing this command.

CLI usage

This section highlights some of the CLI commands and options that are useful when self-hosting. Please check the CLI reference for more in-depth documentation.

Login

To avoid being redirected to Trigger.dev Cloud when using the CLI, you need to specify the URL of your self-hosted instance with the --api-url or -a flag. For example:

npx trigger.dev@latest login -a http://trigger.example.com

Once you’ve logged in, you shouldn’t have to specify the URL again with other commands.

Profiles

You can specify a profile when logging in. This allows you to easily use the CLI with multiple instances of Trigger.dev. For example:

npx trigger.dev@latest login -a http://trigger.example.com \
    --profile self-hosted

Logging in with a new profile will also make it the new default profile. To use a specific profile, you can use the --profile flag with other commands:

npx trigger.dev@latest dev --profile self-hosted

To list all your profiles, use the list-profiles command:

npx trigger.dev@latest list-profiles

To remove a profile, use the logout command:

npx trigger.dev@latest logout --profile self-hosted

To switch to a different profile, use the switch command:

# To run interactively
npx trigger.dev@latest switch

# To switch to a specific profile
npx trigger.dev@latest switch self-hosted

Whoami

It can be useful to check you are logged into the correct instance. Running this will also show the API URL:

npx trigger.dev@latest whoami

CI / GitHub Actions

When running the CLI in a CI environment, your login profiles won’t be available. Instead, you can use the TRIGGER_API_URL and TRIGGER_ACCESS_TOKEN environment variables to point at your self-hosted instance and authenticate. For more detailed instructions, see the GitHub Actions guide.

Telemetry

By default, the Trigger.dev webapp sends telemetry data to our servers. This data is used to improve the product and is not shared with third parties. If you would like to opt-out of this, you can set the TRIGGER_TELEMETRY_DISABLED environment variable on the webapp container. The value doesn’t matter, it just can’t be empty. For example:

services:
  webapp:
    ...
    environment:
      TRIGGER_TELEMETRY_DISABLED: 1

Was this page helpful?

⌘I

You are visitor 01402503 — GeezerVison does not store the pages you look up.
Best viewed with Netscape Navigator 4.7 or Internet Explorer 6 at 800×600. No cookies required.

GeezerVison

​What’s new?

​Requirements

​Prerequisites

​Webapp

​Worker

​Setup

​Webapp

​Worker

​Combined

​Worker token

​Creating additional worker groups

​Registry setup

​Default settings

​Logging in

​Object storage

​Default settings

​Setup

​Authentication

​Magic link

​Resend

​SMTP

​AWS SES

​GitHub OAuth

​Restricting access

​Version locking

​Task events

​Move from the legacy clickhouse store

Switch to clickhouse_v2

List the days to copy

Save the copy query

Copy each day

Check a copied run

​Realtime streams

​Troubleshooting

​CLI usage

​Login

​Profiles

​Whoami

​CI / GitHub Actions

​Telemetry

What’s new?

Requirements

Prerequisites

Webapp

Worker

Setup

Webapp

Worker

Combined

Worker token

Creating additional worker groups

Registry setup

Default settings

Logging in

Object storage

Default settings

Setup

Authentication

Magic link

Resend

SMTP

AWS SES

GitHub OAuth

Restricting access

Version locking

Task events

Move from the legacy clickhouse store

Realtime streams

Troubleshooting

CLI usage

Login

Profiles

Whoami

CI / GitHub Actions

Telemetry