apunkt/dograh
1
0
Fork 0
mirror of https://github.com/dograh-hq/dograh.git synced 2026-06-13 08:15:21 +02:00
Code Issues Projects Releases Packages Wiki Activity

feat: add devcontainer for local setup

Browse source
This commit is contained in:
Abhishek Kumar 2026-05-25 15:58:26 +05:30
parent a725fda274
commit 6b33addb25
26 changed files with 671 additions and 130 deletions
Download patch file Download diff file Expand all files Collapse all files

2
docs/contribution/introduction.mdx
View file

@ -1,4 +1,4 @@
---
title: Contribution
description: If you would like to set up the development environment and use a coding agent like Claude to make changes to the codebase, you can follow this document to help setup the right development environment for yourself.
description: If you would like to set up Dograh development environment in your IDE and use a coding agent like Claude/ Codex to make changes to the codebase, you can follow this document to help setup the right development environment for yourself.
---

161
docs/contribution/setup.mdx
View file

@ -1,29 +1,83 @@
---
title: Setup
description: You can use this document to setup the dev environment for yourself.
description: Use this page to set up the Dograh contributor environment, with a devcontainer-first workflow.
---
<Note>
If the below steps do not work out for you, it would be great if you can open an issue on [Github](https://github.com/dograh-hq/dograh/issues).
If the steps below do not work for you, please open an issue on [GitHub](https://github.com/dograh-hq/dograh/issues).
</Note>
### System Requirements
- git to clone the forked repository
- Node.js 24 to run the UI (we recommend using [NVM](https://github.com/nvm-sh/nvm) on macOS/Linux or [NVM for Windows](https://github.com/coreybutler/nvm-windows) on Windows to manage your node versions locally)
- Python 3.13 to run the backend
- Docker to run the database and redis cache locally
### Recommended: Devcontainer setup
#### System Requirements
- Git
- Docker Desktop or another local Docker engine
- A Dev Container-compatible editor. The most tested path is VS Code with the [Dev Containers extension](https://marketplace.visualstudio.com/items?itemName=ms-vscode-remote.remote-containers).
<Note>
All commands below are shown for **macOS / Linux**. Expand the **Windows** tab for the PowerShell equivalent where it differs.
The checked-in `.devcontainer/` follows the Dev Containers specification. VS Code is the default recommendation because its support is the most mature and best documented, but the same setup should also work in tools like Cursor and JetBrains IDEs that support Dev Containers.
</Note>
### Steps
1. Fork the Dograh repository by going to https://github.com/dograh-hq/dograh
2. Clone **your fork** on your machine. You can skip `--recurse-submodules` here — the bootstrap script in the next step will initialize submodules for you.
```
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
cd dograh
```
3. Run the contributor bootstrap. It configures `origin` (your fork) and `upstream` (`dograh-hq/dograh`), initializes the pipecat submodule, creates the Python venv, and copies the `.env` templates. Re-running it is safe — already-configured pieces are skipped.
If you cloned `dograh-hq/dograh` directly instead of your fork, run `bash scripts/setup_fork.sh` once inside the container after it boots to reset `origin` and `upstream`.
3. Open the repository in your Dev Container-compatible editor and start the devcontainer.
If you are using VS Code, run **Dev Containers: Reopen in Container**.
4. Wait for the first container boot to finish. The post-create bootstrap will:
- initialize the `pipecat` submodule
- create `venv/` with Python 3.13
- install backend dependencies with `scripts/setup_requirements.sh --dev`
- install `ui/` dependencies and `api/mcp_server/ts_validator` dependencies
- create `api/.env` and `ui/.env` if they do not already exist (rewriting docker network hostnames in `api/.env`)
- start `postgres`, `redis`, and `minio` via Docker Compose
5. Start the backend from a terminal inside the container:
```bash
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
```
7. Verify that the backend is healthy:
```bash
curl -X GET localhost:8000/api/v1/health
```
8. Open the app at `http://localhost:3000`.
You can tail backend logs from inside the container with:
```bash
tail -f logs/latest/*.log
```
The backend reads `api/.env` both on the host and inside the devcontainer. The post-create bootstrap rewrites `DATABASE_URL`, `REDIS_URL`, and `MINIO_ENDPOINT` to docker network aliases (`postgres`, `redis`, `minio`) when it creates the file. If you already had an `api/.env` from host development with `localhost` hosts for those, edit it before starting the backend inside the devcontainer.
#### 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.
```bash
bash scripts/start_services_dev.sh
```
<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.
</Note>
### Fallback: host-managed setup
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` (your fork) and `upstream` (`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
@ -32,7 +86,7 @@ bash scripts/setup_fork.sh
.\scripts\setup_fork.ps1
```
</CodeGroup>
Activate the venv (the bootstrap script created it but won't activate it for you):
2. Activate the virtual environment:
<CodeGroup>
```bash macOS/Linux
source venv/bin/activate
@ -41,45 +95,28 @@ source venv/bin/activate
.\venv\Scripts\Activate.ps1
```
</CodeGroup>
4. Ensure you are on right version of Node.js using `node --version`
```
3. Ensure your local Node version is 24:
```bash
nvm use 24
```
5. Install UI dependencies
```
4. Install UI dependencies:
```bash
cd ui && npm install && cd ..
```
6. Start local docker services
<Note>Please ensure you dont have any other instance of conflicting services running by checking `docker ps`</Note>
```
5. Start the local Docker services:
```bash
docker compose -f docker-compose-local.yaml up -d
```
Verify that the processes have started by running `docker ps`
```
abhishek$ docker ps
CONTAINER ID IMAGE COMMAND CREATED STATUS PORTS NAMES
9066b7244b2f postgres:17 "docker-entrypoint.s…" 18 seconds ago Up 18 seconds (healthy) 0.0.0.0:5432->5432/tcp, [::]:5432->5432/tcp dograh-postgres-1
6c7cb8afdf18 redis:7 "docker-entrypoint.s…" 18 seconds ago Up 18 seconds (healthy) 0.0.0.0:6379->6379/tcp, [::]:6379->6379/tcp dograh-redis-1
a57e3e92b02c minio/minio "/usr/bin/docker-ent…" 18 seconds ago Up 18 seconds (healthy) 127.0.0.1:9000-9001->9000-9001/tcp dograh-minio-1
```
7. Install Python requirements. The script installs `api/requirements.txt` and pipecat with the required extras. Add the dev flag if you also want the pipecat dev dependency group (pytest, ruff, pre-commit, etc.).
6. Install Python requirements:
<CodeGroup>
```bash macOS/Linux
# Default (runtime only)
bash scripts/setup_requirements.sh
# Include pipecat dev dependencies
bash scripts/setup_requirements.sh --dev
```
```powershell Windows
# Default (runtime only)
.\scripts\setup_requirements.ps1
# Include pipecat dev dependencies
.\scripts\setup_requirements.ps1 -Dev
```
</CodeGroup>
8. Start backend services
7. Start the backend services:
<CodeGroup>
```bash macOS/Linux
bash scripts/start_services_dev.sh
@ -88,44 +125,11 @@ bash scripts/start_services_dev.sh
.\scripts\start_services_dev.ps1
```
</CodeGroup>
Verify that your backend server is running
<CodeGroup>
```bash macOS/Linux
curl -X GET localhost:8000/api/v1/health
```
```powershell Windows
curl.exe http://localhost:8000/api/v1/health
```
</CodeGroup>
You would be able to see the logs in logs/ directory.
<CodeGroup>
```bash macOS/Linux
tail -f logs/latest/*.log
```
```powershell Windows
Get-Content logs/latest/*.log -Wait
```
</CodeGroup>
#### 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.
<CodeGroup>
```bash macOS/Linux
bash scripts/start_services_dev.sh
```
```powershell Windows
.\scripts\start_services_dev.ps1
```
</CodeGroup>
<Note>
`uvicorn` runs with `--reload --reload-dir api`, so edits under `api/` are picked up automatically — no restart needed. The other services (`ari_manager`, `campaign_orchestrator`, `arq`) do **not** auto-reload; re-run the start script after changing code they execute.
</Note>
9. Start the UI
```
8. Start the UI:
```bash
cd ui && npm run dev
```
10. You should be able to open the application on `localhost:3000` now
9. Open the application on `http://localhost:3000`.
### Keeping your fork in sync with upstream
The bootstrap script configures two remotes: `origin` (your fork, where you push) and `upstream` (`dograh-hq/dograh`, where new commits land). To pull in upstream changes:
@ -133,12 +137,13 @@ The bootstrap script configures two remotes: `origin` (your fork, where you push
```bash
git fetch upstream
git checkout main
git merge upstream/main # or: git rebase upstream/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)
```
@ -148,4 +153,4 @@ Always push feature branches to **`origin`** (your fork), then open a pull reque
</Note>
### Next Steps
We ship with AGENTS.md and CLAUDE.md which will help the Coding Agents get started quickly with the codebase. This should help your favourite coding agents to be able to navigate the codebase quickly and you can make changes to it and suit your specification better.
The repository ships with `AGENTS.md` and `CLAUDE.md` so coding agents can navigate the codebase quickly. Adjust them locally if you need agent-specific guidance for your workflow.

14
docs/docs.json
View file

@ -125,6 +125,13 @@
"tab": "Developer",
"icon": "code",
"groups": [
{
"group": "Contribution",
"pages": [
"contribution/introduction",
"contribution/setup"
]
},
{
"group": "Guides",
"pages": [
@ -152,13 +159,6 @@
"deployment/update",
"deployment/heroku"
]
},
{
"group": "Contribution",
"pages": [
"contribution/introduction",
"contribution/setup"
]
}
]
},