DocupDocup
Esc

Local setup

Run Docup on your machine with Docker for Postgres and Redis, a .dev.vars file, migrations and the Trigger.dev dev server.

This guide runs the dashboard, a docs site and the background tasks on your own machine.

Prerequisites#

  • Node.js and pnpm 12
  • Docker, for Postgres and Redis
  • A GitHub account, to create an OAuth app and a GitHub App
  • A Trigger.dev cloud project, for the background tasks
  • A Google Cloud project with Vertex AI and a service account, for the models
  • A Qdrant Cloud cluster, for Ask AI
  • Optional: Google OAuth credentials, a Cloudflare Turnstile key and an ngrok tunnel

1. Install#

Bash
pnpm install

2. Start Postgres and Redis#

Bash
pnpm db:up

This starts Postgres 17 on port 5432 (user, password and database all docup), Redis 7 and an HTTP proxy on port 8079 so the same @upstash/redis client works locally. The proxy token is docup-local-redis-token.

3. Create .dev.vars#

Bash
cp .dev.vars.example .dev.vars

Fill in the values. The most important ones are described in Environment variables. For local work, set:

Text
BETTER_AUTH_URL=http://localhost:3000
DATABASE_URL=postgres://docup:docup@localhost:5432/docup
UPSTASH_REDIS_REST_URL=http://localhost:8079
UPSTASH_REDIS_REST_TOKEN=docup-local-redis-token

Generate BETTER_AUTH_SECRET with openssl rand -base64 32.

Point DATABASE_URL at your local database unless you mean to use a remote one. The db:* scripts read .dev.vars, and a DATABASE_URL exported in your shell can take precedence over it.

4. Run migrations#

Bash
pnpm db:migrate

5. Start the app#

Bash
pnpm dev

The app runs on http://localhost:3000, and the port is strict: the command fails if it is taken. The Worker runtime is emulated, with R2 and Hyperdrive stored locally. In development Hyperdrive points at the local Postgres.

Docs sites are served on <address>.localhost:3000. Browsers resolve *.localhost to your machine, so a site with the address acme is at http://acme.localhost:3000.

6. Start the background tasks#

In a second terminal:

Bash
pnpm trigger:dev

This connects to your Trigger.dev project. The tasks read their own environment variables from the Trigger.dev dashboard, not from .dev.vars. Add DATABASE_URL, GITHUB_SERVER_TOKEN, GITHUB_APP_ID, GITHUB_APP_PRIVATE_KEY, GOOGLE_VERTEX_CREDENTIALS, QDRANT_* and UPSTASH_* there.

7. Receive GitHub webhooks (optional)#

Updates on push need GitHub to reach your machine. Run an ngrok tunnel to port 3000, set the GitHub App's webhook URL to <tunnel>/api/webhooks/github, and use the same secret as GITHUB_WEBHOOK_SECRET. The dev server allows hosts under .ngrok-free.dev.

Everyday commands#

Command What it does
pnpm dev Dev server on port 3000
pnpm build Build the Worker
pnpm start Preview the build locally
pnpm preview Build, then preview
pnpm deploy Deploy with vinext's Cloudflare helper
pnpm cf-typegen Generate Worker binding types
pnpm trigger:dev Trigger.dev dev server
pnpm trigger:deploy Deploy tasks to Trigger.dev
pnpm db:up Start Postgres and Redis containers
pnpm db:generate Generate a migration from schema changes
pnpm db:migrate Apply migrations
pnpm db:studio Open Drizzle Studio
pnpm db:auth-schema Regenerate the Better Auth tables

Troubleshooting#

  • "Port 3000 is in use." Free the port; the server does not pick another.
  • Sign-in redirects fail. The OAuth callback must be http://localhost:3000/api/auth/callback/github or .../google.
  • A run never starts. Check that pnpm trigger:dev is running and that TRIGGER_SECRET_KEY is the dev key of the same project.
  • Docs sites 404. Use <address>.localhost:3000, and publish the site first.
Documentation written with Docup