From 7babd4fce7b4251eab45199516b46718601dd433 Mon Sep 17 00:00:00 2001 From: Kellan Drucquer Date: Sat, 4 Apr 2026 03:54:16 -0400 Subject: [PATCH] switch docker deployment to a shared npm network --- deployment/docker/.env.example | 2 ++ deployment/docker/README.md | 27 +++++++++++++++++++-------- deployment/docker/docker-compose.yml | 8 ++++---- 3 files changed, 25 insertions(+), 12 deletions(-) diff --git a/deployment/docker/.env.example b/deployment/docker/.env.example index bbaf268..3d305fe 100644 --- a/deployment/docker/.env.example +++ b/deployment/docker/.env.example @@ -6,6 +6,8 @@ REDIS_URL=redis://redis:6379 API_PORT=4000 REST_DEFAULT_LIMIT=200 +NPM_SHARED_NETWORK=npm-shared + # Recommended with NPM on the same Docker network: # app. -> web:3000 # api. -> api:4000 diff --git a/deployment/docker/README.md b/deployment/docker/README.md index 830f545..29a04d8 100644 --- a/deployment/docker/README.md +++ b/deployment/docker/README.md @@ -6,7 +6,7 @@ It is separate from the repo-root `docker-compose.yml`, which is still the light ## What this stack does -- Assumes Nginx Proxy Manager is the edge proxy and runs on the shared Docker network named `bridge`. +- Assumes Nginx Proxy Manager is the edge proxy and runs on a shared user-defined Docker network. - Keeps `web` and `api` internal to the Docker network instead of publishing host ports. - Targets a two-subdomain routing model by default: - `app.` -> `web:3000` @@ -28,7 +28,7 @@ It is separate from the repo-root `docker-compose.yml`, which is still the light - A Linux VPS with Docker Engine and Docker Compose v2 installed - Enough RAM for ClickHouse plus the Bun services - Nginx Proxy Manager running in Docker on the same host -- A shared Docker network named `bridge` +- A shared user-defined Docker network for NPM and this stack Optional: @@ -50,10 +50,21 @@ Important defaults: - `NATS_URL`, `CLICKHOUSE_URL`, and `REDIS_URL` should stay on the internal container hostnames unless you intentionally split infra out. - `OPTIONS_INGEST_ADAPTER=synthetic` and `EQUITIES_INGEST_ADAPTER=synthetic` are the safest first boot settings. +- `NPM_SHARED_NETWORK=npm-shared` is the recommended external Docker network name for NPM and this stack. - `NEXT_PUBLIC_API_URL=https://api.example.com` is the recommended production shape when using NPM with two subdomains. 3. Build and start the stack: +If you have not created the shared Docker network yet, do that once first: + +```bash +docker network create npm-shared +``` + +Then make sure `.env` keeps `NPM_SHARED_NETWORK=npm-shared`, or set it to whatever user-defined network you want to share with NPM. + +Now build and start the stack: + ```bash docker compose up -d --build ``` @@ -67,15 +78,15 @@ docker compose logs -f api web compute candles ingest-options ingest-equities 5. Make sure NPM can reach the stack network. -This deployment attaches `web` and `api` to the external Docker network named `bridge`, in addition to the stack-local network. +This deployment attaches `web` and `api` to the external Docker network named by `NPM_SHARED_NETWORK`, in addition to the stack-local network. -If your NPM container is not already attached to `bridge`, connect it once: +If your NPM container is not already attached to that network, connect it once: ```bash -docker network connect bridge +docker network connect npm-shared ``` -If your NPM stack uses a different shared user-defined network, update the `bridge` network block in `deployment/docker/docker-compose.yml` to point at that external network name, then redeploy. The important part is that NPM, `web`, and `api` all share the same external Docker network. +If you want to use a different network name, set `NPM_SHARED_NETWORK` in `.env` and make sure that external Docker network already exists. The important part is that NPM, `web`, and `api` all share the same user-defined Docker network. 6. Create these NPM proxy hosts: @@ -151,7 +162,7 @@ The web app should be built with `NEXT_PUBLIC_API_URL=https://api.` so b The API host needs websocket support enabled because the app uses `/ws/*` endpoints for live streams. -Because `web` and `api` are both attached to `bridge`, NPM can target them directly by container DNS name: +Because `web` and `api` are both attached to the shared user-defined network, NPM can target them directly by container DNS name: - `web` - `api` @@ -207,7 +218,7 @@ Only use `-v` if you intentionally want to wipe ClickHouse, Redis, and JetStream ## Known caveats - The root `.env.example` still contains a `REPLAY_ENABLED` comment, but the current replay service does not read that variable. Use the Compose replay profile instead. -- This stack does not publish `web` or `api` to host ports. NPM must be able to resolve `web` and `api` over the shared `bridge` network. +- This stack does not publish `web` or `api` to host ports. NPM must be able to resolve `web` and `api` over the shared user-defined network from `NPM_SHARED_NETWORK`. - The stack assumes a single-node VPS deployment. If you later split infra or add external managed services, update the three core connection URLs in `.env`. ## Smoke checks diff --git a/deployment/docker/docker-compose.yml b/deployment/docker/docker-compose.yml index db08455..839c218 100644 --- a/deployment/docker/docker-compose.yml +++ b/deployment/docker/docker-compose.yml @@ -31,7 +31,7 @@ services: - "3000" networks: - default - - bridge + - shared depends_on: api: condition: service_healthy @@ -55,7 +55,7 @@ services: - "4000" networks: - default - - bridge + - shared healthcheck: test: [ @@ -127,9 +127,9 @@ services: - nats-data:/data networks: - bridge: + shared: external: true - name: bridge + name: ${NPM_SHARED_NETWORK:-npm-shared} volumes: clickhouse-data: