Run TimeTriggers in your CI
The standalone image runs all of TimeTriggers in one container: the API, the dashboard and, unless you bring your own, a Postgres database. It is built from the same code and the same database migrations as api.timetriggers.io, so your end-to-end tests, CI pipelines and preview environments exercise the real thing, without calling the hosted service or consuming your quota.
registry.licarth.com/timetriggers/standalone:latest
Each build is also tagged :sha-<commit>. Pin that tag in CI if you want reproducible runs.
The registry is private: log in with the credentials we gave you before pulling (docker login registry.licarth.com). In GitHub Actions, pass them as the service's credentials (see the example).
The standalone image is for tests and ephemeral environments. It prints its sign-in code and generated API key in its logs, and has no email delivery unless you configure SMTP. Don't expose it to the internet with production data.
Quick start
docker run --rm -p 3000:3000 -p 8080:8080 \-e TT_API_KEY=ttr_local_test_key_not_a_secret_000000 \-e TT_ADMIN_LOGIN_CODE=123456 \registry.licarth.com/timetriggers/standalone:latest
When the container logs API on :3000, dashboard on :8080:
The API is at
http://localhost:3000. Use the key fromTT_API_KEYexactly like a production key:curl -X POST http://localhost:3000/schedule \-H "ttr-api-key: ttr_local_test_key_not_a_secret_000000" \-H "ttr-url: https://example.com/webhooks/reminder" \-H "ttr-scheduled-at: now | add 1m"The dashboard is at
http://localhost:8080/login. Sign in asadmin@timetriggers.localwith the code123456. No email is sent.
Configuration
Everything is optional. Without any variable, the container starts its own database, creates the account and prints a generated sign-in code and API key in its logs.
| Variable | Default | Purpose |
|---|---|---|
TT_API_KEY | generated | API key of the project. Must be ttr_ followed by at least 32 letters, digits, _ or -; generate one with echo ttr_$(openssl rand -hex 24). If unset, a key is generated once, stored in the database, and printed in the logs: API key for admin@timetriggers.local: ttr_…. |
TT_ADMIN_EMAIL | admin@timetriggers.local | Email address of the account. The account, its project and its API key are created at startup if they don't exist. |
TT_ADMIN_LOGIN_CODE | random, printed in the logs | 6-digit code that signs this account in to the dashboard. It replaces the code normally sent by email, for this address only. |
TT_PROJECT_SLUG | standalone | Slug of the project, used when it is created. |
TT_PLAN | flex | flex: no monthly quota. free: the free plan's quota of 500 /schedule calls a month, to test how your app handles 429. |
DATABASE_URL | embedded Postgres | Postgres connection URL (postgresql://user:password@host:5432/db). Production runs Postgres 17. If unset, the container runs Postgres 17 itself. |
BETTER_AUTH_SECRET | generated | Secret that signs dashboard sessions. If unset, a random one is generated (and kept in /data with the embedded database). |
API_PORT / UI_PORT | 3000 / 8080 | Ports of the API and of the dashboard inside the container. |
SMTP_HOST, SMTP_PORT, SMTP_USER, SMTP_PASS, SMTP_FROM | none | Optional: deliver sign-in codes for other addresses and failure-alert emails. Without SMTP, only TT_ADMIN_EMAIL can sign in. |
Startup is idempotent: restarting the container with the same variables reuses the account, the project and the keys.
The database
Embedded (default). Postgres 17 runs inside the container and only listens on 127.0.0.1, so it is not reachable from outside and has no password. Its data lives in /data. Mount a volume there to keep it across container restarts:
docker run -v timetriggers-data:/data -p 3000:3000 -p 8080:8080 registry.licarth.com/timetriggers/standalone:latest
Your own Postgres. Set DATABASE_URL. The container applies the migrations at every start, so use an empty database dedicated to TimeTriggers.
Calling your app from TimeTriggers
TimeTriggers sends each trigger's request from inside the container. There, localhost is the container itself, not your app:
- Docker Compose or Kubernetes: use your app's service name, e.g.
ttr-url: http://my-app:4000/webhooks/reminder. - App running on the host: start the container with
--add-host=host.docker.internal:host-gatewayand usehttp://host.docker.internal:<port>/….
Examples
Docker Compose
services:timetriggers:image: registry.licarth.com/timetriggers/standalone:latestports: ["3000:3000", "8080:8080"]environment:TT_API_KEY: ${TT_API_KEY}TT_ADMIN_LOGIN_CODE: "123456"healthcheck:test: ["CMD", "node", "-e", "fetch('http://localhost:3000/health').then(r=>process.exit(r.ok?0:1),()=>process.exit(1))"]interval: 2sretries: 60my-app:build: .environment:TIMETRIGGERS_URL: http://timetriggers:3000TIMETRIGGERS_API_KEY: ${TT_API_KEY}depends_on:timetriggers: { condition: service_healthy }
GitHub Actions
jobs:e2e:runs-on: ubuntu-latestservices:timetriggers:image: registry.licarth.com/timetriggers/standalone:latestcredentials:username: ${{ secrets.TIMETRIGGERS_REGISTRY_USERNAME }}password: ${{ secrets.TIMETRIGGERS_REGISTRY_PASSWORD }}ports: ["3000:3000", "8080:8080"]env:TT_API_KEY: ttr_local_test_key_not_a_secret_000000# Lets triggers reach the app you start on the runner.options: >---add-host=host.docker.internal:host-gateway--health-cmd="node -e \"fetch('http://localhost:3000/health').then(r=>process.exit(r.ok?0:1),()=>process.exit(1))\""--health-interval=2s --health-retries=60steps:- uses: actions/checkout@v4- run: npm ci && npm run test:e2eenv:TIMETRIGGERS_URL: http://localhost:3000TIMETRIGGERS_API_KEY: ttr_local_test_key_not_a_secret_000000# Your app, as TimeTriggers sees it from the container:CALLBACK_BASE_URL: http://host.docker.internal:4000
A key that only exists in this throwaway container is not a secret. Use a different one for anything that outlives the job.
Health and readiness
GET http://localhost:3000/health returns 200 once the API is ready. The image declares the same check as its Docker HEALTHCHECK, so docker ps shows healthy. The first start takes a few seconds longer: it initialises the database and applies the migrations.
Differences from timetriggers.io
The code, the migrations and the API are those of the hosted service, including its rate limit on sign-in (3 attempts every 10 seconds; in browser tests, sign in once and reuse the session). Only these differ:
- One account is created from environment variables, and it signs in with a fixed code instead of an emailed one.
- Its project is on the
flexplan (no monthly quota) unlessTT_PLAN=free. - No email is sent unless you configure SMTP; Add to Slack is not offered.
- The API, the dashboard and the database share one container, so it runs a single API replica.