chore: update documentation

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.
 </Note>
 
-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
+<CodeGroup>
+```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
+```
+</CodeGroup>
+
+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).
+
+<Note>
+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.
+</Note>
+
 ### 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.

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`).
 
+<Note>
+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.
+</Note>
+
 ## 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
 <Warning>
 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.
 </Warning>
+
+## 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 <previous-tag-or-sha>
+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.