From 3b3e4fb928441d6c223202fc5d109673b7d2773c Mon Sep 17 00:00:00 2001 From: dlomm <118149483+dlommm@users.noreply.github.com> Date: Sat, 24 Oct 2026 12:45:18 -0400 Subject: [PATCH 1/4] fix(ci): publish images for arm64 as well as amd64 Release images were x86 only, so on an ARM server (Ampere, Graviton, Hetzner CAX, Raspberry Pi) docker compose found no matching image. The release now builds one multi-platform image with buildx and QEMU, and the PR smoke job builds for arm64 too so an ARM breakage fails before merge. --- .github/workflows/ci.yml | 22 +++++++++++++++++----- 1 file changed, 17 insertions(+), 5 deletions(-) diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml index d578aca..0965125 100644 --- a/.github/workflows/ci.yml +++ b/.github/workflows/ci.yml @@ -241,6 +241,13 @@ jobs: - name: Clean up if: always() run: docker rm -f "$SMOKE" >/dev/null 2>&1 || true + # The release publishes an arm64 image too; prove it builds before merge. + - uses: docker/setup-qemu-action@v3 + with: + platforms: arm64 + - uses: docker/setup-buildx-action@v3 + - name: Build for arm64 + run: docker buildx build --platform linux/arm64 --build-arg APP_VERSION=ci-smoke . release: if: github.ref == 'refs/heads/main' && (github.event_name == 'push' || github.event_name == 'workflow_dispatch') @@ -277,18 +284,23 @@ jobs: registry: docker.io username: ${{ secrets.DOCKERHUB_USERNAME }} password: ${{ secrets.DOCKERHUB_TOKEN }} + # One multi-platform image for x86 servers and ARM ones (Ampere, Graviton, + # Hetzner CAX, Raspberry Pi). QEMU emulates arm64 on the x86 runner. + - uses: docker/setup-qemu-action@v3 + with: + platforms: arm64 + - uses: docker/setup-buildx-action@v3 # Always refresh :latest (carries the baked APP_VERSION) in both registries. # --pull so base image security patches (python:3.12-slim) reach production. - name: Build and push :latest run: | - docker build --pull --build-arg APP_VERSION="$VERSION" \ + docker buildx build --pull --push --platform linux/amd64,linux/arm64 \ + --build-arg APP_VERSION="$VERSION" \ --label org.opencontainers.image.source="$GITHUB_SERVER_URL/$GITHUB_REPOSITORY" \ --label org.opencontainers.image.revision="$GITHUB_SHA" \ --label org.opencontainers.image.version="$VERSION" \ --label org.opencontainers.image.licenses=AGPL-3.0-only \ -t "$IMAGE:latest" -t "$HUB_IMAGE:latest" . - docker push "$IMAGE:latest" - docker push "$HUB_IMAGE:latest" - name: Push :vX.Y.Z and publish the Release env: GH_TOKEN: ${{ secrets.GITHUB_TOKEN }} @@ -305,9 +317,9 @@ jobs: fi exit 0 fi + # Copy the exact multi-platform manifest just pushed as :latest. for img in "$IMAGE" "$HUB_IMAGE"; do - docker tag "$IMAGE:latest" "$img:$VERSION" - docker push "$img:$VERSION" + docker buildx imagetools create -t "$img:$VERSION" "$IMAGE:latest" done # Creates the tag at this commit. Tags pushed with GITHUB_TOKEN do not # trigger workflows, and this workflow only runs on branches anyway. From 9b13038d42e128e338f3c2b47bf63870e4faa2df Mon Sep 17 00:00:00 2001 From: dlomm <118149483+dlommm@users.noreply.github.com> Date: Sat, 24 Oct 2026 12:48:33 -0400 Subject: [PATCH 2/4] fix(deploy): compose files that run the published image, plus a VPS stack with HTTPS docker-compose.yml built from source, so on a server without a checkout there was no image to run, and docker-compose.override.yml (auto-applied in a checkout) switched a deploy into dev mode. Now: - docker-compose.yml runs dendlomm/openpoolpro behind your own proxy - docker-compose.vps.yml runs it with Caddy and automatic HTTPS; the app is reachable only through Caddy, whose fixed address is the trusted proxy - docker-compose.dev.yml builds from source with live reload README and the website's install steps follow. --- README.md | 40 ++++++++++++++++--------- deploy/docker-compose.yml | 32 -------------------- docker-compose.dev.yml | 25 ++++++++++++++++ docker-compose.override.yml | 24 --------------- docker-compose.vps.yml | 58 +++++++++++++++++++++++++++++++++++++ docker-compose.yml | 31 +++++++++++++------- site/index.html | 16 +++++----- 7 files changed, 137 insertions(+), 89 deletions(-) delete mode 100644 deploy/docker-compose.yml create mode 100644 docker-compose.dev.yml delete mode 100644 docker-compose.override.yml create mode 100644 docker-compose.vps.yml diff --git a/README.md b/README.md index 458096d..b018d76 100644 --- a/README.md +++ b/README.md @@ -26,20 +26,30 @@ one box (Docker + SQLite) and to be used from an iPhone in the field. ## Run - cp .env.example .env # set SECRET_KEY (openssl rand -hex 32) - docker compose up -d - # (builds from source; to run the published image instead use - # deploy/docker-compose.yml, which pulls dendlomm/openpoolpro:latest) - # Put a TLS reverse proxy in front — the compose file binds the app to - # 127.0.0.1:8000 ON PURPOSE (the app trusts X-Forwarded-* from the proxy), - # so it is NOT reachable from other machines directly. Point the proxy at - # 127.0.0.1:8000 and set FORWARDED_ALLOW_IPS to the proxy's address. - # Open the app: first-time setup asks for the setup code from - # docker compose logs app | grep "Setup code" - # then creates your owner account (your name, username and password). - # Forgot the owner password? Print a one-time reset link: - # docker compose exec app python -m app.manage reset-owner [--clear-2fa] - # on iPhone: Share → Add to Home Screen +**On a VPS (automatic HTTPS).** Point your domain at the server, open ports 80 +and 443, then: + + mkdir openpoolpro && cd openpoolpro + curl -O https://raw.githubusercontent.com/dlommm/OpenPoolPro/main/docker-compose.vps.yml + printf 'SECRET_KEY=%s\nDOMAIN=pools.example.com\n' "$(openssl rand -hex 32)" > .env + docker compose -f docker-compose.vps.yml up -d + docker compose -f docker-compose.vps.yml logs app | grep "Setup code" + +Open `https://`, enter the setup code, and the setup creates your +owner account. Caddy gets and renews the certificate; the app is reachable only +through it. + +**Behind your own reverse proxy.** `docker-compose.yml` runs the same published +image bound to `127.0.0.1:8000`. Put SECRET_KEY in `.env`, run +`docker compose up -d`, point the proxy at `127.0.0.1:8000`, and set +`FORWARDED_ALLOW_IPS` to the address the proxy connects from (by default the +Docker bridge, `172.17.0.1`). + +Images are built for x86 (amd64) and ARM (arm64) servers. Pin a release with +`OPENPOOLPRO_TAG=vX.Y.Z` in `.env`. Forgot the owner password? Print a one-time +reset link with `docker compose exec app python -m app.manage reset-owner +[--clear-2fa]` (add `-f docker-compose.vps.yml` after `compose` on the VPS +stack). On iPhone, Share → Add to Home Screen. All data lives in ./data (SQLite DB, photos, nightly backups). Back up that folder. @@ -67,6 +77,8 @@ for Unraid's Docker Compose Manager — read the SETUP notes at the top of the f python scripts/build_css.py COOKIE_SECURE=0 uvicorn app.main:create_app --factory --reload # the setup code is printed in the log on first start + # or in Docker, building from this checkout with live reload: + # docker compose -f docker-compose.dev.yml up --build ruff check app/ tests/ scripts/ # same gate CI runs pytest -n auto diff --git a/deploy/docker-compose.yml b/deploy/docker-compose.yml deleted file mode 100644 index 9d94764..0000000 --- a/deploy/docker-compose.yml +++ /dev/null @@ -1,32 +0,0 @@ -# OpenPoolPro from the published image (Docker Hub; the same image is at -# ghcr.io/dlommm/openpoolpro). Put SECRET_KEY in a .env file next to this -# file (openssl rand -hex 32), run `docker compose up -d`, then open the app -# and enter the setup code from `docker compose logs app | grep "Setup code"`. -services: - app: - image: dendlomm/openpoolpro:latest - ports: - # Loopback-only. The app trusts X-Forwarded-* from the configured proxy, - # so anything that can reach this port directly can forge the client IP - # the login rate limiter and audit log key on. Put the reverse proxy in - # front; don't publish this on 0.0.0.0. - - "127.0.0.1:8000:8000" - volumes: - - ./data:/data - environment: - SECRET_KEY: ${SECRET_KEY:?set SECRET_KEY in .env} - APP_TZ: ${APP_TZ:-America/New_York} - # Must match the address the reverse proxy connects from (see Dockerfile). - FORWARDED_ALLOW_IPS: ${FORWARDED_ALLOW_IPS:-127.0.0.1} - # Session cookies are marked Secure (HTTPS-only) by default — correct for - # the documented TLS-reverse-proxy setup above. Set COOKIE_SECURE=0 in - # .env ONLY for a deliberately plain-HTTP deployment; logins won't stick - # over HTTP otherwise. - COOKIE_SECURE: ${COOKIE_SECURE:-1} - # Drop everything, then add back only what the entrypoint needs before it - # gosu's down to PUID:PGID (chown the data dir, then setuid/setgid). - cap_drop: [ALL] - cap_add: [CHOWN, DAC_OVERRIDE, FOWNER, SETUID, SETGID] - security_opt: - - no-new-privileges:true - restart: unless-stopped diff --git a/docker-compose.dev.yml b/docker-compose.dev.yml new file mode 100644 index 0000000..6d5444e --- /dev/null +++ b/docker-compose.dev.yml @@ -0,0 +1,25 @@ +# Development: builds the image from this checkout and live-mounts ./app so +# template and CSS changes (rebuild CSS with `python scripts/build_css.py`) +# show on refresh; uvicorn --reload restarts on Python edits. +# +# docker compose -f docker-compose.dev.yml up --build +# +# Servers use docker-compose.yml or docker-compose.vps.yml instead. +services: + app: + build: . + ports: + - "127.0.0.1:8000:8000" + volumes: + - ./data:/data + - ./app:/srv/app + environment: + SECRET_KEY: ${SECRET_KEY:?set SECRET_KEY in .env (openssl rand -hex 32)} + APP_TZ: ${APP_TZ:-America/New_York} + FORWARDED_ALLOW_IPS: ${FORWARDED_ALLOW_IPS:-127.0.0.1} + COOKIE_SECURE: "0" + RUN_SCHEDULER: "0" + APP_VERSION: dev + command: ["uvicorn", "app.main:create_app", "--factory", "--host", "0.0.0.0", + "--port", "8000", "--reload", "--reload-dir", "/srv/app"] + restart: "no" diff --git a/docker-compose.override.yml b/docker-compose.override.yml deleted file mode 100644 index 76c2096..0000000 --- a/docker-compose.override.yml +++ /dev/null @@ -1,24 +0,0 @@ -# Local DEV overrides — auto-merged by `docker compose` in this directory. -# Live-mounts ./app so template + CSS (app/static/app.css, rebuilt via -# `python scripts/build_css.py`) changes show up on refresh without rebuilding -# the image; uvicorn --reload restarts on Python edits. Production deploys use -# docker-compose.unraid.yml instead and are unaffected by this file. -services: - app: - volumes: - - ./data:/data - - ./app:/srv/app - environment: - RUN_SCHEDULER: "0" - APP_VERSION: dev - command: - - uvicorn - - app.main:create_app - - --factory - - --host - - "0.0.0.0" - - --port - - "8000" - - --reload - - --reload-dir - - /srv/app diff --git a/docker-compose.vps.yml b/docker-compose.vps.yml new file mode 100644 index 0000000..167f4a8 --- /dev/null +++ b/docker-compose.vps.yml @@ -0,0 +1,58 @@ +# OpenPoolPro on a VPS with automatic HTTPS (Caddy + Let's Encrypt). +# +# Before you start: +# 1. Point your domain's DNS A record (and AAAA, if you use IPv6) at this +# server, and open ports 80 and 443 in its firewall. +# 2. Create .env next to this file: +# SECRET_KEY= +# DOMAIN=pools.example.com +# APP_TZ=America/New_York +# 3. docker compose -f docker-compose.vps.yml up -d +# 4. docker compose -f docker-compose.vps.yml logs app | grep "Setup code" +# then open https:// and enter the code. +# +# Updating: docker compose -f docker-compose.vps.yml pull && \ +# docker compose -f docker-compose.vps.yml up -d +services: + app: + image: dendlomm/openpoolpro:${OPENPOOLPRO_TAG:-latest} + # Not published to the internet: only Caddy reaches it, on the private + # network below, so nobody can bypass the proxy and forge their address. + expose: ["8000"] + volumes: + - ./data:/data + environment: + SECRET_KEY: ${SECRET_KEY:?set SECRET_KEY in .env (openssl rand -hex 32)} + APP_TZ: ${APP_TZ:-America/New_York} + FORWARDED_ALLOW_IPS: 172.30.80.2 # Caddy's fixed address below + COOKIE_SECURE: "1" + networks: + web: + ipv4_address: 172.30.80.3 + cap_drop: [ALL] + cap_add: [CHOWN, DAC_OVERRIDE, FOWNER, SETUID, SETGID] + security_opt: + - no-new-privileges:true + restart: unless-stopped + + caddy: + image: caddy:2 + command: caddy reverse-proxy --from ${DOMAIN:?set DOMAIN in .env, e.g. pools.example.com} --to app:8000 + ports: + - "80:80" + - "443:443" + - "443:443/udp" + volumes: + - ./caddy/data:/data # certificates; keep this folder + - ./caddy/config:/config + networks: + web: + ipv4_address: 172.30.80.2 + depends_on: [app] + restart: unless-stopped + +networks: + web: + ipam: + config: + - subnet: 172.30.80.0/24 diff --git a/docker-compose.yml b/docker-compose.yml index 3a58c50..9089670 100644 --- a/docker-compose.yml +++ b/docker-compose.yml @@ -1,26 +1,35 @@ +# OpenPoolPro from the published image (Docker Hub; the same image is at +# ghcr.io/dlommm/openpoolpro). For a server with your own reverse proxy. +# On a fresh VPS with nothing else on it, docker-compose.vps.yml adds Caddy +# with automatic HTTPS instead. +# +# echo "SECRET_KEY=$(openssl rand -hex 32)" > .env +# docker compose up -d +# docker compose logs app | grep "Setup code" +# +# Then open the app through your proxy and enter the setup code. services: app: - build: . + image: dendlomm/openpoolpro:${OPENPOOLPRO_TAG:-latest} ports: # Loopback-only. The app trusts X-Forwarded-* from the configured proxy, # so anything that can reach this port directly can forge the client IP - # the login rate limiter and audit log key on. Put the reverse proxy in - # front; don't publish this on 0.0.0.0. + # the login rate limiter and audit log key on. Point the reverse proxy at + # 127.0.0.1:8000; don't publish this on 0.0.0.0. - "127.0.0.1:8000:8000" volumes: - ./data:/data environment: - SECRET_KEY: ${SECRET_KEY:?set SECRET_KEY in .env} + SECRET_KEY: ${SECRET_KEY:?set SECRET_KEY in .env (openssl rand -hex 32)} APP_TZ: ${APP_TZ:-America/New_York} - # Must match the address the reverse proxy connects from (see Dockerfile). - FORWARDED_ALLOW_IPS: ${FORWARDED_ALLOW_IPS:-127.0.0.1} - # Session cookies are marked Secure (HTTPS-only) by default — correct for - # the documented TLS-reverse-proxy setup above. Set COOKIE_SECURE=0 in - # .env ONLY for a deliberately plain-HTTP deployment; logins won't stick - # over HTTP otherwise. + # The address the reverse proxy connects FROM, as the container sees it. + # A proxy on the host usually arrives from the Docker bridge gateway. + FORWARDED_ALLOW_IPS: ${FORWARDED_ALLOW_IPS:-172.17.0.1} + # Session cookies are HTTPS-only by default. Set COOKIE_SECURE=0 in .env + # ONLY for a deliberately plain-HTTP setup, or logins won't stick. COOKIE_SECURE: ${COOKIE_SECURE:-1} # Drop everything, then add back only what the entrypoint needs before it - # gosu's down to PUID:PGID (chown the data dir, then setuid/setgid). + # drops to PUID:PGID (chown the data dir, then setuid/setgid). cap_drop: [ALL] cap_add: [CHOWN, DAC_OVERRIDE, FOWNER, SETUID, SETGID] security_opt: diff --git a/site/index.html b/site/index.html index a87aaed..4222513 100644 --- a/site/index.html +++ b/site/index.html @@ -91,9 +91,9 @@

One stop, start to finish

Up and running this afternoon

Run one command on your server.

-

Any Linux box or small VPS with Docker. The app, the database and the nightly backups live in one folder.

-
@@ -111,10 +111,10 @@

Up and running this afternoon

$ mkdir openpoolpro && cd openpoolpro
-$ curl -O https://raw.githubusercontent.com/dlommm/OpenPoolPro/main/deploy/docker-compose.yml
-$ echo "SECRET_KEY=$(openssl rand -hex 32)" > .env
-$ docker compose up -d
-$ docker compose logs app | grep "Setup code"
+$ curl -O https://raw.githubusercontent.com/dlommm/OpenPoolPro/main/docker-compose.vps.yml
+$ printf 'SECRET_KEY=%s\nDOMAIN=pools.example.com\n' "$(openssl rand -hex 32)" > .env
+$ docker compose -f docker-compose.vps.yml up -d
+$ docker compose -f docker-compose.vps.yml logs app | grep "Setup code"
 No owner account yet. Setup code: 9SZS-GBEK-82NZ
@@ -251,7 +251,7 @@

Common questions

Nothing. OpenPoolPro is free and open source under the AGPL-3.0 licence. You pay only for the server you run it on; a small VPS is plenty for a company with a handful of technicians.

- + From 4dea18e5978b363ed2231d065b1df78449461427 Mon Sep 17 00:00:00 2001 From: dlomm <118149483+dlommm@users.noreply.github.com> Date: Sat, 24 Oct 2026 12:50:47 -0400 Subject: [PATCH 3/4] fix(deploy): a compose file per proxy (Pangolin, Caddy, your own) and a deploy guide - docker-compose.pangolin.yml joins Pangolin's network with no published port; Pangolin routes to openpoolpro:8000. Optional SSO via the existing trusted-header support. - docker-compose.vps.yml becomes docker-compose.caddy.yml, for a bare VPS. - docs/deploy.md: which file to use, Pangolin resource and bypass rules for customer pages, provider firewalls, ARM, updating and owner recovery. --- README.md | 43 +++--- ...ompose.vps.yml => docker-compose.caddy.yml | 13 +- docker-compose.dev.yml | 2 +- docker-compose.pangolin.yml | 44 +++++++ docker-compose.yml | 3 +- docs/deploy.md | 122 ++++++++++++++++++ site/index.html | 14 +- 7 files changed, 203 insertions(+), 38 deletions(-) rename docker-compose.vps.yml => docker-compose.caddy.yml (75%) create mode 100644 docker-compose.pangolin.yml create mode 100644 docs/deploy.md diff --git a/README.md b/README.md index b018d76..a35bbc3 100644 --- a/README.md +++ b/README.md @@ -26,30 +26,25 @@ one box (Docker + SQLite) and to be used from an iPhone in the field. ## Run -**On a VPS (automatic HTTPS).** Point your domain at the server, open ports 80 -and 443, then: - - mkdir openpoolpro && cd openpoolpro - curl -O https://raw.githubusercontent.com/dlommm/OpenPoolPro/main/docker-compose.vps.yml - printf 'SECRET_KEY=%s\nDOMAIN=pools.example.com\n' "$(openssl rand -hex 32)" > .env - docker compose -f docker-compose.vps.yml up -d - docker compose -f docker-compose.vps.yml logs app | grep "Setup code" - -Open `https://`, enter the setup code, and the setup creates your -owner account. Caddy gets and renews the certificate; the app is reachable only -through it. - -**Behind your own reverse proxy.** `docker-compose.yml` runs the same published -image bound to `127.0.0.1:8000`. Put SECRET_KEY in `.env`, run -`docker compose up -d`, point the proxy at `127.0.0.1:8000`, and set -`FORWARDED_ALLOW_IPS` to the address the proxy connects from (by default the -Docker bridge, `172.17.0.1`). - -Images are built for x86 (amd64) and ARM (arm64) servers. Pin a release with -`OPENPOOLPRO_TAG=vX.Y.Z` in `.env`. Forgot the owner password? Print a one-time -reset link with `docker compose exec app python -m app.manage reset-owner -[--clear-2fa]` (add `-f docker-compose.vps.yml` after `compose` on the VPS -stack). On iPhone, Share → Add to Home Screen. +One image (`dendlomm/openpoolpro`, x86 and ARM) on any VPS or home server. Pick +the compose file for the proxy that gives you HTTPS: + +| You have | Use | +| --- | --- | +| Pangolin on the same server | `docker-compose.pangolin.yml` | +| A bare VPS, nothing on ports 80/443 | `docker-compose.caddy.yml` (bundled Caddy + Let's Encrypt) | +| Nginx, NPM, Traefik, Caddy on the host, or a Cloudflare Tunnel | `docker-compose.yml` (app on `127.0.0.1:8000`) | +| Unraid | `docker-compose.unraid.yml` | + + curl -O https://raw.githubusercontent.com/dlommm/OpenPoolPro/main/ + echo "SECRET_KEY=$(openssl rand -hex 32)" > .env + docker compose -f up -d + docker compose -f logs app | grep "Setup code" + +Then open the site, enter the setup code, and first-time setup creates your +owner account. [docs/deploy.md](docs/deploy.md) has the details for each proxy +(Pangolin resource and bypass rules, single sign-on, firewalls, updating and +owner password recovery). All data lives in ./data (SQLite DB, photos, nightly backups). Back up that folder. diff --git a/docker-compose.vps.yml b/docker-compose.caddy.yml similarity index 75% rename from docker-compose.vps.yml rename to docker-compose.caddy.yml index 167f4a8..987a97a 100644 --- a/docker-compose.vps.yml +++ b/docker-compose.caddy.yml @@ -1,4 +1,7 @@ -# OpenPoolPro on a VPS with automatic HTTPS (Caddy + Let's Encrypt). +# OpenPoolPro with its own Caddy proxy and automatic HTTPS (Let's Encrypt), +# for a VPS with nothing else on ports 80 and 443. Already run Pangolin, +# Traefik, Nginx or another proxy? Use docker-compose.pangolin.yml or +# docker-compose.yml instead (see docs/deploy.md). # # Before you start: # 1. Point your domain's DNS A record (and AAAA, if you use IPv6) at this @@ -7,12 +10,12 @@ # SECRET_KEY= # DOMAIN=pools.example.com # APP_TZ=America/New_York -# 3. docker compose -f docker-compose.vps.yml up -d -# 4. docker compose -f docker-compose.vps.yml logs app | grep "Setup code" +# 3. docker compose -f docker-compose.caddy.yml up -d +# 4. docker compose -f docker-compose.caddy.yml logs app | grep "Setup code" # then open https:// and enter the code. # -# Updating: docker compose -f docker-compose.vps.yml pull && \ -# docker compose -f docker-compose.vps.yml up -d +# Updating: docker compose -f docker-compose.caddy.yml pull && \ +# docker compose -f docker-compose.caddy.yml up -d services: app: image: dendlomm/openpoolpro:${OPENPOOLPRO_TAG:-latest} diff --git a/docker-compose.dev.yml b/docker-compose.dev.yml index 6d5444e..d8e3659 100644 --- a/docker-compose.dev.yml +++ b/docker-compose.dev.yml @@ -4,7 +4,7 @@ # # docker compose -f docker-compose.dev.yml up --build # -# Servers use docker-compose.yml or docker-compose.vps.yml instead. +# Servers use docker-compose.yml, .caddy.yml or .pangolin.yml (docs/deploy.md). services: app: build: . diff --git a/docker-compose.pangolin.yml b/docker-compose.pangolin.yml new file mode 100644 index 0000000..146f2be --- /dev/null +++ b/docker-compose.pangolin.yml @@ -0,0 +1,44 @@ +# OpenPoolPro behind Pangolin (https://github.com/fosrl/pangolin) on the same +# server. The app joins Pangolin's Docker network and publishes no port, so +# the only way in is through Pangolin. +# +# 1. echo "SECRET_KEY=$(openssl rand -hex 32)" > .env +# 2. docker compose -f docker-compose.pangolin.yml up -d +# 3. In Pangolin, add a resource for your domain on the local site with +# target http://openpoolpro:8000 +# 4. docker compose -f docker-compose.pangolin.yml logs app | grep "Setup code" +# then open the resource's URL and enter the code. +# +# If Pangolin's own sign-in protects the resource, add bypass rules for the +# customer pages (/portal/*, /sign/*, /static/*, /branding/*) or customers +# can't open their portal and signing links. See docs/deploy.md. +services: + app: + image: dendlomm/openpoolpro:${OPENPOOLPRO_TAG:-latest} + container_name: openpoolpro + volumes: + - ./data:/data + environment: + SECRET_KEY: ${SECRET_KEY:?set SECRET_KEY in .env (openssl rand -hex 32)} + APP_TZ: ${APP_TZ:-America/New_York} + # Trust X-Forwarded-For from Pangolin's network. With no published port, + # only containers on that network can connect at all. Narrow it to the + # network's own subnet if you like: + # docker network inspect pangolin -f '{{(index .IPAM.Config 0).Subnet}}' + FORWARDED_ALLOW_IPS: ${FORWARDED_ALLOW_IPS:-172.16.0.0/12} + COOKIE_SECURE: "1" + # Optional single sign-on through Pangolin: see docs/deploy.md. + PROXY_AUTH_SECRET: ${PROXY_AUTH_SECRET:-} + networks: [pangolin] + cap_drop: [ALL] + cap_add: [CHOWN, DAC_OVERRIDE, FOWNER, SETUID, SETGID] + security_opt: + - no-new-privileges:true + restart: unless-stopped + +networks: + pangolin: + external: true + # The network Pangolin's installer creates. Change it if yours differs: + # docker network ls + name: ${PANGOLIN_NETWORK:-pangolin} diff --git a/docker-compose.yml b/docker-compose.yml index 9089670..bc824be 100644 --- a/docker-compose.yml +++ b/docker-compose.yml @@ -1,6 +1,7 @@ # OpenPoolPro from the published image (Docker Hub; the same image is at # ghcr.io/dlommm/openpoolpro). For a server with your own reverse proxy. -# On a fresh VPS with nothing else on it, docker-compose.vps.yml adds Caddy +# Behind Pangolin use docker-compose.pangolin.yml; on a bare VPS, +# docker-compose.caddy.yml adds Caddy # with automatic HTTPS instead. # # echo "SECRET_KEY=$(openssl rand -hex 32)" > .env diff --git a/docs/deploy.md b/docs/deploy.md new file mode 100644 index 0000000..460d1c3 --- /dev/null +++ b/docs/deploy.md @@ -0,0 +1,122 @@ +# Deploying OpenPoolPro + +OpenPoolPro is one Docker image (`dendlomm/openpoolpro`, also +`ghcr.io/dlommm/openpoolpro`) built for x86 (amd64) and ARM (arm64), so it runs +on any VPS provider: Hostinger, Hetzner (including the ARM CAX plans), +DigitalOcean, Linode, Vultr, OVH, Oracle Cloud's Ampere instances, AWS +Lightsail or a box at home. + +What changes from one setup to the next is the **reverse proxy** in front of +it, which gives you HTTPS. Pick the compose file that matches yours: + +| You have | Use | +| --- | --- | +| Pangolin on the same server | `docker-compose.pangolin.yml` | +| A bare VPS with nothing on ports 80/443 | `docker-compose.caddy.yml` (brings Caddy and a Let's Encrypt certificate) | +| Nginx, Nginx Proxy Manager, Caddy or Traefik on the host, or a Cloudflare Tunnel | `docker-compose.yml` (app on `127.0.0.1:8000`) | +| Unraid | `docker-compose.unraid.yml` | + +Every option starts the same way: + +```bash +mkdir openpoolpro && cd openpoolpro +curl -O https://raw.githubusercontent.com/dlommm/OpenPoolPro/main/ +echo "SECRET_KEY=$(openssl rand -hex 32)" > .env +``` + +After the app starts, read the one-time setup code from its log, open the site +and follow first-time setup: + +```bash +docker compose -f logs app | grep "Setup code" +``` + +All data lives in `./data` next to the compose file. Back that folder up. + +## Pangolin + +Pangolin's installer runs Pangolin, Gerbil and Traefik on a Docker network +called `pangolin`. `docker-compose.pangolin.yml` puts OpenPoolPro on that +network with no published port, so the only way in is through Pangolin. + +1. `docker compose -f docker-compose.pangolin.yml up -d` +2. In the Pangolin dashboard, add an HTTP resource with your subdomain on the + site that runs on this server, and set its target to `openpoolpro`, port + `8000`. +3. Read the setup code (above) and open the resource's URL. + +If your Pangolin network has another name (`docker network ls`), set +`PANGOLIN_NETWORK=` in `.env`. + +**Pangolin sign-in in front of the app.** If you leave Pangolin's +authentication on for this resource, add bypass rules so customers can still +open the pages they get by email, which carry their own single-use links: +`/portal/*`, `/sign/*`, `/static/*`, `/branding/*`, `/manifest.json` and +`/sw.js`. Without them, customers hit a Pangolin login they can't pass. + +**Single sign-on (optional).** OpenPoolPro can trust Pangolin's login instead +of asking for its own: + +1. Put a long random value in `.env`: `PROXY_AUTH_SECRET=$(openssl rand -hex 32)`. +2. In the resource's settings, add a custom header `X-OpenPool-Auth` with that + same value. +3. Optionally pass the signed-in user's name in `X-OpenPool-User` so the app + logs actions against the right staff member; otherwise SSO signs in as the + owner. + +Only turn this on with Pangolin's authentication enabled: anyone who reaches +the app with that header is signed in. The normal password and two-step +sign-in keep working alongside it. + +**OpenPoolPro on a different machine from Pangolin.** Run a Newt site +connector on that machine, run OpenPoolPro there with `docker-compose.yml`, +and point the resource at the address Newt can reach the app on. + +## Caddy (bare VPS) + +1. Point your domain's DNS `A` record (and `AAAA` for IPv6) at the server. +2. Open ports **80** and **443** in the provider's firewall as well as on the + server (`ufw allow 80,443/tcp`). Most providers have a cloud firewall in + their control panel that blocks them until you allow them. +3. Add `DOMAIN=pools.example.com` to `.env`. +4. `docker compose -f docker-compose.caddy.yml up -d` + +Caddy gets and renews the certificate itself and redirects HTTP to HTTPS. Keep +the `./caddy` folder; it holds the certificates. + +## Your own proxy on the host + +`docker-compose.yml` publishes the app on `127.0.0.1:8000` only. Point the +proxy there. Set `FORWARDED_ALLOW_IPS` in `.env` to the address the proxy +connects from as the container sees it. For a proxy on the host that is +usually the Docker bridge gateway, `172.17.0.1` (the default). With a wrong +value, the sign-in rate limiter and audit log see the proxy's address instead +of the visitor's. + +Cloudflare Tunnel works the same way: point the tunnel at +`http://localhost:8000`. + +## Updating + +```bash +docker compose -f pull +docker compose -f up -d +``` + +The app backs up its database before applying any migration. To stay on one +release, set `OPENPOOLPRO_TAG=v2.0.1` (for example) in `.env`. + +## Forgotten owner password + +```bash +docker compose -f exec app python -m app.manage reset-owner +``` + +prints a one-time reset link valid for 30 minutes. Add `--clear-2fa` if the +phone with the authenticator is lost too. + +## Plain HTTP for testing + +Session cookies are HTTPS-only. To try the app over plain `http://` on a test +box, add `COOKIE_SECURE=0` to `.env` and use `docker-compose.yml`. Don't run a +real business that way. diff --git a/site/index.html b/site/index.html index 4222513..fc75e6c 100644 --- a/site/index.html +++ b/site/index.html @@ -91,9 +91,9 @@

One stop, start to finish

Up and running this afternoon

Run one command on your server.

-

Any Linux VPS with Docker, x86 or ARM. Caddy gets your HTTPS certificate; the app, the database and the nightly backups live in one folder.

-
@@ -111,10 +111,10 @@

Up and running this afternoon

$ mkdir openpoolpro && cd openpoolpro
-$ curl -O https://raw.githubusercontent.com/dlommm/OpenPoolPro/main/docker-compose.vps.yml
+$ curl -O https://raw.githubusercontent.com/dlommm/OpenPoolPro/main/docker-compose.caddy.yml
 $ printf 'SECRET_KEY=%s\nDOMAIN=pools.example.com\n' "$(openssl rand -hex 32)" > .env
-$ docker compose -f docker-compose.vps.yml up -d
-$ docker compose -f docker-compose.vps.yml logs app | grep "Setup code"
+$ docker compose -f docker-compose.caddy.yml up -d
+$ docker compose -f docker-compose.caddy.yml logs app | grep "Setup code"
 No owner account yet. Setup code: 9SZS-GBEK-82NZ
@@ -251,7 +251,7 @@

Common questions

Nothing. OpenPoolPro is free and open source under the AGPL-3.0 licence. You pay only for the server you run it on; a small VPS is plenty for a company with a handful of technicians.

- + From ce9c71eedfb979538886f37b32caefe67c395f3d Mon Sep 17 00:00:00 2001 From: dlomm <118149483+dlommm@users.noreply.github.com> Date: Sat, 24 Oct 2026 13:23:23 -0400 Subject: [PATCH 4/4] fix(deploy): compose files that paste cleanly into control panels Absolute data path (HOST_DIR, default /opt/openpoolpro) instead of ./data, which depends on where a panel keeps the project; the image and Pangolin network are panel-form variables; log rotation; and the deploy guide says that a missing external network stops the project from deploying. --- README.md | 3 ++- docker-compose.caddy.yml | 18 ++++++++++---- docker-compose.pangolin.yml | 47 +++++++++++++++++++++++-------------- docker-compose.yml | 13 ++++++++-- docs/deploy.md | 17 ++++++++++---- 5 files changed, 68 insertions(+), 30 deletions(-) diff --git a/README.md b/README.md index a35bbc3..0275cd4 100644 --- a/README.md +++ b/README.md @@ -46,7 +46,8 @@ owner account. [docs/deploy.md](docs/deploy.md) has the details for each proxy (Pangolin resource and bypass rules, single sign-on, firewalls, updating and owner password recovery). -All data lives in ./data (SQLite DB, photos, nightly backups). Back up that +All data lives in /opt/openpoolpro/data (SQLite DB, photos, nightly backups; set +HOST_DIR to move it). Back up that folder. **Upgrading from a version that used `APP_PASSWORD`:** your `owner` account keeps diff --git a/docker-compose.caddy.yml b/docker-compose.caddy.yml index 987a97a..c4d203c 100644 --- a/docker-compose.caddy.yml +++ b/docker-compose.caddy.yml @@ -18,12 +18,12 @@ # docker compose -f docker-compose.caddy.yml up -d services: app: - image: dendlomm/openpoolpro:${OPENPOOLPRO_TAG:-latest} + image: ${OPENPOOLPRO_IMAGE:-dendlomm/openpoolpro:latest} # Not published to the internet: only Caddy reaches it, on the private # network below, so nobody can bypass the proxy and forge their address. expose: ["8000"] volumes: - - ./data:/data + - ${HOST_DIR:-/opt/openpoolpro}/data:/data environment: SECRET_KEY: ${SECRET_KEY:?set SECRET_KEY in .env (openssl rand -hex 32)} APP_TZ: ${APP_TZ:-America/New_York} @@ -37,6 +37,11 @@ services: security_opt: - no-new-privileges:true restart: unless-stopped + logging: + driver: json-file + options: + max-size: "10m" + max-file: "5" caddy: image: caddy:2 @@ -46,13 +51,18 @@ services: - "443:443" - "443:443/udp" volumes: - - ./caddy/data:/data # certificates; keep this folder - - ./caddy/config:/config + - ${HOST_DIR:-/opt/openpoolpro}/caddy/data:/data # certificates; keep this folder + - ${HOST_DIR:-/opt/openpoolpro}/caddy/config:/config networks: web: ipv4_address: 172.30.80.2 depends_on: [app] restart: unless-stopped + logging: + driver: json-file + options: + max-size: "10m" + max-file: "5" networks: web: diff --git a/docker-compose.pangolin.yml b/docker-compose.pangolin.yml index 146f2be..8daede6 100644 --- a/docker-compose.pangolin.yml +++ b/docker-compose.pangolin.yml @@ -2,43 +2,54 @@ # server. The app joins Pangolin's Docker network and publishes no port, so # the only way in is through Pangolin. # -# 1. echo "SECRET_KEY=$(openssl rand -hex 32)" > .env -# 2. docker compose -f docker-compose.pangolin.yml up -d -# 3. In Pangolin, add a resource for your domain on the local site with -# target http://openpoolpro:8000 -# 4. docker compose -f docker-compose.pangolin.yml logs app | grep "Setup code" -# then open the resource's URL and enter the code. +# Works pasted into a control panel (Hostinger's Docker Manager and similar: +# set the variables in its form) or from a shell (put them in a .env file +# beside this one). Variables marked :? are required. +# +# SECRET_KEY required; any long random string (openssl rand -hex 32). +# Keep it: changing it signs everyone out. +# PANGOLIN_NETWORK Pangolin's Docker network; see `docker network ls`. +# Usually "pangolin"; installed from a panel template it +# may be "_default". +# HOST_DIR where data lives on the server (default /opt/openpoolpro) +# APP_TZ your time zone (default America/New_York) +# +# Then in Pangolin add an HTTP resource for your subdomain on this server's +# site with target openpoolpro : 8000 , open it, and enter the setup code +# from the logs: docker compose logs app | grep "Setup code" # # If Pangolin's own sign-in protects the resource, add bypass rules for the -# customer pages (/portal/*, /sign/*, /static/*, /branding/*) or customers -# can't open their portal and signing links. See docs/deploy.md. +# customer pages (/portal/*, /sign/*, /static/*, /branding/*, /manifest.json, +# /sw.js) or customers can't open their links. See docs/deploy.md. services: app: - image: dendlomm/openpoolpro:${OPENPOOLPRO_TAG:-latest} + image: ${OPENPOOLPRO_IMAGE:-dendlomm/openpoolpro:latest} container_name: openpoolpro - volumes: - - ./data:/data + restart: unless-stopped environment: - SECRET_KEY: ${SECRET_KEY:?set SECRET_KEY in .env (openssl rand -hex 32)} + SECRET_KEY: ${SECRET_KEY:?set SECRET_KEY to a long random string (openssl rand -hex 32)} APP_TZ: ${APP_TZ:-America/New_York} # Trust X-Forwarded-For from Pangolin's network. With no published port, - # only containers on that network can connect at all. Narrow it to the - # network's own subnet if you like: - # docker network inspect pangolin -f '{{(index .IPAM.Config 0).Subnet}}' + # only containers on that network can connect at all. FORWARDED_ALLOW_IPS: ${FORWARDED_ALLOW_IPS:-172.16.0.0/12} COOKIE_SECURE: "1" # Optional single sign-on through Pangolin: see docs/deploy.md. PROXY_AUTH_SECRET: ${PROXY_AUTH_SECRET:-} + volumes: + # Database, photos, PDFs and nightly backups. Back this folder up. + - ${HOST_DIR:-/opt/openpoolpro}/data:/data networks: [pangolin] cap_drop: [ALL] cap_add: [CHOWN, DAC_OVERRIDE, FOWNER, SETUID, SETGID] security_opt: - no-new-privileges:true - restart: unless-stopped + logging: + driver: json-file + options: + max-size: "10m" + max-file: "5" networks: pangolin: external: true - # The network Pangolin's installer creates. Change it if yours differs: - # docker network ls name: ${PANGOLIN_NETWORK:-pangolin} diff --git a/docker-compose.yml b/docker-compose.yml index bc824be..ddc10dc 100644 --- a/docker-compose.yml +++ b/docker-compose.yml @@ -9,9 +9,13 @@ # docker compose logs app | grep "Setup code" # # Then open the app through your proxy and enter the setup code. +# +# Pasting into a control panel (Hostinger's Docker Manager and similar)? Set +# SECRET_KEY in its variables form; data goes to HOST_DIR (default +# /opt/openpoolpro). services: app: - image: dendlomm/openpoolpro:${OPENPOOLPRO_TAG:-latest} + image: ${OPENPOOLPRO_IMAGE:-dendlomm/openpoolpro:latest} ports: # Loopback-only. The app trusts X-Forwarded-* from the configured proxy, # so anything that can reach this port directly can forge the client IP @@ -19,7 +23,7 @@ services: # 127.0.0.1:8000; don't publish this on 0.0.0.0. - "127.0.0.1:8000:8000" volumes: - - ./data:/data + - ${HOST_DIR:-/opt/openpoolpro}/data:/data environment: SECRET_KEY: ${SECRET_KEY:?set SECRET_KEY in .env (openssl rand -hex 32)} APP_TZ: ${APP_TZ:-America/New_York} @@ -36,3 +40,8 @@ services: security_opt: - no-new-privileges:true restart: unless-stopped + logging: + driver: json-file + options: + max-size: "10m" + max-file: "5" diff --git a/docs/deploy.md b/docs/deploy.md index 460d1c3..e23b57a 100644 --- a/docs/deploy.md +++ b/docs/deploy.md @@ -31,7 +31,12 @@ and follow first-time setup: docker compose -f logs app | grep "Setup code" ``` -All data lives in `./data` next to the compose file. Back that folder up. +All data lives in `/opt/openpoolpro/data` (set `HOST_DIR` to move it). Back +that folder up. + +**Control panels.** Every file also works pasted into a panel such as +Hostinger's Docker Manager: set `SECRET_KEY` (and the other variables you need) +in the panel's variables form instead of a `.env` file. ## Pangolin @@ -45,8 +50,10 @@ network with no published port, so the only way in is through Pangolin. `8000`. 3. Read the setup code (above) and open the resource's URL. -If your Pangolin network has another name (`docker network ls`), set -`PANGOLIN_NETWORK=` in `.env`. +The network must already exist, or the project won't deploy (a panel may +report it as "project not found"). Check its name with `docker network ls`; +if it isn't `pangolin` (for example `pangolin_default` when Pangolin was +installed from a panel template), set `PANGOLIN_NETWORK=`. **Pangolin sign-in in front of the app.** If you leave Pangolin's authentication on for this resource, add bypass rules so customers can still @@ -82,7 +89,7 @@ and point the resource at the address Newt can reach the app on. 4. `docker compose -f docker-compose.caddy.yml up -d` Caddy gets and renews the certificate itself and redirects HTTP to HTTPS. Keep -the `./caddy` folder; it holds the certificates. +the `caddy` folder under `HOST_DIR`; it holds the certificates. ## Your own proxy on the host @@ -104,7 +111,7 @@ docker compose -f up -d ``` The app backs up its database before applying any migration. To stay on one -release, set `OPENPOOLPRO_TAG=v2.0.1` (for example) in `.env`. +release, set `OPENPOOLPRO_IMAGE=dendlomm/openpoolpro:v2.0.1` (for example). ## Forgotten owner password