Getting Started

Getting Started

Get a GDX Dispatch instance running locally (or on a server) with Docker. ~5 minutes.

Prerequisites

• Docker and Docker Compose (v2, the docker compose subcommand).
• That's it — Postgres, Redis, the API, and the workers all run as containers.

1. Configure

git clone https://github.com/freePerro/gdx_dispatch.git
cd gdx_dispatch
cp .env.template .env

Open .env and fill in the [REQUIRED] values. The template documents every option; the ones that must be set or the app won't boot / won't let you log in:

Variable	How to generate
DB_PASSWORD (and POSTGRES_PASSWORD)	any strong password
JWT_SECRET	openssl rand -hex 32 (≥32 bytes, or the app refuses to start)
MASTER_ENCRYPTION_KEY	python3 -c "from cryptography.fernet import Fernet; print(Fernet.generate_key().decode())"
SECRET_KEY	openssl rand -hex 32
GDX_ADMIN_EMAIL / GDX_ADMIN_PASSWORD	your first admin login (password optional — see step 4)

Never commit .env — it holds secrets.

2. Start the stack

From the repo root (so Compose picks up .env). Pick one:

Option A — run the published image (recommended, no build)

Pulls a pre-built release from GHCR instead of compiling locally:

echo 'APP_VERSION=1.45.0' >> .env    # pin a release (or leave unset to track :latest)

docker compose --env-file .env \
  -f gdx_dispatch/docker/docker-compose.yml \
  -f gdx_dispatch/docker/docker-compose.selfhost.yml up -d

Option B — build from source (for development / customization)

docker compose -f gdx_dispatch/docker/docker-compose.yml --env-file .env up -d --build

Either way this brings up PostgreSQL, Redis, the API, the Celery workers, and the plugin host (db, redis, app, celery-high, celery-low, celery-beat, plugin-host — the last runs third-party plugins, isolated from the core app). On first start the API container automatically and idempotently runs database migrations, creates the tables, and seeds a default tenant + an initial admin user.

3. Verify it's up

curl http://localhost:8001/health
# {"status":"ok","db":"ok",...}

The API is on http://localhost:8001 (the frontend is served from the same origin in Docker).

4. First login

• Email: GDX_ADMIN_EMAIL (default admin@example.com).

• Password: GDX_ADMIN_PASSWORD if you set one; otherwise a random password is generated and printed to the logs on first start:

  docker compose -f gdx_dispatch/docker/docker-compose.yml logs app | grep -A4 "initial admin account"

The admin is created with must-change-password — change it right after your first login.

What you've got

A working single-tenant field-service dispatch platform: customers, jobs & work-orders, estimates, invoicing, scheduling/dispatch — FastAPI backend, Vue 3 SPA, Postgres, Redis, Celery workers.

Troubleshooting

• app keeps restarting / login 500s — almost always a missing key. Confirm JWT_SECRET (≥32 bytes), MASTER_ENCRYPTION_KEY (a Fernet key), and a reachable Redis are set. If Compose isn't picking up your .env, pass it explicitly with --env-file .env (as above) and run from the repo root.
• Check logs: docker compose -f gdx_dispatch/docker/docker-compose.yml logs -f app

Next steps

• Updating a self-hosted instance — see the project README's Self-hosting and Updating sections (docker/update.sh, pin APP_VERSION).
• Extend it with plugins — Using Plugins (install/enable) and Authoring Plugins (build your own).