Getting started

Quickstart: self-host

Run UserTasks on your own machine or servers with Supabase, create the first workspace and sign in.

UserTasks is a Next.js application backed by Supabase (Postgres, Auth, Storage, Vault, pg_cron and pg_net). You run the app; Supabase can be hosted on supabase.com or self-hosted. This page gets a local install running. For production, read Self-hosting.

Every install starts on Supabase with no provider settings. When you need files, email, secrets, sign-in or the database in AWS, Azure, Google Cloud or your own network, move one area at a time with usertasks-admin switch. See Choose your topology.

Requirements

Node.js 20 or later
Docker (for a local Supabase stack) or a Supabase project
The Supabase CLI (npx supabase works)

1. Database

bash

git clone <repository-url> usertasks && cd usertasks
npm install
npx supabase init                            # first time only
npx supabase start && npx supabase db reset  # applies supabase/migrations

supabase start prints the API URL, anon key and service-role key you need next.

2. Configuration

bash

cp .env.example .env.local

Fill in at least NEXT_PUBLIC_SUPABASE_URL, NEXT_PUBLIC_SUPABASE_ANON_KEY, SUPABASE_SERVICE_ROLE_KEY, NEXT_PUBLIC_APP_URL, CRON_SECRET and ENCRYPTION_KEY. Every variable is described in Environment variables.

3. First workspace and owner

Self-signup is off in self-hosted mode. Create the first workspace from the command line:

bash

set -a; . ./.env.local; set +a
npm run bootstrap -- --email admin@example.com --password 'a-strong-password' --org "Acme Inc"

The script prints the workspace slug.

4. Run

bash

npm run dev            # or: npm run build && npm start

Open http://localhost:3000, sign in with the slug, email and password, and finish setup at /onboarding. Invite more people from Settings → Invitations.

5. Turn on background work

Schedules, the run queue, SLAs, reminders, log shipping and sync jobs run when pg_cron calls the app. Add two Vault secrets (the URL must be reachable from the database; for a local stack use http://host.docker.internal:3000):

sql

select vault.create_secret('<same value as CRON_SECRET>', 'cron_secret', 'Bearer secret for usertasks cron endpoints');
select vault.create_secret('http://host.docker.internal:3000', 'app_base_url', 'Public base URL of the UserTasks app');

Without these secrets, synchronous runs, tasks and the API still work, but scheduled triggers, delays, queued runs and log export wait until something calls the processor.

Docker

bash

cp .env.example .env   # fill it in
docker compose up --build

The image runs the app only; the database stays in Supabase. See Self-hosting for build arguments and optional database drivers.