[Feature] First-class support for installing against existing/external infrastructure (BYO Postgres, Valkey, object storage, reverse proxy)

[deepflowteam]

Summary

Add a documented, script-supported "external infrastructure" install mode so self-hosters can run Paca against services they already operate (managed/shared PostgreSQL, a Redis-compatible cache, an S3-compatible store, an existing reverse proxy) instead of the bundled containers.

Problem

deploy/docker-compose.prod.yml + scripts/install.sh assume a greenfield host. They bundle postgres, valkey, minio, a Caddy gateway, and a db-backup sidecar. Anyone already running shared infra has to hand-edit the compose file and Caddyfile, which then makes install.sh / upgrade.sh unusable (they assume the bundled topology and rewrite those files on every run).

Partial escape hatches exist but are incomplete:

• --scale postgres=0 (+ DATABASE_URL) and --scale minio=0 (+ STORAGE_PROVIDER=s3) work, but there is no valkey equivalent — REDIS_URL is honored by the services, yet the bundled valkey container can't be cleanly dropped/tracked.
• There is no supported way to remove the bundled gateway and route through an existing external proxy. The bundled Caddy also serves plugin static assets (/plugins, /plugins-mcp, /plugins-skills) from named volumes and hosts the internal :8080 block that PACA_GATEWAY_URL points at — so removing it silently breaks plugins and agent-runner MCP/skill bundle loading unless you replicate the volume mounts + full route set in your own proxy.
• upgrade.sh records PACA_WEB / PACA_AGENT_RUNNER topology choices and re-applies them; there's no equivalent for "external postgres/valkey/storage/proxy", so upgrades can re-introduce bundled services.

The Helm chart already decomposes this cleanly (separate postgres / valkey / minio templates that can be disabled); Docker Compose is the gap.

Proposed Direction

1. --scale valkey=0 support with REDIS_URL, at parity with the existing postgres/minio external paths.
2. A supported "no bundled gateway" mode: either publish api / web / realtime on configurable host ports for an external proxy, or ship the canonical external-proxy route set + the three plugin-asset mount points in the repo, kept in sync per release the same way deploy/helm/paca/files/Caddyfile is.
3. A clear PACA_GATEWAY_URL story when the bundled gateway is absent (MCP/skill bundle serving).
4. install.sh / upgrade.sh record and re-apply all external-infra choices (env-var flags, same pattern as PACA_WEB / PACA_AGENT_RUNNER).
5. Optionally a thin deploy/docker-compose.external.yml overlay (only api / web / realtime / agent-runner), analogous to docker-compose.dev.yml.

Scope

• Product behavior
• Architecture
• Developer experience
• Documentation

Additional Context

I ran Paca this way against an existing stack (ParadeDB / a Redis-compatible cache / an S3-compatible store / a shared Caddy) by hand-editing the compose file and adding a site block to the existing proxy. It works, but every step was undocumented and won't survive upgrade.sh. Happy to share that config as a starting point or open a docs PR.

Tradeoff: larger support matrix and more config surface. Mitigation: most of this is documentation + one new --scale target + keeping the external-proxy route list in the repo (it already has to exist for Helm).

---

This is a really exciting project — the "agents and humans as equal teammates on the same board" model is genuinely novel, and making it easy to slot into an existing self-hosted stack would help it land with the homelab / self-hosting crowd. Thanks for building it in the open.

[pullfrog]

  ^{｜ Build this ➔ ｜ Make a plan ➔}

[pikann]

Thank you so much for your feedback! Please feel free to open a PR whenever you're ready