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
87 changes: 39 additions & 48 deletions .github/workflows/ci.yml
Original file line number Diff line number Diff line change
@@ -1,25 +1,36 @@
name: CI/CD Pipeline

# Triggers and action summary:
# pull-request -> build and verify.
# push develop -> build, verify, and push image tagged :<version> and :develop.
# push main -> build, verify, and push image tagged :latest.
# push tag -> build, verify, and push image tagged :<version>.

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" ]

# 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
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
Expand Down Expand Up @@ -98,76 +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 (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:${{ steps.version.outputs.value }}
docker push ghcr.io/${{ steps.repo_owner.outputs.value }}/simdb-dashboard:${{ steps.version.outputs.value }}

# 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:${{ 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:develop
docker push ghcr.io/${{ steps.repo_owner.outputs.value }}/simdb-dashboard:develop

# These steps run on tagged commits only — `:latest` tag and GitHub Release.
- name: Tag and push 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
8 changes: 7 additions & 1 deletion docker-compose.systemd.yml
Original file line number Diff line number Diff line change
Expand Up @@ -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):
# <version> 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.
Expand Down
7 changes: 7 additions & 0 deletions docs/development.md
Original file line number Diff line number Diff line change
Expand Up @@ -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).
22 changes: 20 additions & 2 deletions docs/installation.md
Original file line number Diff line number Diff line change
Expand Up @@ -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`).
Expand All @@ -88,6 +88,23 @@ 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
push to `develop` or `main`, and on tagged commits (releases):

| Tag | Pushed on | Mutable |
| --- | --- | --- |
| `<version>` | `develop` and tag pushes | no |
| `develop` | `develop` pushes | yes |
| `latest` | `main` pushes | yes |

`<version>` 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, "stable") or pin a version for reproducibility.

## 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.
Expand Down Expand Up @@ -213,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
Expand Down
Loading