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

chore: refactor setup scrpts (#288)

Browse source 
* refactor setup scrpts

* update docker compose to use dograh-init

* avoid creating unnecessary conf files

* fix local setup script

* add agents.md
This commit is contained in:
Abhishek 2026-05-14 14:45:34 +05:30 • committed by GitHub
parent 4ff1f576f0
commit 87699f2dee
No known key found for this signature in database
GPG key ID: B5690EEEBB952194
18 changed files with 1321 additions and 1178 deletions
Download patch file Download diff file Expand all files Collapse all files

49
docs/deployment/custom-domain.mdx
View file

@ -75,9 +75,10 @@ It will automatically:
- Verify DNS configuration
- Install Certbot
- Generate Let's Encrypt SSL certificates
- Update nginx configuration
- Update the canonical public host/base URL settings in `.env`
- Validate the runtime config that `dograh-init` will render from `.env`
- Configure automatic certificate renewal
- Restart Dograh services
- Restart Dograh services through the validated startup wrapper
Once complete, your application will be available at `https://voice.yourcompany.com`.
@ -130,7 +131,7 @@ Replace `voice.yourcompany.com` with your actual domain name.
Certbot will:
1. Verify that you control the domain
2. Generate SSL certificates
3. Store them in `/etc/letsencrypt/archive/voice.yourcompany.com/`
3. Store them in `/etc/letsencrypt/live/voice.yourcompany.com/`
<Note>
You'll be prompted to enter an email address for renewal notifications and agree to the terms of service.
@ -142,44 +143,31 @@ Copy the generated certificates to the dograh certs directory:
```bash
cd dograh
sudo cp /etc/letsencrypt/archive/voice.yourcompany.com/fullchain1.pem certs/local.crt
sudo cp /etc/letsencrypt/archive/voice.yourcompany.com/privkey1.pem certs/local.key
sudo cp /etc/letsencrypt/live/voice.yourcompany.com/fullchain.pem certs/local.crt
sudo cp /etc/letsencrypt/live/voice.yourcompany.com/privkey.pem certs/local.key
sudo chmod 644 certs/local.crt certs/local.key
```
### Update nginx Configuration
### Update Canonical Public URL Settings
Update the nginx configuration to use your domain name. Open the nginx configuration file:
Update `.env` so the canonical remote settings point at your domain:
```bash
nano dograh/nginx.conf
nano dograh/.env
```
Update the `server_name` directive with your domain:
```nginx
server {
listen 443 ssl;
server_name voice.yourcompany.com;
ssl_certificate /etc/nginx/certs/local.crt;
ssl_certificate_key /etc/nginx/certs/local.key;
# ... rest of the configuration remains the same
}
```bash
PUBLIC_HOST=voice.yourcompany.com
PUBLIC_BASE_URL=https://voice.yourcompany.com
```
### Add environment variable
Replace `BACKEND_API_ENDPOINT` environment variable the `docker-compose.yaml` with your custom domain with the scheme.
### Start Dograh Services
Start Dograh with the updated configuration:
Start Dograh through the validated startup wrapper so `dograh-init` regenerates nginx and coturn runtime config before Docker starts:
```bash
cd dograh
sudo docker compose --profile remote up -d --pull always
./remote_up.sh
```
### Access Your Application
@ -207,8 +195,8 @@ Add the following content (replace paths as needed):
```bash
#!/bin/bash
# Copy renewed certificates to dograh certs directory
cp /etc/letsencrypt/archive/voice.yourcompany.com/fullchain1.pem /home/ubuntu/dograh/certs/local.crt
cp /etc/letsencrypt/archive/voice.yourcompany.com/privkey1.pem /home/ubuntu/dograh/certs/local.key
cp /etc/letsencrypt/live/voice.yourcompany.com/fullchain.pem /home/ubuntu/dograh/certs/local.crt
cp /etc/letsencrypt/live/voice.yourcompany.com/privkey.pem /home/ubuntu/dograh/certs/local.key
chmod 644 /home/ubuntu/dograh/certs/local.crt /home/ubuntu/dograh/certs/local.key
# Restart nginx to load new certificates
@ -243,7 +231,7 @@ If Certbot fails to generate certificates:
If you see SSL errors after setup:
1. Verify the certificates were copied correctly: `ls -la dograh/certs/`
2. Check that `nginx.conf` points to `/etc/nginx/certs/local.crt` and `/etc/nginx/certs/local.key`
2. Run `./remote_up.sh --preflight-only` in `dograh/` to verify the `dograh-init` runtime render matches `.env`
3. Restart the nginx container: `sudo docker compose --profile remote restart nginx`
### WebRTC Connection Issues
@ -251,5 +239,4 @@ If you see SSL errors after setup:
If voice calls don't connect after domain setup:
1. Ensure TCP/UDP ports 3478, 5349, and UDP 49152-49200 are still open
2. Update the `.env` file with your domain name if needed for TURN server configuration
2. Check that `PUBLIC_HOST` / `PUBLIC_BASE_URL` in `.env` match your domain, then re-run `./remote_up.sh`

17
docs/deployment/docker.mdx
View file

@ -66,7 +66,7 @@ The script will prompt you for:
- The host browsers should use to reach TURN (press Enter for `127.0.0.1`; use your LAN IP if testing from another device on the same network)
- A shared secret for the TURN server (press Enter to generate a random one)
It creates `docker-compose.yaml`, `turnserver.conf`, and a `.env` file with TURN credentials. Start the stack with the `local-turn` profile so coturn comes up alongside the other services:
It creates `docker-compose.yaml`, a `.env` file with TURN credentials, and the small helper bundle that `dograh-init` uses to render coturn config at startup. Start the stack with the `local-turn` profile so coturn comes up alongside the other services:
```bash
docker compose --profile local-turn up --pull always
@ -118,9 +118,10 @@ The script will prompt you for:
It will automatically:
- Get the source — `docker-compose.yaml` only (prebuilt mode), or clone the full repo (build mode)
- Create and configure nginx.conf with your IP address
- Download the validated remote deployment helper bundle
- Generate SSL certificates
- Create an environment file with TURN server configuration
- Validate the runtime config that `dograh-init` will render from `.env`
- Write a `docker-compose.override.yaml` with build directives (build mode only)
### Start the Application
@ -134,11 +135,11 @@ After the setup script completes, start Dograh. The script prints the exact comm
<CodeGroup>
```bash Prebuilt mode
cd dograh
sudo docker compose --profile remote up --pull always
./remote_up.sh
```
```bash Build mode
cd dograh
sudo docker compose --profile remote up -d --build
./remote_up.sh --build
```
</CodeGroup>
@ -174,12 +175,14 @@ The setup script creates the following files in the `dograh/` directory:
|------|---------|
| `docker-compose.yaml` | Main Docker Compose configuration |
| `docker-compose.override.yaml` | Build directives for `api` and `ui` (**build mode only**) |
| `turnserver.conf` | Configuration for TURN server |
| `nginx.conf` | nginx reverse proxy configuration with your IP |
| `remote_up.sh` | Validated startup wrapper for the remote stack |
| `scripts/run_dograh_init.sh` | One-shot init renderer/validator used by Docker Compose |
| `scripts/lib/setup_common.sh` | Shared deployment helper library |
| `deploy/templates/` | nginx and coturn runtime config templates |
| `generate_certificate.sh` | Script to regenerate SSL certificates |
| `certs/local.crt` | Self-signed SSL certificate |
| `certs/local.key` | SSL private key |
| `.env` | Environment variables (TURN secret, JWT secret, FastAPI worker count) |
| `.env` | Single source of truth for deployment settings (TURN secret, JWT secret, FastAPI worker count, public host/base URL) |
### Building from source

48
docs/deployment/scaling.mdx
View file

@ -8,7 +8,7 @@ By default, the Dograh API container runs a single uvicorn worker. For productio
This page covers how the multi-worker setup works, how to choose a worker count at install time, and how to change it on a running stack.
<Warning>
Multi-worker support requires **Dograh v1.29.0 or newer**. Earlier releases used `uvicorn --workers` and ship a different `setup_remote.sh` / `start_services_docker.sh` / `nginx.conf` layout — the steps below will not work on them. If your stack is older, [update first](/deployment/update) and then come back to this page.
Multi-worker support requires **Dograh v1.29.0 or newer**. Earlier releases used `uvicorn --workers` and a different remote deployment layout. If your stack is older, [update first](/deployment/update) and then come back to this page.
</Warning>
## How it works
@ -58,23 +58,11 @@ Press Enter for the default (`4`) or enter a different positive integer. Non-int
SERVER_IP=... TURN_SECRET=... FASTAPI_WORKERS=8 ./setup_remote.sh
```
The script wires the value into two places:
- **`.env`** — sets `FASTAPI_WORKERS=N`, which `docker-compose.yaml` substitutes into the API container's environment.
- **`nginx.conf`** — generates an `upstream dograh_api` block with one `server api:800X` entry per worker.
Both must agree, which is why the script generates them together.
The script stores the value in **`.env`** (`FASTAPI_WORKERS=N`). The supported startup path (`./remote_up.sh`) preflights the `dograh-init` render from that value before every remote start, so nginx and the API worker count stay aligned.
## Changing the worker count on a running stack
Once Dograh is running, increasing or decreasing the worker count is a two-file edit plus a restart. You'll touch:
1. **`.env`** — controls how many uvicorn processes the API container spawns.
2. **`nginx.conf`** — controls which worker ports nginx forwards to.
<Warning>
Both files must stay in sync. If `.env` says `FASTAPI_WORKERS=8` but `nginx.conf` only lists 4 upstream servers, half your workers will be idle. If `nginx.conf` lists more upstreams than there are workers, those upstreams will throw connection errors and trip the `proxy_next_upstream` fallback.
</Warning>
Once Dograh is running, increasing or decreasing the worker count is a one-file edit plus a restart. Change `.env`, then start through `./remote_up.sh` so `dograh-init` regenerates nginx runtime config before Docker starts the stack.
### Steps
@ -90,41 +78,21 @@ FASTAPI_WORKERS=4
FASTAPI_WORKERS=8
```
**2. Edit `nginx.conf`** and update the `upstream dograh_api` block so it has exactly one `server api:800X` line per worker, with ports starting at `8000`:
```nginx
upstream dograh_api {
least_conn;
server api:8000 max_fails=3 fail_timeout=10s;
server api:8001 max_fails=3 fail_timeout=10s;
server api:8002 max_fails=3 fail_timeout=10s;
server api:8003 max_fails=3 fail_timeout=10s;
server api:8004 max_fails=3 fail_timeout=10s; # ← new
server api:8005 max_fails=3 fail_timeout=10s; # ← new
server api:8006 max_fails=3 fail_timeout=10s; # ← new
server api:8007 max_fails=3 fail_timeout=10s; # ← new
keepalive 32;
}
```
To **scale down**, remove the trailing `server` lines so the list matches the new `FASTAPI_WORKERS` value.
**3. Recreate the affected containers.** The simplest path — brief downtime, no surprises:
**2. Recreate the stack through the validated wrapper.** The simplest path — brief downtime, no surprises:
```bash
sudo docker compose --profile remote down
sudo docker compose --profile remote up -d
./remote_up.sh
```
If you want to avoid downtime and your stack is healthy, you can recreate only the `api` and `nginx` containers:
```bash
sudo docker compose --profile remote up -d --force-recreate api nginx
./remote_up.sh -- api nginx
```
`--force-recreate` ensures the api container picks up the new `FASTAPI_WORKERS` value and nginx re-reads the updated `nginx.conf` (which is mounted read-only from disk).
`remote_up.sh` validates `.env`, runs the same `dograh-init` render that Compose will use at startup, runs `docker compose config -q`, and then starts the requested services.
**4. Verify.** Confirm the right number of uvicorn processes are running. The API image is slim and doesn't include `ps`, so use Docker's host-side view instead:
**3. Verify.** Confirm the right number of uvicorn processes are running. The API image is slim and doesn't include `ps`, so use Docker's host-side view instead:
```bash
sudo docker compose --profile remote top api | grep uvicorn

18
docs/deployment/update.mdx
View file

@ -37,8 +37,8 @@ Always update **`dograh-api`** and **`dograh-ui`** to the **same tag**. The two
- Asks for a target version (defaults to the latest release tag on GitHub).
- Pulls `docker-compose.yaml` at that version and pins both `api` and `ui` images to it.
- Regenerates `nginx.conf` and `turnserver.conf` from the upstream templates, so newer features (like [multi-worker scaling](/deployment/scaling)) are wired up correctly without manual editing.
- Reads your existing `.env` and appends any new required keys with safe defaults — your `OSS_JWT_SECRET`, `TURN_SECRET`, and other values are never touched.
- Refreshes the remote helper bundle (`remote_up.sh` plus shared templates/helpers).
- Synchronizes the canonical remote keys in `.env` and validates the runtime config that `dograh-init` will render from it.
- Backs up every file it changes with a `.bak.<timestamp>` suffix.
From your install directory:
@ -55,15 +55,14 @@ You'll be prompted for the target version, defaulting to the most recent release
TARGET_VERSION=1.28.0 DOGRAH_UPDATE_YES=1 bash update_remote.sh
```
After the script finishes, apply the update by recreating the stack:
After the script finishes, apply the update through the validated startup wrapper:
```bash
sudo docker compose --profile remote down
sudo docker compose --profile remote up -d --pull always
./remote_up.sh
```
<Note>
The script overwrites `docker-compose.yaml`, `nginx.conf`, and `turnserver.conf` from upstream templates. If you've made local edits to any of these (extra environment variables, custom ports, modified nginx routes), check the `.bak.<timestamp>` files after the update and re-apply your edits.
The script overwrites `docker-compose.yaml` and the remote helper bundle (`remote_up.sh`, `scripts/run_dograh_init.sh`, `scripts/lib/setup_common.sh`, and `deploy/templates/*`) from the shared upstream deployment bundle. If you've made local edits to any of these, check the `.bak.<timestamp>` files after the update and re-apply your edits.
</Note>
## Local deployment
@ -100,11 +99,10 @@ curl http://localhost:8000/api/v1/health # local
```bash
cd dograh
for f in docker-compose.yaml nginx.conf turnserver.conf .env; do
for f in docker-compose.yaml nginx.conf turnserver.conf .env remote_up.sh scripts/run_dograh_init.sh scripts/lib/setup_common.sh deploy/templates/nginx.remote.conf.template deploy/templates/turnserver.remote.conf.template; do
[[ -f "$f.bak.<timestamp>" ]] && cp "$f.bak.<timestamp>" "$f"
done
sudo docker compose --profile remote down
sudo docker compose --profile remote up -d
./remote_up.sh
```
Your Postgres data volume persists across `down`/`up` cycles, so agents and call history are preserved.
@ -138,6 +136,6 @@ sudo docker compose --profile remote up -d
If you update the `pipecat` submodule, you **must** run `git submodule update --init --recursive` before rebuilding, or the Docker build will not pick up `pipecat` changes.
</Warning>
If you maintain a fork with local customizations on top of upstream, merging conflicts in `docker-compose.yaml`, `nginx.conf`, `turnserver.conf`, or `setup_remote.sh` is up to you — resolve them as you would any other git merge. Leave `OSS_JWT_SECRET` and `TURN_SECRET` in `.env` unchanged across updates to preserve sessions and WebRTC auth.
If you maintain a fork with local customizations on top of upstream, merging conflicts in `docker-compose.yaml`, `remote_up.sh`, `scripts/run_dograh_init.sh`, `deploy/templates/*`, or `setup_remote.sh` is up to you — resolve them as you would any other git merge. Leave `OSS_JWT_SECRET` and `TURN_SECRET` in `.env` unchanged across updates to preserve sessions and WebRTC auth.
The same migration warning above applies: rolling back across a schema change can leave the DB in a state the older API can't read.