gortium/openconcho
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs: document dev/prod compose modes and make targets

Browse Source 
README, docs/docker.md, and AGENTS.md now cover make compose-up (dev-forward,
builds from source) vs make compose-up-prod (pulls ghcr latest) and compose-down.
This commit is contained in:
Offending Commit
2026-06-02 13:51:23 -05:00
parent c9bd2db07d
commit e1285c73ad
3 changed files with 52 additions and 21 deletions
Download Patch File Download Diff File Expand all files Collapse all files

3
AGENTS.md
View File

@@ -17,6 +17,9 @@ Frontend UI for self-hosted Honcho instances — browse memories, peers, session
| `make test` | Vitest (unit + integration), excludes `e2e/` |
| `make test-e2e` | Playwright e2e (uncached) |
| `make smoke-docker` | Local: build image + hermetic smoke test of the `/api` proxy (Docker required) |
| `make compose-up` | Run the web container from source (dev-forward, builds) at :8080 |
| `make compose-up-prod` | Run the web container from the published image (pulls `ghcr…:latest`) |
| `make compose-down` | Stop + remove the web container |
| `make check` | lint + typecheck + test |
| `pnpm --filter @openconcho/desktop cargo-check` | Local Rust/Tauri compile check before pushing desktop changes |
| `pnpm --filter @openconcho/web generate:api` | Regen `src/api/schema.d.ts` from `openapi.json` |

28
README.md
View File

@@ -89,23 +89,29 @@ pnpm --filter @openconcho/desktop dev
### Docker (web app)
Run the web UI in a container — handy for adding it to a self-hosted Honcho
Compose stack. The image serves the SPA and reverse-proxies the Honcho API under
its own origin: the browser calls `/api` same-origin and names the upstream in an
The container serves the SPA and reverse-proxies the Honcho API under its own
origin: the browser calls `/api` same-origin and names the upstream in an
`X-Honcho-Upstream` header, so there's no browser CORS to configure.
Two Compose modes (the published image is `ghcr.io/offendingcommit/openconcho-web`):
```bash
docker run --rm -p 8080:8080 \
-e OPENCONCHO_DEFAULT_HONCHO_URL=http://host.docker.internal:8000 \
ghcr.io/offendingcommit/openconcho-web:latest
# Dev-forward — build from this repo and run your local changes:
OPENCONCHO_DEFAULT_HONCHO_URL=https://honcho.example.net make compose-up
# Production — pull the latest published image instead of building:
OPENCONCHO_DEFAULT_HONCHO_URL=https://honcho.example.net make compose-up-prod
make compose-down # stop + remove
# → http://localhost:8080
```
`OPENCONCHO_DEFAULT_HONCHO_URL` seeds the first instance (absolute URL).
`OPENCONCHO_UPSTREAM_ALLOWLIST` is an optional SSRF guard (comma-separated host
globs) for when you expose the proxy. To drop it into a Honcho Compose stack, use
the `openconcho` service in [`docker-compose.yml`](docker-compose.yml). Full
details and env vars are in [`docs/docker.md`](docs/docker.md).
`make compose-up` uses [`docker-compose.yml`](docker-compose.yml) (`build: .`);
`make compose-up-prod` layers [`docker-compose.prod.yml`](docker-compose.prod.yml)
to pull `ghcr…:latest`. `OPENCONCHO_DEFAULT_HONCHO_URL` seeds the first instance
(absolute URL); `OPENCONCHO_UPSTREAM_ALLOWLIST` is an optional SSRF guard
(comma-separated host globs) for when you expose the proxy. Full details and env
vars are in [`docs/docker.md`](docs/docker.md).
### Connecting to your instance

42
docs/docker.md
View File

@@ -15,18 +15,41 @@ applies**; the nginx→Honcho hop is server-side, where CORS is irrelevant. The
frontend stays the source of truth for which instance to talk to, so the
multi-instance switcher and the Fleet view keep working.
## Add it to a Honcho Compose stack (recommended)
## Compose: dev-forward vs prod
Honcho's self-hosting path is Docker Compose. Drop the `openconcho` service from
[`docker-compose.yml`](../docker-compose.yml) into the project that runs your
Honcho `api`:
Two Compose files, env/ports defined once in the base:
- **`docker-compose.yml`** — dev-forward: `build: .`, so it runs **your local source**.
- **`docker-compose.prod.yml`** — override that swaps the build for the **published
image** (`ghcr.io/offendingcommit/openconcho-web:latest`, `pull_policy: always`).
```bash
make compose-up # build from source + run → http://localhost:8080
make compose-up-prod # pull ghcr…:latest instead of building
make compose-down # stop + remove
```
`make compose-up-prod` expands to
`docker compose -f docker-compose.yml -f docker-compose.prod.yml up -d`. Set env
inline or via a `.env` file:
```bash
OPENCONCHO_DEFAULT_HONCHO_URL=https://honcho.example.net make compose-up-prod
```
The published image is multi-arch (amd64 + arm64); the first publish creates a
private GHCR package — make it public for unauthenticated pulls.
## Add it to an existing Honcho Compose stack
Drop the `openconcho` service into the project that runs your Honcho `api`,
pointing the seed at the api service (nginx resolves it on the compose network):
```yaml
services:
openconcho:
image: ghcr.io/offendingcommit/openconcho-web:latest
environment:
# Seeds the first instance; nginx resolves this on the compose network.
OPENCONCHO_DEFAULT_HONCHO_URL: http://api:8000
ports:
- "127.0.0.1:8080:8080"
@@ -39,14 +62,13 @@ services:
`OPENCONCHO_DEFAULT_HONCHO_URL` seeds the UI's first instance with an absolute
URL. The browser sends that URL in the `X-Honcho-Upstream` header; nginx (on the
compose network) forwards to it — **no browser CORS, and the API token never
leaves the origin.** The published image is multi-arch (amd64 + arm64); the first
publish creates a private GHCR package — make it public for unauthenticated pulls.
leaves the origin.**
## Standalone
## Standalone (no compose)
```bash
docker build -t openconcho-web .
docker run --rm -p 8080:8080 -e OPENCONCHO_DEFAULT_HONCHO_URL=http://host.docker.internal:8000 openconcho-web
docker run --rm -p 8080:8080 -e OPENCONCHO_DEFAULT_HONCHO_URL=http://host.docker.internal:8000 \
ghcr.io/offendingcommit/openconcho-web:latest
# → http://localhost:8080 · GET /healthz returns "ok"
```