Skip to content

Getting Started

Jump to bottom
Doug edited this page Jun 24, 2026 · 5 revisions

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):

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

This brings up PostgreSQL, Redis, the API, and the Celery workers (db, redis, app, celery-high, celery-low, celery-beat). 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).

Clone this wiki locally