Skip to content
Open
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
22 changes: 17 additions & 5 deletions .github/workflows/ci.yml
Original file line number Diff line number Diff line change
Expand Up @@ -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')
Expand Down Expand Up @@ -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 }}
Expand All @@ -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.
Expand Down
40 changes: 24 additions & 16 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -26,22 +26,28 @@ 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

All data lives in ./data (SQLite DB, photos, nightly backups). Back up that
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/<the file>
echo "SECRET_KEY=$(openssl rand -hex 32)" > .env
docker compose -f <the file> up -d
docker compose -f <the file> 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 /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
Expand All @@ -67,6 +73,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

Expand Down
32 changes: 0 additions & 32 deletions deploy/docker-compose.yml

This file was deleted.

71 changes: 71 additions & 0 deletions docker-compose.caddy.yml
Original file line number Diff line number Diff line change
@@ -0,0 +1,71 @@
# 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
# server, and open ports 80 and 443 in its firewall.
# 2. Create .env next to this file:
# SECRET_KEY=<output of: openssl rand -hex 32>
# DOMAIN=pools.example.com
# APP_TZ=America/New_York
# 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://<your domain> and enter the code.
#
# Updating: docker compose -f docker-compose.caddy.yml pull && \
# docker compose -f docker-compose.caddy.yml up -d
services:
app:
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:
- ${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}
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
logging:
driver: json-file
options:
max-size: "10m"
max-file: "5"

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:
- ${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:
ipam:
config:
- subnet: 172.30.80.0/24
25 changes: 25 additions & 0 deletions docker-compose.dev.yml
Original file line number Diff line number Diff line change
@@ -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, .caddy.yml or .pangolin.yml (docs/deploy.md).
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"
24 changes: 0 additions & 24 deletions docker-compose.override.yml

This file was deleted.

55 changes: 55 additions & 0 deletions docker-compose.pangolin.yml
Original file line number Diff line number Diff line change
@@ -0,0 +1,55 @@
# 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.
#
# 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 "<project>_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/*, /manifest.json,
# /sw.js) or customers can't open their links. See docs/deploy.md.
services:
app:
image: ${OPENPOOLPRO_IMAGE:-dendlomm/openpoolpro:latest}
container_name: openpoolpro
restart: unless-stopped
environment:
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.
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
logging:
driver: json-file
options:
max-size: "10m"
max-file: "5"

networks:
pangolin:
external: true
name: ${PANGOLIN_NETWORK:-pangolin}
43 changes: 31 additions & 12 deletions docker-compose.yml
Original file line number Diff line number Diff line change
@@ -1,28 +1,47 @@
# OpenPoolPro from the published image (Docker Hub; the same image is at
# ghcr.io/dlommm/openpoolpro). For a server with your own reverse proxy.
# 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
# docker compose up -d
# 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:
build: .
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
# 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
- ${HOST_DIR:-/opt/openpoolpro}/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:
- no-new-privileges:true
restart: unless-stopped
logging:
driver: json-file
options:
max-size: "10m"
max-file: "5"
Loading
Loading