Getting Started Locally
This is the from-zero contributor onboarding. For the production install paths see the top-level README.md.
Requirements#
- Docker Engine running locally
- Node.js ≥ 22.18 LTS
- Python 3.12+ (Django backend runs in its own venv)
- Postgres 15+ (provided by docker-compose-local)
- Valkey 7+ (or Redis 7+, drop-in compatible — also provided)
- RAM ≥ 12 GB — 8 GB will OOM during Docker build / pnpm install
- Rust toolchain (only needed if you’ll touch
runner/;rust-toolchain.tomlpins the version)
First-time bootstrap#
git clone https://github.com/The-AI-Republic/pi-dash.git
cd pi-dash
chmod +x setup.sh
./setup.shsetup.sh does three things:
- Copies every
.env.exampleto.env— repo root plusapps/{web,api,space,admin,live}. The defaults work out of the box for loopback dev (localhost URLs,pi-dashPostgres creds, local MinIO endpoint). Only edit.envfiles if you’re binding to a non-default host or wiring in external services. - Generates a unique Django
SECRET_KEYand appends it toapps/api/.env. - Runs
pnpm installfor the TS workspace.
Start the infra#
docker compose -f docker-compose-local.yml upThis brings up just the dependencies — Postgres, Redis/Valkey, RabbitMQ, MinIO. The app processes themselves run on your host so you keep hot reload.
Start the apps#
pnpm devTurbo launches every dev server concurrently. Watch the output for any one that failed to start.
Ports#
| App | Port | Purpose |
|---|---|---|
web | 3000 | Main product UI |
admin | 3001 | Instance admin (“god mode”) |
space | 3002 | Published public spaces |
live | per .env | Hocuspocus realtime editor server |
api | (Django, port per .env) | REST + Channels backend |
First-run flow#
- Open
http://localhost:3001/god-mode/and register yourself as the instance admin. You only do this once per instance. - Open
http://localhost:3000and log in with the same credentials. This is the actual product. - Create a workspace → create a project → invite yourself.
- (Optional, for runner work) install the
pidashCLI and point it athttp://localhost:8000(or whatever the API exposes locally) — see 11 — Authentication for device-code login.
Common gotchas#
- Django defaults to
productionsettings.manage.pysetsDJANGO_SETTINGS_MODULE=pi_dash.settings.production. For local work either exportDJANGO_SETTINGS_MODULE=pi_dash.settings.localor use the helper scripts underapps/api/. - Turbo concurrency = 18. If
pnpm devis choking your machine, lower it:pnpm turbo run dev --concurrency=8. - OxLint warning ceilings will block your commit. Each app pins a
--max-warningsceiling in itspackage.json. Adding warnings past the ceiling failscheck:lintand trips the pre-commit hook. Either fix the warning or — if you legitimately removed some — lower the ceiling, don’t raise it. - Husky + lint-staged run
oxfmtandoxlint --fix --deny-warningson commit. A hook failure means the commit didn’t happen — fix the underlying issue and re-commit, do not--no-verify. - Postgres data persists in the named Docker volume from
docker-compose-local.yml.docker compose down -vwill wipe it; that’s how you get a clean slate.
Where to go next#
- 13 — Development workflow — pnpm/turbo/lint/format day-to-day commands
- 14 — Testing — running pytest / vitest / cargo test
- 05, 06, 07 — the per-stack deep dives