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 from TT_API_KEY exactly 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 as admin@timetriggers.local with the code 123456. 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.

VariableDefaultPurpose
TT_API_KEYgeneratedAPI 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_EMAILadmin@timetriggers.localEmail address of the account. The account, its project and its API key are created at startup if they don't exist.
TT_ADMIN_LOGIN_CODErandom, printed in the logs6-digit code that signs this account in to the dashboard. It replaces the code normally sent by email, for this address only.
TT_PROJECT_SLUGstandaloneSlug of the project, used when it is created.
TT_PLANflexflex: no monthly quota. free: the free plan's quota of 500 /schedule calls a month, to test how your app handles 429.
DATABASE_URLembedded PostgresPostgres connection URL (postgresql://user:password@host:5432/db). Production runs Postgres 17. If unset, the container runs Postgres 17 itself.
BETTER_AUTH_SECRETgeneratedSecret that signs dashboard sessions. If unset, a random one is generated (and kept in /data with the embedded database).
API_PORT / UI_PORT3000 / 8080Ports of the API and of the dashboard inside the container.
SMTP_HOST, SMTP_PORT, SMTP_USER, SMTP_PASS, SMTP_FROMnoneOptional: 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-gateway and use http://host.docker.internal:<port>/….

Examples

Docker Compose

services:
timetriggers:
image: registry.licarth.com/timetriggers/standalone:latest
ports: ["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: 2s
retries: 60
my-app:
build: .
environment:
TIMETRIGGERS_URL: http://timetriggers:3000
TIMETRIGGERS_API_KEY: ${TT_API_KEY}
depends_on:
timetriggers: { condition: service_healthy }

GitHub Actions

jobs:
e2e:
runs-on: ubuntu-latest
services:
timetriggers:
image: registry.licarth.com/timetriggers/standalone:latest
credentials:
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=60
steps:
- uses: actions/checkout@v4
- run: npm ci && npm run test:e2e
env:
TIMETRIGGERS_URL: http://localhost:3000
TIMETRIGGERS_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 flex plan (no monthly quota) unless TT_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.

TimeTriggers — Schedule HTTP requests at any time.