> ## Documentation Index
> Fetch the complete documentation index at: https://docs.tierity.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Local Development

> Run Tierity from source for development and testing. For people with access to the Tierity source repository.

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.

> [!NOTE]
>
> The source repository is private. To run Tierity yourself, use [Self-hosting](https://docs.tierity.com/self-hosting.md) instead.

## Prerequisites

| Requirement | Version | Notes |
| - | - | - |
| Node.js | 22.x | Backend and frontend |
| Docker & Docker Compose | 24.0 / v2.20+ | For PostgreSQL and Redis |
| Git | Any | To clone the repository |

## Clone the repository

```bash theme={null}
git clone https://github.com/Armistice-Group/tierity.git
cd tierity
```

## Configure the backend

```bash theme={null}
cp backend/.env.example backend/.env
```

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

> [!NOTE]
>
> 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:

| Field | Default |
| - | - |
| Email | `admin@local.net` |
| Password | `@dminUser` |

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:

```bash theme={null}
AUTH_PROVIDER=workos
WORKOS_API_KEY=sk_...
WORKOS_CLIENT_ID=client_...
WORKOS_REDIRECT_URI=http://localhost:3001/auth/callback
```

WorkOS requires a publicly reachable redirect URI. For local development, use a tool like [ngrok](https://ngrok.com) to tunnel your local backend, then register the tunnel URL as the redirect URI in your WorkOS dashboard.

## Start everything

### Option A: Using the dev script (recommended)

The `dev.sh` script starts all services in one step with colored, labeled output:

```bash theme={null}
./dev.sh
```

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:

```bash theme={null}
docker compose up -d postgres redis
```

Install dependencies (first run only):

```bash theme={null}
npm install
cd backend && npm install && cd ..
```

Run database migrations:

```bash theme={null}
cd backend && npm run db:migrate && cd ..
```

Then start backend and frontend in separate terminals:

```bash theme={null}
# Terminal 1 — backend
cd backend && npm run dev

# Terminal 2 — frontend
npm run dev
```

The app will be available at [http://localhost:8080](http://localhost:8080).

## Database management

### Migrations

After pulling changes that include new migrations:

```bash theme={null}
cd backend && npm run db:migrate
```

### Export and import

Useful for moving data between machines or creating snapshots:

```bash theme={null}
# Export (creates a timestamped archive)
cd backend && npm run db:export

# Import a previously exported archive
cd backend && npm run db:import
```

## Running tests

### Frontend

```bash theme={null}
npm test
```

### Backend

The backend tests need a PostgreSQL test database:

```bash theme={null}
createdb pwnbook_test
cd backend && TEST_DATABASE_URL="postgres://<user>@localhost:5432/pwnbook_test" npm test
```

### Type-checking

```bash theme={null}
npm run typecheck          # frontend
cd backend && npx tsc --noEmit
```

## Desktop app (Electron)

To run the desktop application locally:

```bash theme={null}
npm run electron-dev
```

This launches an Electron window pointed at your local Vite dev server. Ensure the frontend is already running.

To build distributable desktop apps:

```bash theme={null}
npm run build:mac    # macOS .dmg
npm run build:win    # Windows installer
npm run build:linux  # Linux AppImage
```


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.