diff --git a/docs/deployment/docker.mdx b/docs/deployment/docker.mdx index 7e075163..9c2fa5b9 100644 --- a/docs/deployment/docker.mdx +++ b/docs/deployment/docker.mdx @@ -113,12 +113,14 @@ curl -o setup_remote.sh https://raw.githubusercontent.com/dograh-hq/dograh/main/ The script will prompt you for: - Your server's public IP address - A password for the TURN server (optional, press Enter for default) +- Deployment mode — press Enter for **prebuilt** (pulls official images, the recommended default) or pick **build** to compile images from source. Use **build** when you maintain a fork or want to deploy local customizations — see [Building from source](#building-from-source) below. It will automatically: -- Download the docker-compose.yaml file +- 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 - Generate SSL certificates - Create an environment file with TURN server configuration +- Write a `docker-compose.override.yaml` with build directives (build mode only) ### Start the Application @@ -126,12 +128,20 @@ It will automatically: Please ensure that Docker Compose is installed on your machine before proceeding further. You can check whether its installed by running `docker compose version` command. If its not installed, please install it by following your server provider documentation. -After the setup script completes, start Dograh: +After the setup script completes, start Dograh. The script prints the exact command to run at the end — it differs slightly between modes: -```bash + +```bash Prebuilt mode cd dograh sudo docker compose --profile remote up --pull always ``` +```bash Build mode +cd dograh +sudo docker compose --profile remote up -d --build +``` + + +First boot in build mode takes several minutes — Docker has to build both the API and UI images before the stack comes up. ### Access Your Application @@ -162,6 +172,7 @@ The setup script creates the following files in the `dograh/` directory: | File | Purpose | |------|---------| | `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 | | `generate_certificate.sh` | Script to regenerate SSL certificates | @@ -169,5 +180,29 @@ The setup script creates the following files in the `dograh/` directory: | `certs/local.key` | SSL private key | | `.env` | Environment variables for TURN server | +### Building from source + +If you maintain a fork or want to ship local code changes without waiting for an official image release, pick **build** when the setup script prompts for deployment mode. + +In this mode the script: + +1. Clones the repo into `dograh/` (default: `dograh-hq/dograh@main`; the script will ask for an `owner/name` and `branch` so a fork can point at its own). +2. If you run the script from inside an existing dograh checkout, offers to use that checkout instead of cloning. +3. Generates a `docker-compose.override.yaml` next to `docker-compose.yaml` that swaps the `image:` directives for local `build:` directives. Docker Compose auto-loads the override file — you don't need to pass any `-f` flags. + +After editing `api/` or `ui/` code, rebuild and restart the affected service: + +```bash +cd dograh +sudo docker compose --profile remote build api # or ui +sudo docker compose --profile remote up -d +``` + +To revert to pulling official images, delete `docker-compose.override.yaml` and start the stack with `--pull always` as in the [prebuilt flow](#start-the-application). + + +Build mode is for **fork maintainers and self-hosters who want to deploy customized images** — not for active development on the code itself. For day-to-day contributor work (fast reload, IDE/LSP integration), use the [contributor setup](/contribution/setup) instead. + + ### Next Steps Now that you are able to create and test a voice agent, you can setup a custom domain and setup SSL using letsencrypt. Checkout [Custom Domain](custom-domain) for instructions on how to do that. diff --git a/docs/deployment/update.mdx b/docs/deployment/update.mdx index d4dc3a1f..bfa431d9 100644 --- a/docs/deployment/update.mdx +++ b/docs/deployment/update.mdx @@ -5,6 +5,10 @@ description: "Update your self-hosted Dograh stack to a newer image version" This guide covers updating a Dograh stack you've already deployed with [Docker](/deployment/docker) or a [custom domain](/deployment/custom-domain). You run commands from the same directory that contains your `docker-compose.yaml` (this is the `dograh/` directory if you used `setup_remote.sh`). + +This guide assumes you deployed in **prebuilt mode** — i.e. your stack pulls official `dograh-api` / `dograh-ui` images from a registry. If you deployed in **build mode** (a `docker-compose.override.yaml` exists in your `dograh/` directory), the update flow is different — see [Updating a source build](#updating-a-source-build) at the bottom. + + ## Find an image version Dograh publishes two images — `dograh-api` and `dograh-ui` — to both container registries: @@ -111,3 +115,24 @@ If something breaks, roll back by pinning the previous tag using the same proces Rolling back across a database migration is not always safe — if the newer release ran a schema migration, downgrading may leave the DB in a state the older API doesn't understand. If in doubt, [open an issue](https://github.com/dograh-hq/dograh/issues) before rolling back. + +## Updating a source build + +If you deployed in **build mode** (you'll have a `docker-compose.override.yaml` in your `dograh/` directory), there are no image tags to pull — you update by pulling new source and rebuilding: + +```bash +cd dograh +git pull +sudo docker compose --profile remote build +sudo docker compose --profile remote up -d +``` + +To roll back, check out an earlier commit or tag and rebuild: + +```bash +git checkout +sudo docker compose --profile remote build +sudo docker compose --profile remote up -d +``` + +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. diff --git a/scripts/setup_remote.sh b/scripts/setup_remote.sh index d02a313d..2b5a6fd1 100755 --- a/scripts/setup_remote.sh +++ b/scripts/setup_remote.sh @@ -48,8 +48,8 @@ fi if [[ -z "$DEPLOY_MODE" ]]; then echo "" echo -e "${YELLOW}Deployment mode:${NC}" - echo " 1) prebuilt — pull official dograh images (recommended, fastest)" - echo " 2) build — build images from source (for forks or local customizations)" + echo " 1) prebuilt - pull official dograh images (recommended, fastest)" + echo " 2) build - build images from source (for forks or local customizations)" read -p "Choose [1]: " mode_choice mode_choice="${mode_choice:-1}" case "$mode_choice" in @@ -59,7 +59,7 @@ if [[ -z "$DEPLOY_MODE" ]]; then esac fi -# Build mode needs source code — either use existing repo or clone fresh +# Build mode needs source code - either use existing repo or clone fresh if [[ "$DEPLOY_MODE" == "build" ]]; then if [[ -z "$REPO_SOURCE" ]]; then if [[ -d ".git" ]] && [[ -f "docker-compose.yaml" ]]; then @@ -95,6 +95,46 @@ fi # Telemetry opt-out (default: true) ENABLE_TELEMETRY="${ENABLE_TELEMETRY:-true}" +# Where setup artifacts (.env, certs, nginx.conf, etc.) will land. Build mode +# with an existing repo writes them next to docker-compose.yaml in cwd; +# everything else writes into a fresh dograh/ subdirectory. +if [[ "$DEPLOY_MODE" == "build" && "$REPO_SOURCE" == "existing" ]]; then + TARGET_DIR="." +else + TARGET_DIR="dograh" +fi + +# Refuse to overwrite an existing install - re-running this script would +# regenerate OSS_JWT_SECRET (invalidating logged-in sessions), reset the +# TURN secret (breaking WebRTC auth), and overwrite nginx.conf customizations. +# Set DOGRAH_FORCE_OVERWRITE=1 to bypass; DOGRAH_SKIP_DOWNLOAD=1 (used by e2e) +# also bypasses since those flows manage state themselves. +if [[ "$DOGRAH_FORCE_OVERWRITE" != "1" && "$DOGRAH_SKIP_DOWNLOAD" != "1" ]]; then + if [[ -f "$TARGET_DIR/.env" ]]; then + if [[ "$TARGET_DIR" == "." ]]; then + existing_path="$(pwd)/.env" + else + existing_path="$(pwd)/$TARGET_DIR/.env" + fi + echo "" + echo -e "${YELLOW}Detected an existing Dograh install:${NC}" + echo -e " ${YELLOW}$existing_path${NC}" + echo "" + echo -e "${RED}Refusing to continue - re-running setup would:${NC}" + echo -e "${RED} - overwrite .env (invalidates sessions, breaks TURN auth)${NC}" + echo -e "${RED} - regenerate SSL certificates${NC}" + echo -e "${RED} - reset nginx.conf and turnserver.conf customizations${NC}" + echo "" + echo -e "${BLUE}To upgrade an existing install, follow:${NC}" + echo -e " ${BLUE}https://docs.dograh.com/deployment/update${NC}" + echo "" + echo -e "${BLUE}To wipe state and reinstall from scratch, re-run with:${NC}" + echo -e " ${BLUE}DOGRAH_FORCE_OVERWRITE=1 ${NC}" + echo "" + exit 1 + fi +fi + # Total step count depends on mode (build adds the override-file step) if [[ "$DEPLOY_MODE" == "build" ]]; then TOTAL=7 @@ -116,7 +156,7 @@ if [[ "$DEPLOY_MODE" == "build" ]]; then fi echo "" -# Step 1: get the source — either the standalone compose file (prebuilt mode) +# Step 1: get the source - either the standalone compose file (prebuilt mode) # or the full repo (build mode). Skip the download/clone when # DOGRAH_SKIP_DOWNLOAD=1 (e.g. e2e tests that already have everything in place). if [[ "$DEPLOY_MODE" == "build" ]]; then @@ -168,7 +208,7 @@ server { ssl_protocols TLSv1.2 TLSv1.3; ssl_prefer_server_ciphers on; - # Backend API and WebSockets — bypass the UI, go straight to api:8000 + # Backend API and WebSockets - bypass the UI, go straight to api:8000 location /api/v1/ { proxy_pass http://api:8000; proxy_http_version 1.1;