apunkt/dograh
1
0
Fork 0
mirror of https://github.com/dograh-hq/dograh.git synced 2026-07-13 11:22:14 +02:00
Code Issues Projects Releases Packages Wiki Activity

chore: simplify dev setup docs (#520)

Browse source 
Co-authored-by: Claude Fable 5 <noreply@anthropic.com>
This commit is contained in:
Abhishek 2026-07-10 16:09:37 +05:30 • committed by GitHub
parent fb4038a969
commit 4989bab1e9
No known key found for this signature in database
GPG key ID: B5690EEEBB952194
6 changed files with 230 additions and 267 deletions
Download patch file Download diff file Expand all files Collapse all files

41
docs/contribution/fork-workflow.mdx
View file

@ -1,41 +0,0 @@
---
title: Fork Workflow
description: Keep your Dograh fork connected to upstream.
---
The contributor bootstrap script configures two remotes:
- `origin`: your fork, where you push
- `upstream`: `dograh-hq/dograh`, where new commits land
If you cloned `dograh-hq/dograh` directly instead of your fork, run this once inside the devcontainer after it boots:
```bash
bash scripts/setup_fork.sh
```
To pull in upstream changes:
```bash
git fetch upstream
git checkout main
git merge upstream/main
git push origin main
```
Check your remotes any time with:
```bash
git remote -v
```
You should see:
```bash
origin https://github.com/<YOUR_HANDLE>/dograh.git (fetch/push)
upstream https://github.com/dograh-hq/dograh.git (fetch/push)
```
<Note>
Always push feature branches to **`origin`** (your fork), then open a pull request against `dograh-hq/dograh:main`. Never push directly to `upstream`.
</Note>

67
docs/contribution/host-managed-setup.mdx
View file

@ -1,67 +0,0 @@
---
title: Host-managed Setup
description: Set up Dograh directly on your host without the devcontainer.
---
Use this only if you do not want to use the devcontainer.
### System Requirements
- Git
- Node.js 24 to run the UI
- Python 3.13 to run the backend
- Docker to run Postgres, Redis, and MinIO locally
1. Run the contributor bootstrap. It configures `origin` as your fork and `upstream` as `dograh-hq/dograh`, initializes the pipecat submodule, creates the Python venv, and copies the `.env` templates.
<CodeGroup>
```bash macOS/Linux
bash scripts/setup_fork.sh
```
```powershell Windows
.\scripts\setup_fork.ps1
```
</CodeGroup>
2. Activate the virtual environment:
<CodeGroup>
```bash macOS/Linux
source venv/bin/activate
```
```powershell Windows
.\venv\Scripts\Activate.ps1
```
</CodeGroup>
3. Ensure your local Node version is 24:
```bash
nvm use 24
```
4. Install UI dependencies:
```bash
cd ui && npm install && cd ..
```
5. Start the local Docker services:
```bash
docker compose -f docker-compose-local.yaml up -d
```
6. Install Python requirements:
<CodeGroup>
```bash macOS/Linux
bash scripts/setup_requirements.sh --dev
```
```powershell Windows
.\scripts\setup_requirements.ps1 -Dev
```
</CodeGroup>
7. Start the backend services:
<CodeGroup>
```bash macOS/Linux
bash scripts/start_services_dev.sh
```
```powershell Windows
.\scripts\start_services_dev.ps1
```
</CodeGroup>
8. Start the UI:
```bash
cd ui && npm run dev
```
9. Open the application on `http://localhost:3000`.

50
docs/contribution/introduction.mdx
View file

@ -1,50 +0,0 @@
---
title: Contribution
description: How the Dograh codebase is laid out, and how to get a local dev environment running so you can contribute.
---
Dograh is an open-source, full-stack voice agent platform: a Next.js UI, a FastAPI backend, Postgres/Redis/MinIO for storage, and a [Pipecat](https://github.com/pipecat-ai/pipecat)-based pipeline (checked in as a git submodule) that drives the actual voice conversation.
## Repository layout
| Path | What's there |
| --- | --- |
| `ui/` | Next.js frontend — the workflow builder, dashboard, and agent editor |
| `api/` | FastAPI backend — REST API, campaign orchestration, ARI/telephony integration, ARQ background workers |
| `pipecat/` | Git submodule for the voice pipeline (STT → LLM → TTS) |
| `docs/` | This documentation site, built with Mintlify |
| `sdk/` | Python/TypeScript SDKs for driving Dograh programmatically |
| `scripts/` | Setup, deployment, and update scripts referenced throughout these docs |
| `deploy/` | nginx and coturn config templates used by remote deployment |
## Setting up a dev environment
There are two supported paths:
1. **[Devcontainer setup](/contribution/setup)** (recommended) — a VS Code / Dev Containers environment that bootstraps Postgres, Redis, MinIO, the Python venv, and UI dependencies for you.
2. **[Host-managed setup](/contribution/host-managed-setup)** — run everything directly on your machine if you'd rather not use a devcontainer.
If you cloned `dograh-hq/dograh` directly instead of forking first, see [Fork Workflow](/contribution/fork-workflow) to fix up your `origin`/`upstream` remotes.
## Contribution flow
1. Fork the repo and clone your fork.
2. Set up your dev environment ([devcontainer](/contribution/setup) or [host-managed](/contribution/host-managed-setup)).
3. Create a branch, make your change.
4. Push to your fork (`origin`) and open a pull request against `dograh-hq/dograh:main`.
5. A maintainer reviews and merges.
Bug reports and feature ideas go through [GitHub Issues](https://github.com/dograh-hq/dograh/issues) and [Ideas](https://github.com/orgs/dograh-hq/discussions/categories/ideas). Issues tagged `good first issue` are a good place to start. For questions while you're working, use the [Dograh Community Slack](https://join.slack.com/t/dograh-community/shared_invite/zt-3zjb5vwvl-j7hRz3_F1SOn5cH~jm5f5g).
## Where to start
- **First time setting up?** Go to [Setup](/contribution/setup).
- **Contributing to these docs?** Docs live in `docs/`, written in MDX, previewed with `mint dev` inside that folder.
- **Working on the voice pipeline?** You'll be in `pipecat/` and `api/` — remember to `git submodule update --init --recursive` after pulling submodule bumps.
- **Deploying your own build instead of contributing upstream?** See [Deployments](/deployment/introduction) instead.
## Related
- [Setup](/contribution/setup)
- [Devcontainer Workflow](/contribution/devcontainer)
- [Fork Workflow](/contribution/fork-workflow)

178
docs/contribution/devcontainer.mdx → docs/contribution/reference.mdx
View file

@ -1,11 +1,81 @@
---
title: Devcontainer Workflow
description: Details for running and maintaining the Dograh devcontainer.
title: Setup Reference
description: Host-managed setup, devcontainer internals, the Dev Container CLI, and fork maintenance.
---
The checked-in `.devcontainer/` follows the Dev Containers specification, so it should also work in Cursor, JetBrains IDEs, and other Dev Container-compatible editors. Only the VS Code path is actively tested. If something breaks elsewhere, please open a [GitHub issue](https://github.com/dograh-hq/dograh/issues).
Everything on this page is optional reading — [Setup](/contribution/setup) covers the normal path.
### What the Bootstrap Does
## Host-managed setup
Run everything directly on your host instead of inside the devcontainer. You need Git, Node.js 24, Python 3.13, and Docker (for Postgres, Redis, and MinIO).
1. Run the contributor bootstrap. It configures `origin` as your fork and `upstream` as `dograh-hq/dograh`, initializes the pipecat submodule, creates the Python venv, and copies the `.env` templates:
<CodeGroup>
```bash macOS/Linux
bash scripts/setup_fork.sh
```
```powershell Windows
.\scripts\setup_fork.ps1
```
</CodeGroup>
2. Activate the virtual environment:
<CodeGroup>
```bash macOS/Linux
source venv/bin/activate
```
```powershell Windows
.\venv\Scripts\Activate.ps1
```
</CodeGroup>
3. Install Python requirements:
<CodeGroup>
```bash macOS/Linux
bash scripts/setup_requirements.sh --dev
```
```powershell Windows
.\scripts\setup_requirements.ps1 -Dev
```
</CodeGroup>
4. Install UI dependencies (make sure `node --version` reports 24, e.g. via `nvm use 24`):
```bash
cd ui && npm install && cd ..
```
5. Start Postgres, Redis, and MinIO:
```bash
docker compose -f docker-compose-local.yaml up -d
```
6. Start the backend:
<CodeGroup>
```bash macOS/Linux
bash scripts/start_services_dev.sh
```
```powershell Windows
.\scripts\start_services_dev.ps1
```
</CodeGroup>
7. Start the UI, then open `http://localhost:3000`:
```bash
cd ui && npm run dev
```
## Devcontainer internals
The checked-in `.devcontainer/` follows the Dev Containers specification, so it should also work in Cursor, JetBrains IDEs, and other compatible editors. Only the VS Code path is actively tested — if something breaks elsewhere, please open a [GitHub issue](https://github.com/dograh-hq/dograh/issues).
### What the bootstrap does
While the container starts, the devcontainer will:
@ -22,9 +92,41 @@ In the API env files, `localhost` for Postgres, Redis, and MinIO is rewritten to
If you already had an `api/.env` or `api/.env.test` from host-managed development with `localhost` hosts for Postgres, Redis, or MinIO, the bootstrap leaves it untouched. Edit those URLs to the docker network aliases before starting the backend inside the devcontainer, or delete the file and let the bootstrap recreate it on the next rebuild.
</Note>
### Dev Container CLI
### When to rebuild the container
Install the CLI once on your host:
The workspace bind mount and the `venv` / `node_modules` named volumes persist across container restarts, so you rarely need to rebuild. Rebuild only when one of these changes:
- `.devcontainer/Dockerfile` or `.devcontainer/devcontainer.json`
- `api/requirements.txt` or `api/requirements.dev.txt`
- The `pipecat/` submodule
Plain source edits, `ui/package.json`, and the `.env.example` templates do **not** require a rebuild. After a `git pull`, a quick check:
```bash
git diff HEAD@{1} HEAD -- .devcontainer api/requirements.txt api/requirements.dev.txt pipecat
```
If the diff is empty, you can keep your current container.
### Personal install hook
Anything you install inside the container outside the named volumes, notably under `/home/vscode`, is wiped on rebuild. This includes `npm i -g` packages and tools like the Claude or Codex CLIs.
To reinstall personal tooling automatically on every rebuild, drop an executable script at `.devcontainer/install.local.sh`. It is gitignored and runs at the tail of the post-create bootstrap. Example:
```bash
#!/usr/bin/env bash
set -euo pipefail
command -v claude >/dev/null 2>&1 || curl -fsSL https://claude.ai/install.sh | bash
command -v codex >/dev/null 2>&1 || npm i -g @openai/codex
```
Keep entries idempotent with `command -v` or a marker file so re-runs are cheap and safe.
## Dev Container CLI
To use the devcontainer without VS Code, install the CLI once on your host (requires Node.js):
```bash
npm install -g @devcontainers/cli
@ -42,60 +144,42 @@ Open a shell in the running workspace container:
devcontainer exec --workspace-folder . bash
```
Run a one-off command from the host:
Run a one-off command from the host, e.g. starting the backend or the UI:
```bash
devcontainer exec --workspace-folder . bash scripts/start_services_dev.sh
devcontainer exec --workspace-folder . bash -lc 'cd ui && npm run dev -- --hostname 0.0.0.0'
```
### Backend Logs
## Fork and upstream remotes
Tail backend logs from inside the container:
The contributor bootstrap (`scripts/setup_fork.sh`) configures two remotes:
- `origin`: your fork, where you push
- `upstream`: `dograh-hq/dograh`, where new commits land
If you cloned `dograh-hq/dograh` directly instead of your fork, run it once (inside the devcontainer is fine):
```bash
tail -f logs/latest/*.log
bash scripts/setup_fork.sh
```
### Restarting the Backend
Re-run the same start script to restart. It reads the PID files under `run/`, terminates the previous services along with their descendants, and starts fresh ones.
To pull in upstream changes:
```bash
bash scripts/start_services_dev.sh
git fetch upstream
git checkout main
git merge upstream/main
git push origin main
```
Check your remotes any time with `git remote -v`. You should see:
```bash
origin https://github.com/<YOUR_HANDLE>/dograh.git (fetch/push)
upstream https://github.com/dograh-hq/dograh.git (fetch/push)
```
<Note>
`uvicorn` runs with `--reload --reload-dir api`, so edits under `api/` are picked up automatically. The other services (`ari_manager`, `campaign_orchestrator`, `arq`) do not auto-reload; re-run the start script after changing code they execute.
Always push feature branches to **`origin`** (your fork), then open a pull request against `dograh-hq/dograh:main`. Never push directly to `upstream`.
</Note>
### When to Rebuild the Container
The workspace bind mount and the `venv` / `node_modules` named volumes persist across container restarts, so you rarely need to rebuild. Rebuild only when one of these changes:
- `.devcontainer/Dockerfile` or `.devcontainer/devcontainer.json`
- `api/requirements.txt` or `api/requirements.dev.txt`
- The `pipecat/` submodule
Plain source edits, `ui/package.json`, and the `.env.example` templates do **not** require a rebuild. After a `git pull`, a quick check:
```bash
git diff HEAD@{1} HEAD -- .devcontainer api/requirements.txt api/requirements.dev.txt pipecat
```
If the diff is empty, you can keep your current container.
### Personal Install Hook
Anything you install inside the container outside the named volumes, notably under `/home/vscode`, is wiped on rebuild. This includes `npm i -g` packages and tools like the Claude or Codex CLIs.
To reinstall personal tooling automatically on every rebuild, drop an executable script at `.devcontainer/install.local.sh`. It is gitignored and runs at the tail of the post-create bootstrap. Example:
```bash
#!/usr/bin/env bash
set -euo pipefail
command -v claude >/dev/null 2>&1 || curl -fsSL https://claude.ai/install.sh | bash
command -v codex >/dev/null 2>&1 || npm i -g @openai/codex
```
Keep entries idempotent with `command -v` or a marker file so re-runs are cheap and safe.

136
docs/contribution/setup.mdx
View file

@ -1,80 +1,102 @@
---
title: Setup
description: Set up the Dograh contributor environment with the devcontainer-first workflow.
description: Get a Dograh dev environment running and learn the daily commands.
---
<Note>
If the steps below do not work for you, please open an issue on [GitHub](https://github.com/dograh-hq/dograh/issues).
</Note>
Dograh is a Next.js UI (`ui/`), a FastAPI backend (`api/`), and a [Pipecat](https://github.com/pipecat-ai/pipecat)-based voice pipeline (`pipecat/`, a git submodule), backed by Postgres, Redis, and MinIO.
<Tip>
**Using Claude Code or Codex?** Install the official Dograh setup skill and let your agent walk you through the contributor setup — it covers both the devcontainer and host-managed paths, runs Dograh's own scripts, and verifies the stack is healthy.
<CodeGroup>
```text Claude Code
/plugin marketplace add dograh-hq/dograh-plugins
/plugin install dograh@dograh
```
```text Codex
codex plugin marketplace add dograh-hq/dograh-plugins
codex plugin add dograh@dograh
```
</CodeGroup>
Start a new session, then ask it to *"set up Dograh for development"* (or run `/dograh-setup develop` in Claude Code). More at [dograh-hq/dograh-plugins](https://github.com/dograh-hq/dograh-plugins).
**Using Claude Code or Codex?** Install the [Dograh setup skill](https://github.com/dograh-hq/dograh-plugins) (`/plugin marketplace add dograh-hq/dograh-plugins`, then `/plugin install dograh@dograh`) and ask your agent to *"set up Dograh for development"* — it runs the steps below for you and verifies the stack is healthy.
</Tip>
### Recommended: Devcontainer Setup
## Set up
#### System Requirements
- Git
- Docker Desktop or another local Docker engine
- For the IDE path: VS Code with the [Dev Containers extension](https://marketplace.visualstudio.com/items?itemName=ms-vscode-remote.remote-containers)
- For the terminal-only path: Node.js on your host so you can install the Dev Container CLI
You need Git, a local Docker engine (such as Docker Desktop), and VS Code with the [Dev Containers extension](https://marketplace.visualstudio.com/items?itemName=ms-vscode-remote.remote-containers).
1. Fork [dograh-hq/dograh](https://github.com/dograh-hq/dograh) and clone **your fork**:
1. Fork the Dograh repository at https://github.com/dograh-hq/dograh
2. Clone **your fork**:
```bash
git clone https://github.com/<GITHUB_HANDLE>/dograh
git clone https://github.com/<YOUR_HANDLE>/dograh
cd dograh
```
3. Start the devcontainer.
In VS Code, open the repository and run **Dev Containers: Reopen in Container**.
2. 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 `.env` files, and installs UI dependencies. Later opens are fast.
3. 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:
Without an IDE, use the Dev Container CLI:
```bash
npm install -g @devcontainers/cli
devcontainer up --workspace-folder .
devcontainer exec --workspace-folder . bash
```
4. Wait for the first build to finish. The first build takes several minutes; subsequent opens are much faster.
5. Start the backend from a terminal inside the container:
```bash
bash scripts/start_services_dev.sh
```
Without an IDE, run the same command from your host:
4. Start the UI from a second terminal inside the container:
```bash
devcontainer exec --workspace-folder . bash scripts/start_services_dev.sh
```
6. Start the UI from another terminal inside the container:
```bash
cd ui
npm run dev -- --hostname 0.0.0.0
cd ui && npm run dev -- --hostname 0.0.0.0
```
Without an IDE, use another host terminal:
```bash
devcontainer exec --workspace-folder . bash -lc 'cd ui && npm run dev -- --hostname 0.0.0.0'
```
7. Verify that the backend is healthy:
```bash
curl -X GET localhost:8000/api/v1/health
```
8. Open the app at `http://localhost:3000`.
5. Open the app at `http://localhost:3000`.
### More Setup Options
If these steps do not work for you, please open an issue on [GitHub](https://github.com/dograh-hq/dograh/issues).
- For what the devcontainer bootstrap does, rebuild guidance, logs, and personal install hooks, see [Devcontainer Workflow](/contribution/devcontainer).
- If you cloned `dograh-hq/dograh` directly instead of your fork, see [Fork Workflow](/contribution/fork-workflow) to reset `origin` and `upstream`.
- If you do not want to use the devcontainer, see [Host-managed Setup](/contribution/host-managed-setup).
<AccordionGroup>
<Accordion title="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](/contribution/reference#fork-and-upstream-remotes).
</Accordion>
<Accordion title="No VS Code? No devcontainer at all?">
The devcontainer also runs headless via the [Dev Container CLI](/contribution/reference#dev-container-cli), or you can run everything [directly on your host](/contribution/reference#host-managed-setup).
</Accordion>
</AccordionGroup>
## 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:
1. Stop the script-managed backend if it is running, so the ports are free:
```bash
bash scripts/stop_services.sh
```
2. 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 |
All configurations load `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
1. Create a branch and make your change.
2. Push to your fork (`origin`) and open a pull request against `dograh-hq/dograh:main`.
3. A maintainer reviews and merges.
Bug reports and feature ideas go through [GitHub Issues](https://github.com/dograh-hq/dograh/issues) and [Ideas](https://github.com/orgs/dograh-hq/discussions/categories/ideas). Issues tagged `good first issue` are a good place to start. For questions while you're working, use the [Dograh Community Slack](https://join.slack.com/t/dograh-community/shared_invite/zt-3zjb5vwvl-j7hRz3_F1SOn5cH~jm5f5g).
Deploying your own build instead of contributing upstream? See [Deployments](/deployment/introduction) instead.