Skip to content
Merged
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
36 changes: 28 additions & 8 deletions .github/workflows/ci.yml
Original file line number Diff line number Diff line change
Expand Up @@ -2,10 +2,11 @@
#
# Pull requests and pushes to main run the checks. On a push to main, once every
# gating check is green:
# release — always (re)build & push the image to GHCR as `:latest`; when
# release — always (re)build & push the image to GHCR and Docker Hub as `:latest`; when
# conventional commits since the last tag warrant a version bump, also
# push `:vX.Y.Z` and create the git tag + GitHub Release.
# Auth is the built-in GITHUB_TOKEN — no extra secret required. See docs/ci-cd.md.
# GHCR auth is the built-in GITHUB_TOKEN; Docker Hub uses the DOCKERHUB_USERNAME /
# DOCKERHUB_TOKEN repo secrets. See docs/ci-cd.md.

name: CI

Expand Down Expand Up @@ -223,33 +224,52 @@ jobs:
bash scripts/next-version.sh >> "$GITHUB_ENV"
bash scripts/next-version.sh
echo "IMAGE=ghcr.io/${GITHUB_REPOSITORY,,}" >> "$GITHUB_ENV"
echo "HUB_IMAGE=docker.io/dendlomm/openpoolpro" >> "$GITHUB_ENV"
- uses: docker/login-action@v3
with:
registry: ghcr.io
username: ${{ github.actor }}
password: ${{ secrets.GITHUB_TOKEN }}
# Always refresh :latest (carries the baked APP_VERSION). --pull so base
# image security patches (python:3.12-slim) reach production.
# Docker Hub mirror. DOCKERHUB_TOKEN is a Docker Hub access token with
# Read & Write scope on dendlomm/openpoolpro.
- uses: docker/login-action@v3
with:
registry: docker.io
username: ${{ secrets.DOCKERHUB_USERNAME }}
password: ${{ secrets.DOCKERHUB_TOKEN }}
# 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" \
--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 "$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 }}
run: |
if [ "$BUMP" = "none" ]; then
echo "No feat/fix/breaking commits since last tag — pushed :latest only, no new release."
# Versioned tags are immutable, so never rebuild one. If Docker Hub
# is missing the current release (it was cut before the mirror
# existed), copy GHCR's exact image across instead.
if ! docker manifest inspect "$HUB_IMAGE:$VERSION" >/dev/null 2>&1 \
&& docker manifest inspect "$IMAGE:$VERSION" >/dev/null 2>&1; then
docker buildx imagetools create -t "$HUB_IMAGE:$VERSION" "$IMAGE:$VERSION"
echo "Mirrored $IMAGE:$VERSION to Docker Hub."
fi
exit 0
fi
docker tag "$IMAGE:latest" "$IMAGE:$VERSION"
docker push "$IMAGE:$VERSION"
for img in "$IMAGE" "$HUB_IMAGE"; do
docker tag "$IMAGE:latest" "$img:$VERSION"
docker push "$img:$VERSION"
done
# Creates the tag at this commit. Tags pushed with GITHUB_TOKEN do not
# trigger workflows, and this workflow only runs on branches anyway.
gh release create "$VERSION" --target "$GITHUB_SHA" --title "$VERSION" --generate-notes \
--notes "Docker image \`$IMAGE:$VERSION\` (also \`:latest\`). Built from ${GITHUB_SHA::7}."
--notes "Docker image \`$IMAGE:$VERSION\` or \`$HUB_IMAGE:$VERSION\` (both also \`:latest\`). Built from ${GITHUB_SHA::7}."
5 changes: 3 additions & 2 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -40,8 +40,9 @@ folder.

### Deploy the published image (Unraid)

CI publishes `ghcr.io/dlommm/openpoolpro:latest` on every merge to `main`, plus an
immutable `:vX.Y.Z` per release. `docker-compose.unraid.yml` is a ready-made stack
CI publishes `:latest` on every merge to `main`, plus an immutable `:vX.Y.Z` per
release, to both `ghcr.io/dlommm/openpoolpro` and Docker Hub
(`dendlomm/openpoolpro`). `docker-compose.unraid.yml` is a ready-made stack
for Unraid's Docker Compose Manager — read the SETUP notes at the top of the file
(cache-only appdata share, required `APP_PASSWORD`/`SECRET_KEY`), then:

Expand Down
4 changes: 3 additions & 1 deletion docker-compose.unraid.yml
Original file line number Diff line number Diff line change
Expand Up @@ -14,7 +14,9 @@
# 4. Start the stack. Open the WebUI from the Unraid Docker tab.
#
# Image is pulled from GitHub Container Registry (ghcr.io), published by CI on
# every merge to main. If the package is private, log in on the Unraid terminal
# every merge to main. The same image is on Docker Hub — swap the image line
# below for `dendlomm/openpoolpro:latest` to pull from there instead. Both are
# public; if you make the GHCR package private, log in on the Unraid terminal
# first with a classic PAT that has the read:packages scope:
# docker login ghcr.io -u <github-user> -p <PAT>
# (The Compose Manager pulls with the host Docker's stored credentials.)
Expand Down
34 changes: 23 additions & 11 deletions docs/ci-cd.md
Original file line number Diff line number Diff line change
Expand Up @@ -35,10 +35,14 @@ green, the **release** job runs:

- Computes the next version from **conventional commits** since the last tag
(`scripts/next-version.sh`).
- **Always** rebuilds and pushes `ghcr.io/dlommm/openpoolpro:latest` (the image
bakes the version in via `--build-arg APP_VERSION`).
- **On a version bump only**: also pushes `:vX.Y.Z` and publishes a GitHub
**Release**, which creates the git tag `vX.Y.Z` at that commit.
- **Always** rebuilds and pushes `:latest` to both registries (the image bakes
the version in via `--build-arg APP_VERSION`):
- `ghcr.io/dlommm/openpoolpro`
- `docker.io/dendlomm/openpoolpro` (Docker Hub)
- **On a version bump only**: also pushes `:vX.Y.Z` to both and publishes a
GitHub **Release**, which creates the git tag `vX.Y.Z` at that commit.
- **No bump**: if Docker Hub is missing the current `:vX.Y.Z`, the exact GHCR
image is copied across (never rebuilt), so the two registries stay in step.

Releases are serialized (`concurrency: release`), so two quick merges can't race
to the same version. Never create version tags by hand.
Expand Down Expand Up @@ -73,6 +77,8 @@ So: keep using `feat:` / `fix:` / `feat!:` commit prefixes and versions bump the
- `:latest` — always the newest build of `main`.
- `:vX.Y.Z` — immutable, one per release, matches the git tag and the GitHub Release.

Both tags are identical in GHCR and Docker Hub; pull from whichever you prefer.

Deploy target is **Unraid (amd64)**. GitHub-hosted runners are amd64, so CI builds natively.
(Building on an Apple-Silicon Mac needs `--platform linux/amd64`.)

Expand All @@ -84,11 +90,16 @@ the **Settings** page ("OpenPoolPro vX.Y.Z"), theme-agnostic. Local/dev shows `d

## One-time setup

**No secret is required.** The release job authenticates to GHCR and creates the
Release with the built-in `GITHUB_TOKEN` (the workflow requests `contents: write`
and `packages: write` for that job only).
The release job authenticates to GHCR and creates the Release with the built-in
`GITHUB_TOKEN` (the workflow requests `contents: write` and `packages: write` for
that job only). Docker Hub needs two repository secrets
(**Settings → Secrets and variables → Actions**):

- `DOCKERHUB_USERNAME` — the Docker Hub account that owns `dendlomm/openpoolpro`.
- `DOCKERHUB_TOKEN` — a Docker Hub personal access token with **Read & Write**
scope (Docker Hub → Account settings → Personal access tokens).

After the first release publishes the package:
For GHCR, after the first release publishes the package:

1. Open **GitHub → your profile → Packages → openpoolpro → Package settings**.
2. Under *Manage Actions access*, confirm the `OpenPoolPro` repository has
Expand All @@ -98,8 +109,8 @@ After the first release publishes the package:
credentials, or keep it private and `docker login ghcr.io` on the Unraid host
with a classic PAT that has `read:packages`.

Recommended branch protection on `main`: require pull requests, and require the
`hygiene`, `lint`, `test`, `browser`, and `build-smoke` checks to pass.
Branch protection on `main` requires a pull request and the `hygiene`, `lint`,
`test`, `browser`, and `build-smoke` checks; admins can still bypass in an emergency.

## Manual release fallback

Expand All @@ -121,4 +132,5 @@ docker compose -f docker-compose.unraid.yml pull
docker compose -f docker-compose.unraid.yml up -d
```
Data persists via the `/data` volume. Pin a specific version by setting the image to
`ghcr.io/dlommm/openpoolpro:vX.Y.Z` instead of `:latest`.
`ghcr.io/dlommm/openpoolpro:vX.Y.Z` instead of `:latest`; to pull from Docker Hub
instead, use `dendlomm/openpoolpro:latest` (or `:vX.Y.Z`).
Loading