mirror of
https://github.com/dograh-hq/dograh.git
synced 2026-06-16 08:25:18 +02:00
feat: add devcontainer based setup (#352)
* feat: add devcontainer for local setup * feat: add local install hook * feat: add devcontainer based setup docs * feat: use uv in api/Dockerfile * fix: fix CI scripts * fix: fix post job cleanup step
This commit is contained in:
Abhishek
GitHub
parent
285de92528
commit
0716582aa7
31 changed files with 971 additions and 227 deletions
101
docs/contribution/devcontainer.mdx
Normal file
101
docs/contribution/devcontainer.mdx
Normal file
|
|
@ -0,0 +1,101 @@
|
|||
---
|
||||
title: Devcontainer Workflow
|
||||
description: Details for running and maintaining the Dograh devcontainer.
|
||||
---
|
||||
|
||||
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).
|
||||
|
||||
### What the Bootstrap Does
|
||||
|
||||
While the container starts, the devcontainer will:
|
||||
|
||||
- Initialize the `pipecat` git submodule on the host through `initializeCommand`
|
||||
- Bring up `postgres`, `redis`, and `minio` through Docker Compose and wait for them to be healthy
|
||||
- Seed the `venv` named volume from the image-baked Python 3.13 venv
|
||||
- Reinstall `pipecat` as editable from the bind-mounted submodule so source edits take effect
|
||||
- Create `api/.env`, `api/.env.test`, and `ui/.env` from their `*.example` templates if they do not already exist
|
||||
- Run `npm ci` for `ui/` and `api/mcp_server/ts_validator/`
|
||||
|
||||
In the API env files, `localhost` for Postgres, Redis, and MinIO is rewritten to the docker network aliases `postgres`, `redis`, and `minio`. `MINIO_PUBLIC_ENDPOINT` deliberately stays on `localhost` because the browser on your host loads from it.
|
||||
|
||||
<Note>
|
||||
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
|
||||
|
||||
Install the CLI once on your host:
|
||||
|
||||
```bash
|
||||
npm install -g @devcontainers/cli
|
||||
```
|
||||
|
||||
Start or rebuild the container from the repository root:
|
||||
|
||||
```bash
|
||||
devcontainer up --workspace-folder .
|
||||
```
|
||||
|
||||
Open a shell in the running workspace container:
|
||||
|
||||
```bash
|
||||
devcontainer exec --workspace-folder . bash
|
||||
```
|
||||
|
||||
Run a one-off command from the host:
|
||||
|
||||
```bash
|
||||
devcontainer exec --workspace-folder . bash scripts/start_services_dev.sh
|
||||
```
|
||||
|
||||
### Backend Logs
|
||||
|
||||
Tail backend logs from inside the container:
|
||||
|
||||
```bash
|
||||
tail -f logs/latest/*.log
|
||||
```
|
||||
|
||||
### 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>
|
||||
|
||||
### 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.
|
||||
41
docs/contribution/fork-workflow.mdx
Normal file
41
docs/contribution/fork-workflow.mdx
Normal file
|
|
@ -0,0 +1,41 @@
|
|||
---
|
||||
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
Normal file
67
docs/contribution/host-managed-setup.mdx
Normal file
|
|
@ -0,0 +1,67 @@
|
|||
---
|
||||
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`.
|
||||
|
|
@ -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.
|
||||
---
|
||||
|
|
@ -1,151 +1,63 @@
|
|||
---
|
||||
title: Setup
|
||||
description: You can use this document to setup the dev environment for yourself.
|
||||
description: Set up the Dograh contributor environment with the 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
|
||||
|
||||
<Note>
|
||||
All commands below are shown for **macOS / Linux**. Expand the **Windows** tab for the PowerShell equivalent where it differs.
|
||||
</Note>
|
||||
#### 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
|
||||
|
||||
### 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.
|
||||
<CodeGroup>
|
||||
```bash macOS/Linux
|
||||
bash scripts/setup_fork.sh
|
||||
```
|
||||
```powershell Windows
|
||||
.\scripts\setup_fork.ps1
|
||||
```
|
||||
</CodeGroup>
|
||||
Activate the venv (the bootstrap script created it but won't activate it for you):
|
||||
<CodeGroup>
|
||||
```bash macOS/Linux
|
||||
source venv/bin/activate
|
||||
```
|
||||
```powershell Windows
|
||||
.\venv\Scripts\Activate.ps1
|
||||
```
|
||||
</CodeGroup>
|
||||
4. Ensure you are on right version of Node.js using `node --version`
|
||||
```
|
||||
nvm use 24
|
||||
```
|
||||
5. Install UI dependencies
|
||||
```
|
||||
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>
|
||||
```
|
||||
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.).
|
||||
<CodeGroup>
|
||||
```bash macOS/Linux
|
||||
# Default (runtime only)
|
||||
bash scripts/setup_requirements.sh
|
||||
3. Start the devcontainer.
|
||||
|
||||
# Include pipecat dev dependencies
|
||||
bash scripts/setup_requirements.sh --dev
|
||||
```
|
||||
```powershell Windows
|
||||
# Default (runtime only)
|
||||
.\scripts\setup_requirements.ps1
|
||||
In VS Code, open the repository and run **Dev Containers: Reopen in Container**.
|
||||
|
||||
# Include pipecat dev dependencies
|
||||
.\scripts\setup_requirements.ps1 -Dev
|
||||
Without an IDE, use the Dev Container CLI:
|
||||
```bash
|
||||
npm install -g @devcontainers/cli
|
||||
devcontainer up --workspace-folder .
|
||||
devcontainer exec --workspace-folder . bash
|
||||
```
|
||||
</CodeGroup>
|
||||
8. Start backend services
|
||||
<CodeGroup>
|
||||
```bash macOS/Linux
|
||||
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
|
||||
```
|
||||
```powershell Windows
|
||||
.\scripts\start_services_dev.ps1
|
||||
|
||||
Without an IDE, run the same command from your host:
|
||||
```bash
|
||||
devcontainer exec --workspace-folder . bash scripts/start_services_dev.sh
|
||||
```
|
||||
</CodeGroup>
|
||||
Verify that your backend server is running
|
||||
<CodeGroup>
|
||||
```bash macOS/Linux
|
||||
6. Start the UI from another terminal inside the container:
|
||||
```bash
|
||||
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
|
||||
```
|
||||
```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>
|
||||
8. Open the app at `http://localhost:3000`.
|
||||
|
||||
#### 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>
|
||||
### More Setup Options
|
||||
|
||||
<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
|
||||
```
|
||||
cd ui && npm run dev
|
||||
```
|
||||
10. You should be able to open the application on `localhost:3000` now
|
||||
|
||||
### 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:
|
||||
|
||||
```bash
|
||||
git fetch upstream
|
||||
git checkout main
|
||||
git merge upstream/main # or: git rebase upstream/main
|
||||
git push origin main
|
||||
```
|
||||
|
||||
Check your remotes any time with `git remote -v`. You should see:
|
||||
```
|
||||
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>
|
||||
|
||||
### 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.
|
||||
- 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).
|
||||
|
|
|
|||
|
|
@ -125,6 +125,16 @@
|
|||
"tab": "Developer",
|
||||
"icon": "code",
|
||||
"groups": [
|
||||
{
|
||||
"group": "Contribution",
|
||||
"pages": [
|
||||
"contribution/introduction",
|
||||
"contribution/setup",
|
||||
"contribution/devcontainer",
|
||||
"contribution/host-managed-setup",
|
||||
"contribution/fork-workflow"
|
||||
]
|
||||
},
|
||||
{
|
||||
"group": "Guides",
|
||||
"pages": [
|
||||
|
|
@ -152,13 +162,6 @@
|
|||
"deployment/update",
|
||||
"deployment/heroku"
|
||||
]
|
||||
},
|
||||
{
|
||||
"group": "Contribution",
|
||||
"pages": [
|
||||
"contribution/introduction",
|
||||
"contribution/setup"
|
||||
]
|
||||
}
|
||||
]
|
||||
},
|
||||
|
|
@ -292,7 +295,6 @@
|
|||
"search": {
|
||||
"prompt": "Search for Tools, Webhook, Deployment, etc..."
|
||||
},
|
||||
"openapi": "/api-reference/openapi.json",
|
||||
"customCSS": "/custom.css",
|
||||
"contextual": {
|
||||
"options": [
|
||||
|
|
@ -311,5 +313,8 @@
|
|||
"github": "https://github.com/dograh-hq",
|
||||
"linkedin": "https://linkedin.com/company/dograh"
|
||||
}
|
||||
},
|
||||
"api": {
|
||||
"openapi": "api-reference/openapi.json"
|
||||
}
|
||||
}
|
||||
|
|
|
|||
Loading…
Add table
Add a link
Reference in a new issue