From 0881d7fc4ef8bee10b9a17253dceba8241139d9f Mon Sep 17 00:00:00 2001
From: Luan Vu <luanvuseo@gmail.com>
Date: Tue, 24 Mar 2026 10:00:13 +0700
Subject: [PATCH] docs: use make up in Docker quick start, add optional service
 flags (#404)

- Update README Docker section to use `make up` instead of raw
  docker compose commands. `make up` handles network creation,
  version embedding from git tags, and database migrations.

- Add WITH_* flags to Makefile for optional compose services:
  WITH_BROWSER, WITH_OTEL, WITH_SANDBOX, WITH_TAILSCALE, WITH_REDIS.
  Uses WITH_ prefix to avoid conflicts with common env vars (e.g.
  BROWSER is set by many desktop environments).

- Document common make commands (up/down/logs/reset) and optional
  service flags with descriptions in a table format.

Co-authored-by: Luvu182 <208665161+Luvu182@users.noreply.github.com>
---
 Makefile  | 19 ++++++++++++++++++-
 README.md | 36 +++++++++++++++++++++++++++++++++---
 2 files changed, 51 insertions(+), 4 deletions(-)

diff --git a/Makefile b/Makefile
index 82bdbbee..8f100cbd 100644
--- a/Makefile
+++ b/Makefile
@@ -16,7 +16,24 @@ clean:
 version:
 	@echo $(VERSION)
 
-COMPOSE = docker compose -f docker-compose.yml -f docker-compose.postgres.yml -f docker-compose.selfservice.yml
+COMPOSE_BASE = docker compose -f docker-compose.yml -f docker-compose.postgres.yml -f docker-compose.selfservice.yml
+COMPOSE_EXTRA =
+ifdef WITH_BROWSER
+COMPOSE_EXTRA += -f docker-compose.browser.yml
+endif
+ifdef WITH_OTEL
+COMPOSE_EXTRA += -f docker-compose.otel.yml
+endif
+ifdef WITH_SANDBOX
+COMPOSE_EXTRA += -f docker-compose.sandbox.yml
+endif
+ifdef WITH_TAILSCALE
+COMPOSE_EXTRA += -f docker-compose.tailscale.yml
+endif
+ifdef WITH_REDIS
+COMPOSE_EXTRA += -f docker-compose.redis.yml
+endif
+COMPOSE = $(COMPOSE_BASE) $(COMPOSE_EXTRA)
 UPGRADE = docker compose -f docker-compose.yml -f docker-compose.postgres.yml -f docker-compose.upgrade.yml
 
 net:
diff --git a/README.md b/README.md
index 5db52add..967e91e1 100644
--- a/README.md
+++ b/README.md
@@ -132,16 +132,46 @@ source .env.local && ./goclaw
 chmod +x prepare-env.sh && ./prepare-env.sh
 
 # Add at least one GOCLAW_*_API_KEY to .env, then:
-docker compose -f docker-compose.yml -f docker-compose.postgres.yml \
-  -f docker-compose.selfservice.yml up -d
+make up
 
 # Web Dashboard at http://localhost:3000
 # Health check: curl http://localhost:18790/health
 ```
 
+`make up` creates a Docker network, embeds the correct version from git tags, builds and starts all services, and runs database migrations automatically.
+
+**Common commands:**
+
+```bash
+make up                # Start all services (build + migrate)
+make down              # Stop all services
+make logs              # Tail logs (goclaw service)
+make reset             # Wipe volumes and rebuild from scratch
+```
+
+**Optional services** — enable with `WITH_*` flags:
+
+| Flag | Service | What it does |
+|------|---------|-------------|
+| `WITH_BROWSER=1` | Headless Chrome | Enables `browser` tool for web scraping, screenshots, automation |
+| `WITH_OTEL=1` | Jaeger | OpenTelemetry tracing UI for debugging LLM calls and latency |
+| `WITH_SANDBOX=1` | Docker sandbox | Isolated container for running untrusted code from agents |
+| `WITH_TAILSCALE=1` | Tailscale | Expose gateway over Tailscale private network |
+| `WITH_REDIS=1` | Redis | Redis-backed caching layer |
+
+Flags can be combined and work with all commands:
+
+```bash
+# Start with browser automation and tracing
+make up WITH_BROWSER=1 WITH_OTEL=1
+
+# Stop everything including optional services
+make down WITH_BROWSER=1 WITH_OTEL=1
+```
+
 When `GOCLAW_*_API_KEY` environment variables are set, the gateway auto-onboards without interactive prompts — detects provider, runs migrations, and seeds default data.
 
-> For build variants (OTel, Tailscale, Redis), Docker image tags, and compose overlays, see the [Deployment Guide](https://docs.goclaw.sh/#deploy-docker-compose).
+> For detailed configuration and Docker image tags, see the [Deployment Guide](https://docs.goclaw.sh/#deploy-docker-compose).
 
 ## Multi-Agent Orchestration