Skip to main content
This guide covers running Tierity from source, without the Docker images. PostgreSQL and Redis still run in Docker, but the frontend and backend run as native processes with hot reload.
The source repository is private. To run Tierity yourself, use Self-hosting instead.

​
Prerequisites

​
Clone the repository

​
Configure the backend

Edit backend/.env. The .env.example file in the repository contains all available options with inline comments. At minimum, set:
  • DATABASE_URL — PostgreSQL connection string pointing to your local instance
  • REDIS_URL — Redis connection string
  • SESSION_SECRET — any random string for local development
  • AUTH_PROVIDER — set to local for local development
  • ADMIN_EMAIL / ADMIN_PASSWORD — credentials for the auto-seeded admin account
The frontend proxies /api and /auth to http://localhost:3001 automatically in development — you do not need to set VITE_API_URL.

​
Authentication in local development

​
Local auth (default)

Set AUTH_PROVIDER=local in backend/.env. Tierity seeds a default admin account on first startup: You can override these by setting ADMIN_EMAIL and ADMIN_PASSWORD in your .env.

​
WorkOS auth

Set AUTH_PROVIDER=workos and supply your WorkOS credentials:
WorkOS requires a publicly reachable redirect URI. For local development, use a tool like ngrok to tunnel your local backend, then register the tunnel URL as the redirect URI in your WorkOS dashboard.

​
Start everything

The dev.sh script starts all services in one step with colored, labeled output:
This will:
  1. Start PostgreSQL and Redis via Docker Compose
  2. Launch the backend on port 3001 (with hot reload)
  3. Launch the frontend on port 8080 (with Vite HMR)
  4. Print combined logs with color-coded prefixes
  5. Clean up all processes on Ctrl+C

​
Option B: Manual startup

Start infrastructure first:
Install dependencies (first run only):
Run database migrations:
Then start backend and frontend in separate terminals:
The app will be available at http://localhost:8080.

​
Database management

​
Migrations

After pulling changes that include new migrations:

​
Export and import

Useful for moving data between machines or creating snapshots:

​
Running tests

​
Frontend

​
Backend

The backend tests need a PostgreSQL test database:

​
Type-checking

​
Desktop app (Electron)

To run the desktop application locally:
This launches an Electron window pointed at your local Vite dev server. Ensure the frontend is already running. To build distributable desktop apps: