Skip to content
Docket

First run

This guide walks through bringing up Docket from a fresh clone to a logged-in browser session.

Prerequisites

Section titled “Prerequisites”
  • Docker and Docker Compose
  • Git

1. Clone and configure

Section titled “1. Clone and configure”
Terminal window
git clone https://git.bcnelson.dev/bcnelson/docket.git
cd docket
cp docket.example.toml docket.toml

Edit docket.toml if needed — defaults work for local development. See Configuration for the full reference.

2. Start services

Section titled “2. Start services”
Terminal window
docker compose up -d

This starts PostgreSQL 15 with persistent storage and Docket itself (which runs migrations automatically on startup).

3. Create the admin user

Section titled “3. Create the admin user”
Terminal window
docker compose exec docket /docket bootstrap-admin \
    --email admin@example.com \
    --name "Admin User"

You’ll be prompted for a password (minimum 8 characters). The command runs migrations if they haven’t run yet, creates the user, and assigns them to the Administrators group.

Or skip the exec step entirely

Section titled “Or skip the exec step entirely”

If you’d rather not shell into the container, set these env vars on the Docket service before docker compose up and the admin is created during startup:

environment:
  DOCKET_AUTH__BOOTSTRAP_ADMIN_EMAIL: admin@example.com
  DOCKET_AUTH__BOOTSTRAP_ADMIN_PASSWORD: change-me-at-least-8-chars
  DOCKET_AUTH__BOOTSTRAP_ADMIN_NAME: Admin User

The flow is idempotent — subsequent restarts are no-ops. Pick one or the other; don’t mix.

4. Verify

Section titled “4. Verify”
Terminal window
curl http://localhost:8080/readyz

Expected response:

{"status":"ready","version":"dev","commit":"...","build_date":"...","gates":{...}}

/readyz only returns ready once startup gates (config loaded, database reachable, migrations current, registries warm) have all passed.

5. Sign in

Section titled “5. Sign in”

Open http://localhost:8080 in a browser and sign in with the admin credentials you just created. You’ll land on the ticket workbench.

Stopping

Section titled “Stopping”
Terminal window
docker compose down        # stop, keep data
docker compose down -v     # stop and delete data

What’s next

Section titled “What’s next”