From ff154b63995df4930607d336a4eeae65645677fe Mon Sep 17 00:00:00 2001 From: Louwrens van Dellen Date: Thu, 24 Sep 2026 10:02:45 +0200 Subject: [PATCH 1/5] ci: docker push nightly to ghcr.io Hereby, we provide docker images tagged with: - "nightly" : single moving tag that follows merges in develop - `git-describe` : fixed tags, one for every merge since PR#27 - "latest" : single moving tag that follows latest tagged commit (main) --- .github/workflows/ci.yml | 12 ++++++++++-- 1 file changed, 10 insertions(+), 2 deletions(-) diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml index a273700..e41a85b 100644 --- a/.github/workflows/ci.yml +++ b/.github/workflows/ci.yml @@ -151,8 +151,16 @@ jobs: ghcr.io/${{ steps.repo_owner.outputs.value }}/simdb-dashboard:${{ needs.build.outputs.version }} docker push ghcr.io/${{ steps.repo_owner.outputs.value }}/simdb-dashboard:${{ needs.build.outputs.version }} - # These steps run on tagged commits only — `:latest` tag and GitHub Release. - - name: Tag and push latest + - name: Tag and push service image with "nightly" + if: ${{ github.ref_type == 'branch' }} + run: | + docker tag \ + simdb-dashboard:service \ + ghcr.io/${{ steps.repo_owner.outputs.value }}/simdb-dashboard:nightly + docker push ghcr.io/${{ steps.repo_owner.outputs.value }}/simdb-dashboard:nightly + + # These steps run on tagged commits only + - name: Tag and push service image with "latest" if: ${{ github.ref_type == 'tag' }} run: | docker tag \ From 971957e5a32fd5e9b1e772d35f1e9323db643d72 Mon Sep 17 00:00:00 2001 From: Louwrens van Dellen Date: Thu, 24 Sep 2026 16:05:17 +0200 Subject: [PATCH 2/5] ci: rename to "develop" image-tag --- .github/workflows/ci.yml | 10 ++++++---- 1 file changed, 6 insertions(+), 4 deletions(-) diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml index e41a85b..e1a8610 100644 --- a/.github/workflows/ci.yml +++ b/.github/workflows/ci.yml @@ -151,15 +151,17 @@ jobs: ghcr.io/${{ steps.repo_owner.outputs.value }}/simdb-dashboard:${{ needs.build.outputs.version }} docker push ghcr.io/${{ steps.repo_owner.outputs.value }}/simdb-dashboard:${{ needs.build.outputs.version }} - - name: Tag and push service image with "nightly" + # Run on branch pushes only, so that older tag pushes won't overwrite newer develop images + - name: Tag and push service image with "develop" if: ${{ github.ref_type == 'branch' }} + # Note that branch pushes other than to "develop" are already filtered out by workflow trigger rules above run: | docker tag \ simdb-dashboard:service \ - ghcr.io/${{ steps.repo_owner.outputs.value }}/simdb-dashboard:nightly - docker push ghcr.io/${{ steps.repo_owner.outputs.value }}/simdb-dashboard:nightly + ghcr.io/${{ steps.repo_owner.outputs.value }}/simdb-dashboard:develop + docker push ghcr.io/${{ steps.repo_owner.outputs.value }}/simdb-dashboard:develop - # These steps run on tagged commits only + # These steps run on tag pushes only - name: Tag and push service image with "latest" if: ${{ github.ref_type == 'tag' }} run: | From 31cfedff938b39ebed6ead7984f10aa6abfb23ec Mon Sep 17 00:00:00 2001 From: Louwrens van Dellen Date: Thu, 24 Sep 2026 16:13:11 +0200 Subject: [PATCH 3/5] ci: add concurrency limit to avoid hypothetically moving the develop image tag to older merge --- .github/workflows/ci.yml | 7 +++++++ 1 file changed, 7 insertions(+) diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml index e1a8610..9daeb74 100644 --- a/.github/workflows/ci.yml +++ b/.github/workflows/ci.yml @@ -12,6 +12,13 @@ on: pull_request: branches: [ "develop" ] +# Serialize runs per ref, so that two merges in quick succession can't race to +# move the "develop" image tag backward. Superseded runs are not cancelled, so +# every merged commit still gets a versioned image. +concurrency: + group: ${{ github.workflow }}-${{ github.ref }} + cancel-in-progress: false + jobs: build: name: Build, verify, and package From 69d7e18fa7a2a98e8d030c4fb7e43b5ba4af2673 Mon Sep 17 00:00:00 2001 From: Louwrens van Dellen Date: Thu, 24 Sep 2026 17:11:52 +0200 Subject: [PATCH 4/5] docs: describe docker image tags --- .github/workflows/ci.yml | 1 + docker-compose.systemd.yml | 8 +++++++- docs/development.md | 7 +++++++ docs/installation.md | 23 ++++++++++++++++++++++- 4 files changed, 37 insertions(+), 2 deletions(-) diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml index 9daeb74..4e1ff75 100644 --- a/.github/workflows/ci.yml +++ b/.github/workflows/ci.yml @@ -151,6 +151,7 @@ jobs: username: ${{ steps.repo_owner.outputs.value }} password: ${{ secrets.GITHUB_TOKEN }} + # Run on branch pushes (develop only) and _any_ tag pushes. - name: Tag and push service image with version tag run: | docker tag \ diff --git a/docker-compose.systemd.yml b/docker-compose.systemd.yml index 291adf9..c550ad0 100644 --- a/docker-compose.systemd.yml +++ b/docker-compose.systemd.yml @@ -3,7 +3,13 @@ # Uses the GHCR-published image instead of a local build. # # Set SIMDB_DASHBOARD_TAG in the environment file to pin a specific -# version. The default is the latest tag at the time of writing. +# version. The default is the latest tag. +# +# Published tags (ghcr.io/iterorganization/simdb-dashboard): +# immutable per-commit build, pin for reproducibility (e.g. 0.9.0) +# latest most recently pushed tag (default; moves after any tag push) +# develop tip of develop, for (pre-production) testing only +# See docs/installation.md#published-image-tags-ghcr. # # Enable this override by including it in COMPOSE_FILE, # after the original, e.g. diff --git a/docs/development.md b/docs/development.md index 205b928..0074270 100644 --- a/docs/development.md +++ b/docs/development.md @@ -48,3 +48,10 @@ make type-check ``` At the moment, the project does not include test files, so `make test` will exit with no tests found. + +## Releases and image tags + +Pushing a tag makes CI publish a versioned image and a GitHub Release, and moves +`latest`; pushes to `develop` move `develop`. The version comes from +`git describe --tags`, so tag releases as plain versions (`0.9.0`) and don't leave +stray tags around. See [Published image tags](installation.md#published-image-tags-ghcr). diff --git a/docs/installation.md b/docs/installation.md index f05898d..85c63db 100644 --- a/docs/installation.md +++ b/docs/installation.md @@ -77,7 +77,7 @@ sudo make systemd-start - `COMPOSE_FILE`: default systemd stack is `docker-compose.yml:docker-compose.systemd.yml`. - `SIMDB_DASHBOARD_IMAGE`: optional image repository override (default `ghcr.io/iterorganization/simdb-dashboard`). -- `SIMDB_DASHBOARD_TAG`: optional image tag (default `latest` in `docker-compose.systemd.yml`). +- `SIMDB_DASHBOARD_TAG`: optional image tag (default `latest` in `docker-compose.systemd.yml`; see [Published image tags](#published-image-tags-ghcr)). - `SYSTEMD_CONTAINER_NAME`: optional docker container name override (see `docker-compose.systemd.yml`). - `DASHBOARD_PORT`: host HTTP port (default `80`). - `DASHBOARD_HTTPS_PORT`: host HTTPS port (default `443`). @@ -88,6 +88,27 @@ sudo make systemd-start See `scripts/simdb-dashboard.env.example` and `scripts/simdb-dashboard.service` for the same defaults and where they are consumed. +## Published image tags + +CI publishes `ghcr.io/iterorganization/simdb-dashboard` docker images on every +PR merge to `develop` and tagged commits (releases): + +| Tag | Pushed on | Mutable | +| --- | --- | --- | +| `` | `develop` and tag pushes | no | +| `develop` | `develop` pushes | yes | +| `latest` | tag pushes | yes | + +`` is `git describe --tags --always` at the pushed commit (e.g. `0.9.0` on a +tag, `0.9.0-12-gabc1234` otherwise). The versioned image is therefore treated as +immutable and never reused across events. + +Deploy `latest` (the default) or pin a version for reproducibility — +`SIMDB_DASHBOARD_TAG=0.9.0`. `latest` only exists once a tag has been pushed, and +tracks whichever tag was pushed last: it equals the newest release only if you +always tag in increasing version order, but nothing enforces that. `develop` is +for testing, not production hosts. + ## Local container building and installation workflow (Docker image + Compose) For building and running docker containers directly (without need for systemd or root), also for development or tweaking. From 206e4cc57f2c6293a5db69fc3d01cb1618b52ac7 Mon Sep 17 00:00:00 2001 From: Louwrens van Dellen Date: Thu, 1 Oct 2026 12:31:39 +0200 Subject: [PATCH 5/5] ci: simplify triggered actions, reduce artifacts - remove tarball of docker image - merge jobs, remove artefact roundtrip between jobs - remove pull_request triggers --- .github/workflows/ci.yml | 79 +++++++++++++--------------------------- docs/installation.md | 13 +++---- 2 files changed, 31 insertions(+), 61 deletions(-) diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml index 4e1ff75..8ef3c7c 100644 --- a/.github/workflows/ci.yml +++ b/.github/workflows/ci.yml @@ -1,13 +1,18 @@ name: CI/CD Pipeline +# Triggers and action summary: +# pull-request -> build and verify. +# push develop -> build, verify, and push image tagged : and :develop. +# push main -> build, verify, and push image tagged :latest. +# push tag -> build, verify, and push image tagged :. + env: CACHE_FROM: type=gha,scope=simdb-dashboard CACHE_TO: type=gha,mode=max,scope=simdb-dashboard on: - # Triggers on pushes to develop, on pushed tags, and on pull requests targeting develop. push: - branches: [ "develop" ] + branches: [ "develop", "main" ] tags: [ "*" ] pull_request: branches: [ "develop" ] @@ -21,12 +26,11 @@ concurrency: jobs: build: - name: Build, verify, and package + name: Build and verify runs-on: ubuntu-latest - outputs: - version: ${{ steps.version.outputs.value }} permissions: - contents: read + contents: write + packages: write steps: - name: Checkout code uses: actions/checkout@v7 @@ -105,87 +109,56 @@ jobs: path: ${{ runner.temp }}/dist/ retention-days: 7 - - name: Export service image tar - run: docker save -o "${{ runner.temp }}/simdb-dashboard-service.tar" simdb-dashboard:service - - - name: Upload service image artifact - uses: actions/upload-artifact@v7 - with: - name: simdb-dashboard-service - path: ${{ runner.temp }}/simdb-dashboard-service.tar - retention-days: 7 - - publish: - name: Publish service image - # Runs only for push events (branch/tag pushes), and is skipped for pull_request events. - if: ${{ github.event_name == 'push' }} - runs-on: ubuntu-latest - needs: build - permissions: - contents: write - packages: write - steps: + # Everything below publishes; it is skipped entirely for pull requests. - name: Lowercase repo-owner + if: ${{ github.event_name == 'push' }} id: repo_owner run: echo "value=${GITHUB_REPOSITORY_OWNER,,}" >> "$GITHUB_OUTPUT" - - name: Download service image artifact - uses: actions/download-artifact@v8 - with: - name: simdb-dashboard-service - path: ${{ runner.temp }} - - - name: Download dist artifact - uses: actions/download-artifact@v8 - with: - name: simdb-dashboard-dist - path: ${{ runner.temp }}/dist - - - name: Load service image - run: docker load -i "${{ runner.temp }}/simdb-dashboard-service.tar" - - name: Login to GitHub Container Registry + if: ${{ github.event_name == 'push' }} uses: docker/login-action@v4 with: registry: ghcr.io username: ${{ steps.repo_owner.outputs.value }} password: ${{ secrets.GITHUB_TOKEN }} - # Run on branch pushes (develop only) and _any_ tag pushes. + # Run on branch pushes (except main, it'll follow develop) and _any_ tag pushes. - name: Tag and push service image with version tag + if: ${{ github.event_name == 'push' && github.ref_name != 'main' }} run: | docker tag \ simdb-dashboard:service \ - ghcr.io/${{ steps.repo_owner.outputs.value }}/simdb-dashboard:${{ needs.build.outputs.version }} - docker push ghcr.io/${{ steps.repo_owner.outputs.value }}/simdb-dashboard:${{ needs.build.outputs.version }} + ghcr.io/${{ steps.repo_owner.outputs.value }}/simdb-dashboard:${{ steps.version.outputs.value }} + docker push ghcr.io/${{ steps.repo_owner.outputs.value }}/simdb-dashboard:${{ steps.version.outputs.value }} - # Run on branch pushes only, so that older tag pushes won't overwrite newer develop images - - name: Tag and push service image with "develop" - if: ${{ github.ref_type == 'branch' }} - # Note that branch pushes other than to "develop" are already filtered out by workflow trigger rules above + # Run on develop pushes only + - name: Tag image :develop and publish + if: ${{ github.event_name == 'push' && github.ref_name == 'develop' }} run: | docker tag \ simdb-dashboard:service \ ghcr.io/${{ steps.repo_owner.outputs.value }}/simdb-dashboard:develop docker push ghcr.io/${{ steps.repo_owner.outputs.value }}/simdb-dashboard:develop - # These steps run on tag pushes only - - name: Tag and push service image with "latest" - if: ${{ github.ref_type == 'tag' }} + # Run on main pushes only + - name: Tag image :latest and publish + if: ${{ github.event_name == 'push' && github.ref_name == 'main' }} run: | docker tag \ simdb-dashboard:service \ ghcr.io/${{ steps.repo_owner.outputs.value }}/simdb-dashboard:latest docker push ghcr.io/${{ steps.repo_owner.outputs.value }}/simdb-dashboard:latest + # This step runs on tag pushes only - name: Package and upload release tarball - if: ${{ github.ref_type == 'tag' }} + if: ${{ github.event_name == 'push' && github.ref_type == 'tag' }} env: GH_TOKEN: ${{ github.token }} GH_REPO: ${{ github.repository }} run: | tar -czf "${{ runner.temp }}/simdb-dashboard-dist.tar.gz" \ -C "${{ runner.temp }}/dist" . - gh release create "${{ needs.build.outputs.version }}" \ + gh release create "${{ steps.version.outputs.value }}" \ "${{ runner.temp }}/simdb-dashboard-dist.tar.gz" \ --generate-notes diff --git a/docs/installation.md b/docs/installation.md index 85c63db..1060b73 100644 --- a/docs/installation.md +++ b/docs/installation.md @@ -91,23 +91,19 @@ for the same defaults and where they are consumed. ## Published image tags CI publishes `ghcr.io/iterorganization/simdb-dashboard` docker images on every -PR merge to `develop` and tagged commits (releases): +push to `develop` or `main`, and on tagged commits (releases): | Tag | Pushed on | Mutable | | --- | --- | --- | | `` | `develop` and tag pushes | no | | `develop` | `develop` pushes | yes | -| `latest` | tag pushes | yes | +| `latest` | `main` pushes | yes | `` is `git describe --tags --always` at the pushed commit (e.g. `0.9.0` on a tag, `0.9.0-12-gabc1234` otherwise). The versioned image is therefore treated as immutable and never reused across events. -Deploy `latest` (the default) or pin a version for reproducibility — -`SIMDB_DASHBOARD_TAG=0.9.0`. `latest` only exists once a tag has been pushed, and -tracks whichever tag was pushed last: it equals the newest release only if you -always tag in increasing version order, but nothing enforces that. `develop` is -for testing, not production hosts. +Deploy `latest` (the default, "stable") or pin a version for reproducibility. ## Local container building and installation workflow (Docker image + Compose) @@ -234,7 +230,8 @@ index path should be `/www/data/dashboard/index.html`. ## Exporting a runnable service image tar (non-Compose) -If you want a portable Docker image artifact (similar to CI artifacts), use: +If you want a portable Docker image tar — for example to move the image to a +host that cannot pull from the registry — use: ```sh make simdb-dashboard-service.tar