ui/), a FastAPI backend (api/), and a Pipecat-based voice pipeline (pipecat/, a git submodule), backed by Postgres, Redis, and MinIO.
Set up
You need Git, a local Docker engine (such as Docker Desktop), and VS Code with the Dev Containers extension.- Fork dograh-hq/dograh and clone your fork:
-
Open the folder in VS Code and run Dev Containers: Reopen in Container. The first build takes several minutes — it starts Postgres, Redis, and MinIO, seeds the Python venv, creates the
.envfiles, and installs UI dependencies. Later opens are fast. - Start the backend from a terminal inside the container. The script waits for the health check and prints a status summary, so when it exits successfully the backend is up:
- Start the UI from a second terminal inside the container:
- Open the app at
http://localhost:3000.
Cloned dograh-hq/dograh directly instead of your fork?
Cloned dograh-hq/dograh directly instead of your fork?
Run
bash scripts/setup_fork.sh once. It prompts for your fork URL, points origin at it, and adds upstream as dograh-hq/dograh. See Fork and upstream remotes.No VS Code? No devcontainer at all?
No VS Code? No devcontainer at all?
The devcontainer also runs headless via the Dev Container CLI, or you can run everything directly on your host.
Daily workflow
| What | How |
|---|---|
| Restart the backend | Re-run bash scripts/start_services_dev.sh — it stops the old processes first |
| Stop the backend | bash scripts/stop_services.sh |
| Backend logs | tail -f logs/latest/*.log |
| Code reload | Edits under api/ auto-reload; ari_manager, campaign_orchestrator, and arq need a backend restart |
| Rebuild the container | Only when .devcontainer/, api/requirements*.txt, or pipecat/ change — plain source edits never need it |
| Sync the pipecat submodule | git submodule update --init --recursive after pulling a submodule bump |
Debugging
The repo ships debug configurations in.vscode/launch.json for every backend service and for pytest. To run under the debugger instead of the start script:
- Stop the script-managed backend if it is running, so the ports are free:
- In VS Code’s Run and Debug panel, pick a configuration and press F5:
| Configuration | What it runs |
|---|---|
| API: Uvicorn (reload) | The FastAPI backend, with auto-reload (port from UVICORN_PORT in api/.env, default 8000) |
| API: Arq worker (watch) / API: Campaign orchestrator / API: ARI manager | The other backend services — launch them alongside Uvicorn as needed |
| Tests: API (pytest, full suite / current file) | pytest under the debugger, against api/.env.test |
| Tests: Pipecat (pytest, current file) / Python: Current file | Debug a pipecat test or any standalone script |
api/.env (test configs use api/.env.test) and set justMyCode: false, so you can step into FastAPI and pipecat code — breakpoints in the pipecat/ submodule work because it is installed editable. Inside the devcontainer the Python interpreter is preselected; on a host-managed setup, pick ./venv/bin/python via Python: Select Interpreter first.
Repository layout
| Path | What’s there |
|---|---|
ui/ | Next.js frontend — the workflow builder, dashboard, and agent editor |
api/ | FastAPI backend — REST API, campaign orchestration, telephony, ARQ background workers |
pipecat/ | Git submodule for the voice pipeline (STT → LLM → TTS) |
docs/ | This documentation site, written in MDX, previewed with mint dev |
sdk/ | Python/TypeScript SDKs for driving Dograh programmatically |
scripts/ | Setup, deployment, and update scripts |
deploy/ | nginx and coturn config templates used by remote deployment |
Contributing a change
- Create a branch and make your change.
- Push to your fork (
origin) and open a pull request againstdograh-hq/dograh:main. - A maintainer reviews and merges.
good first issue are a good place to start. For questions while you’re working, use the Dograh Community Slack.
Deploying your own build instead of contributing upstream? See Deployments instead.