Self-hosting

Deployment profiles

Docker Compose profiles (supabase, standalone with PostgreSQL, MinIO, worker, built-in auth, SSE and Mailpit), the on-premises, Azure and Google Cloud reference profiles with their smoke tests, the full instance migration test, release gates and the Bicep / Terraform templates.

Ready-made ways to run UserTasks, from the default Supabase setup to a stack with no Supabase at all, plus four reference profiles (on-premises, Azure, Google Cloud, AWS). Each reference profile has a smoke test, and all of them are release gates. The provider choices are described in Infrastructure and providers. To move an existing install, see Switching providers.

Docker Compose

docker-compose.yml has two profiles. The profile decides which containers start; .env decides which providers the app uses.

supabase (default)

The app only, against a Supabase project (hosted or supabase start):

cp .env.example .env      # Supabase URL and keys, ENCRYPTION_KEY, CRON_SECRET, …
docker compose up -d --build
docker compose exec -e BOOTSTRAP_PASSWORD='a-strong-password' app \
  node admin.cjs bootstrap --email admin@example.com --org "Acme Inc"

This works exactly as before; see Self-hosting.

standalone

No Supabase. These containers start:

One command writes .env from deploy/compose/standalone.env.example with fresh secrets, builds and starts the stack, waits until it is healthy, and creates the first workspace:

npm run stack -- up --email admin@example.com --org "Acme Inc"   # prints a generated password

By hand, the same steps are:

cp deploy/compose/standalone.env.example .env   # replace every <generate>
docker compose --profile standalone up -d --build --wait
docker compose exec -e BOOTSTRAP_PASSWORD=… app node admin.cjs bootstrap --email admin@example.com --org "Acme Inc"

The standalone profile has some options:

• PgBouncer: pass npm run stack -- init --pgbouncer, or add --profile pgbouncer and point DATABASE_URL at pgbouncer:5432. That runs transaction pooling for the app's queries. Migrations, LISTEN and the worker's leader lock need a real session, so MIGRATION_DATABASE_URL, REALTIME_DATABASE_URL and SCHEDULER_DATABASE_URL keep pointing at postgres:5432.
• Host ports: use APP_PORT, MAILPIT_PORT and MINIO_CONSOLE_PORT.
• Prebuilt image: set USERTASKS_IMAGE=registry.example.com/usertasks:1.2.3 and pass --no-build.

Other npm run stack commands:

Reference profiles

Each reference profile combines the providers for one environment and proves they work together. Run one with:

npm run stack -- up --profile onprem|azure|gcp|aws [--no-build]
npm run stack -- smoke --profile onprem|azure|gcp|aws
npm run stack -- down --profile onprem|azure|gcp|aws --volumes

Reference profiles keep their env files in deploy/compose/.state/, which is git-ignored and gets fresh secrets. Each uses its own Compose project name and host port, so they don't collide with each other or with a dev server on port 3000.

On-premises (onprem)

This is the standalone stack on a Docker network with internal: true, so there is no route to the internet and nothing is published on the host. A passing run shows that no part of the app needs SaaS, a CDN or outbound calls: the smoke test also checks that the app container cannot reach registry.npmjs.org.

--keycloak adds Keycloak 26 (start-dev, realm deploy/compose/keycloak/usertasks-realm.json) as an OIDC identity provider (AUTH_SSO_PROVIDERS, preset keycloak). The doctor checks its discovery document from inside the isolated network.

For a real install, see On-premises setup.

Azure (azure)

The cloud services are replaced by emulators or by local stand-ins. In every case the app still uses its real SDKs.

The stand-ins are in deploy/compose/mocks/cloud-mocks.mjs.

Not emulated: Entra token auth for PostgreSQL (DATABASE_AUTH=azure; plain PostgreSQL with a password is used instead; the token path is tested against PostgreSQL with a fake token provider) and real sign-in through Entra ID.

To deploy for real, use deploy/azure/ (Bicep and Terraform) and Azure setup.

Google Cloud (gcp)

Not emulated: Cloud SQL IAM database auth (DATABASE_AUTH=gcp; tested against PostgreSQL with a fake token provider).

To deploy for real, use deploy/gcp/ (Terraform) and Google Cloud setup.

AWS (aws)

Not emulated: RDS IAM database auth (DATABASE_AUTH=aws) and ElastiCache IAM auth (CACHE_REDIS_AUTH=aws_iam): nothing local verifies those tokens. Both are tested with a fake signer against PostgreSQL and Valkey (__tests__/pg-auth-aws.test.ts, __tests__/cache-aws-iam.test.ts).

To deploy for real, use deploy/aws/ (Terraform) and AWS setup.

Smoke test

npm run stack -- smoke does four things:

1. It creates a throwaway workspace, owner and API key (usertasks-admin bootstrap --api-key).
2. It runs deploy/compose/smoke/smoke.mjs in a container on the deployment's network. That script needs no dependencies and only uses HTTP. It checks:
   • the app answers;
   • the API key works;
   • a task round trip;
   • password sign-in through the login page's server action, and the session it sets;
   • a file upload that is served back by /files;
   • the SSE realtime stream opens;
   • an invitation email reaches the mail sink (Mailpit or the ACS / SES stand-in);
   • for the cloud profiles, a log destination's test event reaches the cloud log stand-in (Azure Monitor, Cloud Logging, CloudWatch Logs).
3. It runs usertasks-admin doctor --json and requires every check to pass, including the scheduler's last tick. It waits for that for up to three minutes.
4. For onprem, it confirms there is no outbound internet.

The script also works against any running install:

SMOKE_URL=https://tasks.example.com SMOKE_API_KEY=ut_… SMOKE_EMAIL=… SMOKE_PASSWORD=… \
SMOKE_ORG=<slug> SMOKE_SIGNIN_ACTION=<id> SMOKE_MAIL=skip node deploy/compose/smoke/smoke.mjs

To find the sign-in action id, look up the signInAction entry in .next/server/server-reference-manifest.json of the build.

Full instance migration test

scripts/e2e-instance-migration.ts takes a Supabase-backed install with the Northwind demo workspace (scripts/screenshots/seed-demo.ts) and moves it off Supabase:

1. It runs usertasks-admin switch for auth → builtin, realtime → sse, scheduler → worker, storage → s3 (MinIO), email → smtp, secrets → db, and then the database → plain PostgreSQL. Each switch has a dry run first.
2. It restarts the app with no Supabase variables at all.
3. It checks the result:
   • the surface E2E (scripts/e2e-surfaces.ts: REST, MCP, CLI) passes, before and after;
   • the demo owner signs in with their old password;
   • files copied from Supabase Storage load through /files;
   • scheduled jobs run through the worker (app_cron.tick_runs);
   • log export ships new events to the demo's Splunk HEC destination;
   • row counts match;
   • usertasks-admin doctor passes;
   • the RLS semantics snapshot is identical before and after.

It is destructive for its source: use CI's stack or a second local Supabase stack (a copy of supabase/ with another project_id and ports). It refuses the default local ports unless E2E_ALLOW_DEFAULT_PORTS=1. The header of the script lists its environment variables.

Release gates

.github/workflows/release-gates.yml runs when started by hand (workflow_dispatch), on v* release tags, or from another workflow (workflow_call):

• Reference profiles: standalone, standalone with PgBouncer, onprem (with Keycloak), azure, gcp and aws. Each one is stack up + smoke + down --volumes.
• Instance migration: a local Supabase stack, plus PostgreSQL 16, MinIO and Mailpit as services, then scripts/e2e-instance-migration.ts.

A release ships only when all of them pass.

Infrastructure as code

Each directory has a README with the deploy order and the one-time database grants. The templates are checked with terraform validate and az bicep build; they have not been applied to a live subscription or project yet.