From 840012409a35694059957ae2e2cb16ebf2e03eae Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Milan=20Felix=20=C5=A0ulc?= Date: Mon, 9 Nov 2026 14:35:46 +0100 Subject: [PATCH 1/2] CI: release and date version in VERSION, one build for all tags VERSION is key=value like the other dockette repos. CI follows the shared shape: Go checks, one build and smoke test, master-only push of latest and the date tag, release and Docker Hub description. Drops the sha tag, SBOM, provenance, cosign signing, the Trivy scan, SHA-pinned actions and the same-day .N suffix. --- .github/workflows/docker.yml | 147 ++++++++++------------------------- AGENTS.md | 4 +- Makefile | 17 ++-- VERSION | 2 +- 4 files changed, 51 insertions(+), 119 deletions(-) diff --git a/.github/workflows/docker.yml b/.github/workflows/docker.yml index 5c4609c..4d89f52 100644 --- a/.github/workflows/docker.yml +++ b/.github/workflows/docker.yml @@ -4,9 +4,6 @@ on: workflow_dispatch: push: - branches: [master] - - pull_request: schedule: - cron: "0 8 * * 1" @@ -15,21 +12,19 @@ permissions: contents: read jobs: - lint: - name: Lint & unit tests + test: + name: Test runs-on: ubuntu-latest + steps: - name: Checkout - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7 + uses: actions/checkout@v7 - name: Set up Go - uses: actions/setup-go@b7ad1dad31e06c5925ef5d2fc7ad053ef454303e # v7 + uses: actions/setup-go@v7 with: go-version-file: go.mod - - name: VERSION format - run: grep -Eqx '[0-9]{4}\.[0-9]{2}\.[0-9]{2}(\.[0-9]+)?' VERSION || { echo "::error file=VERSION::expected YYYY.MM.DD or YYYY.MM.DD.N, got '$(cat VERSION)'"; exit 1; } - - name: gofmt run: test -z "$(gofmt -l .)" || { gofmt -l .; exit 1; } @@ -40,7 +35,7 @@ jobs: run: go test -tags nodynamic -race ./... - name: staticcheck - uses: dominikh/staticcheck-action@9716614d4101e79b4340dd97b10e54d68234e431 # v1 + uses: dominikh/staticcheck-action@v1 with: install-go: false build-tags: nodynamic @@ -57,141 +52,83 @@ jobs: - name: hadolint run: docker run --rm -i -v "$PWD/.hadolint.yaml:/.config/hadolint.yaml:ro" hadolint/hadolint < Dockerfile - smoke: - name: Smoke test - needs: lint + build: + name: Build + needs: test runs-on: ubuntu-latest + steps: - name: Checkout - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7 + uses: actions/checkout@v7 + + - name: Set up QEMU + uses: docker/setup-qemu-action@v4 - name: Set up Docker Buildx - uses: docker/setup-buildx-action@f87e5991a6d7451dcb8d9637bfbc97413f497069 # v4 + uses: docker/setup-buildx-action@v4 + + - name: Read VERSION + id: version + run: . ./VERSION && echo "version=$VERSION" >> "$GITHUB_OUTPUT" - - name: Build image - uses: docker/build-push-action@c3c9e263c25d99ce0380d002d59b67737d91b0dc # v7 + - name: Build image for testing + uses: docker/build-push-action@v7 with: context: . + push: false load: true tags: dockette/docshot:test + build-args: VERSION=${{ steps.version.outputs.version }} cache-from: type=gha cache-to: type=gha,mode=max - - name: Render a page - run: make smoke DOCKER_IMAGE=dockette/docshot:test - - - name: Check HTML isolation - run: make test-isolation DOCKER_IMAGE=dockette/docshot:test - - # Informational: the base image (LibreOffice, Chromium) carries CVEs we cannot fix here; - # the weekly rebuild picks up upstream fixes. Pinned by digest: scanners are a supply-chain target too. - - name: Scan image (Trivy) - run: | - docker run --rm -v /var/run/docker.sock:/var/run/docker.sock \ - aquasec/trivy:0.75.0@sha256:af6acf9a6b85dfe389a1941505c0ce9efef52a4719635e1a962f022a3d855daa \ - image --scanners vuln --severity HIGH,CRITICAL --ignore-unfixed --exit-code 0 --no-progress dockette/docshot:test - - docker: - name: Docker (dockette/docshot) - needs: smoke - if: github.ref == 'refs/heads/master' - runs-on: ubuntu-latest - permissions: - contents: read - id-token: write # keyless cosign signing - steps: - - name: Checkout - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7 - - - name: Install cosign - uses: sigstore/cosign-installer@6f9f17788090df1f26f669e9d70d6ae9567deba6 # v4.1.2 + - name: Test image + run: make smoke test-isolation DOCKER_IMAGE=dockette/docshot:test - name: Login to DockerHub - uses: docker/login-action@81c6f93d4bc991e510b342a00b419b3bb4efc5c6 # v4 + if: github.ref == 'refs/heads/master' + uses: docker/login-action@v4 with: username: ${{ secrets.DOCKERHUB_USERNAME }} password: ${{ secrets.DOCKERHUB_TOKEN }} - - name: Read VERSION - id: version - run: echo "version=$(cat VERSION)" >> "$GITHUB_OUTPUT" - - - name: Set up QEMU - uses: docker/setup-qemu-action@99012661954931238ded8c8b007157a8430204e1 # v4 - - - name: Set up Docker Buildx - uses: docker/setup-buildx-action@f87e5991a6d7451dcb8d9637bfbc97413f497069 # v4 - - # dockette/docshot:latest rolling, latest master - # dockette/docshot: release (YYYY.MM.DD); like other dockette - # versions it's rebuilt by the weekly schedule - # dockette/docshot:sha- immutable, for rollbacks / pinning - - name: Docker meta - id: meta - uses: docker/metadata-action@dc802804100637a589fabce1cb79ff13a1411302 # v6 - with: - images: dockette/docshot - flavor: latest=false - tags: | - type=raw,value=latest - type=raw,value=${{ steps.version.outputs.version }} - type=sha,format=short - labels: | - org.opencontainers.image.version=${{ steps.version.outputs.version }} - + # One build, two tags: latest and - name: Build and push - id: push - uses: docker/build-push-action@c3c9e263c25d99ce0380d002d59b67737d91b0dc # v7 + if: github.ref == 'refs/heads/master' + uses: docker/build-push-action@v7 with: context: . - file: Dockerfile push: true - tags: ${{ steps.meta.outputs.tags }} - labels: ${{ steps.meta.outputs.labels }} + tags: | + dockette/docshot:latest + dockette/docshot:${{ steps.version.outputs.version }} platforms: linux/amd64,linux/arm64 + build-args: VERSION=${{ steps.version.outputs.version }} cache-from: type=gha cache-to: type=gha,mode=max - build-args: | - VERSION=${{ steps.version.outputs.version }} - provenance: mode=max - sbom: true - - # Verify with: cosign verify dockette/docshot: --certificate-oidc-issuer https://token.actions.githubusercontent.com - # --certificate-identity-regexp '^https://github.com/dockette/docshot/' - - name: Sign image - env: - DIGEST: ${{ steps.push.outputs.digest }} - run: cosign sign --yes "dockette/docshot@${DIGEST}" - # Tags the commit and publishes a GitHub release for VERSION the first - # time it reaches master with the image pushed (make release bumps it). release: name: Release - needs: docker - runs-on: ubuntu-latest + needs: build if: github.ref == 'refs/heads/master' && github.event_name == 'push' + runs-on: ubuntu-latest permissions: contents: write + steps: - name: Checkout - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7 + uses: actions/checkout@v7 - - name: Create release if VERSION is new + - name: Create release env: GH_TOKEN: ${{ github.token }} run: | - v="$(cat VERSION)" - if gh release view "$v" >/dev/null 2>&1; then - echo "Release $v already exists" - exit 0 - fi - # The CHANGELOG.md section of this version, then GitHub's generated list of changes. - awk -v h="## $v" '$0 == h {f = 1; next} /^## / {f = 0} f' CHANGELOG.md > notes.md - gh release create "$v" --target "$GITHUB_SHA" --title "$v" --notes-file notes.md --generate-notes + . ./VERSION + gh release view "$VERSION" || gh release create "$VERSION" --generate-notes docs: name: Docs - needs: docker + needs: build if: github.ref == 'refs/heads/master' uses: dockette/.github/.github/workflows/dockerhub-description.yml@master secrets: inherit diff --git a/AGENTS.md b/AGENTS.md index a62665b..23ca7e7 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -9,7 +9,7 @@ Dockette Docshot builds `dockette/docshot`, an HTTP service that renders any doc - Default image: `dockette/docshot:latest`. - Build context: repository root `.` with `Dockerfile` (multi-stage: `golang:1.27-trixie` build → `gotenberg/gotenberg` runtime stage, which runs `apt-get upgrade` for Debian security fixes → `FROM scratch` + `COPY --from=runtime / /`, one layer so upgraded Chromium/LibreOffice do not stack on the base's copies). - Flattening drops the base image's config: the Dockerfile restates Gotenberg's ENV and WORKDIR; re-check them after bumping `GOTENBERG_VERSION`. -- Date versions: `VERSION` holds `YYYY.MM.DD` (`.N` for a same-day re-release), bumped by `make release`, with `## Unreleased` in `CHANGELOG.md` renamed to `## ` (user-facing: Breaking / Added / Fixed / Changed) that becomes the GitHub release notes; it's built into the binary (`main.version`, via `-ldflags -X`), tags images `latest`, `` and `sha-`, and CI creates the matching GitHub release. See README → *Development*. +- Date versions: `VERSION` holds `VERSION=YYYY.MM.DD`, bumped by `make release`; it is built into the binary (`main.version`, via `-ldflags -X`), tags images `latest` and ``, and CI creates the matching GitHub release. See README → *Development*. - The Go binary (no CGO, `cmd/docshot` + `internal/*`) listens on `:3000` and supervises Gotenberg as a child on `127.0.0.1:3001`; the image `CMD` is Gotenberg's own command line. - docshot is a child subreaper: Gotenberg runs in its own process group, and the supervisor kills/reaps only children outside docshot's group. Tools run with `os/exec` (ffmpeg, bsdtar…) must stay in docshot's group (no `Setpgid`), or a Gotenberg restart would kill them. - On SIGTERM, HTTP drains first (30s), then Gotenberg stops; compose's `stop_grace_period` covers both. @@ -25,7 +25,7 @@ Dockette Docshot builds `dockette/docshot`, an HTTP service that renders any doc - `internal/htmlconv` — formats rendered as an HTML page: e-mail, Outlook msg, EPUB, CSV, JSON, notebooks, calendars, contacts, fonts, SVG, text. - `internal/diskcache` — byte-bounded LRU of rendered results on disk (`DOCSHOT_CACHE_DIR`), index rebuilt on start; `internal/server/cache.go` keys it by URL and handles ETag/TTL/purge. - `internal/apierr`, `internal/metrics`, `internal/lru`, `internal/supervisor` — JSON errors, Prometheus collectors (client_golang), byte-bounded LRU, child-process supervision. -- GitHub Actions (actions pinned to commit SHAs, kept current by Dependabot) runs lint + unit tests, a smoke test and an informational Trivy scan of the built image, then publishes (with SBOM, provenance and a keyless cosign signature) `linux/amd64,linux/arm64` on `master` and the weekly schedule, and creates a GitHub release when `VERSION` is new. +- GitHub Actions runs Go checks (gofmt, vet, tests, staticcheck, govulncheck, shellcheck, hadolint), then builds the image and smoke tests it. Pull requests never push. On `master` and the weekly schedule it pushes `linux/amd64,linux/arm64`, creates a GitHub release when `VERSION` is new and syncs the Docker Hub description. ## Commands diff --git a/Makefile b/Makefile index e4926aa..9d8904a 100644 --- a/Makefile +++ b/Makefile @@ -2,7 +2,7 @@ # Override COMPOSE if your user needs sudo: make up COMPOSE="sudo docker compose" COMPOSE ?= docker compose DOCKER_IMAGE ?= dockette/docshot:latest -VERSION := $(shell cat VERSION) +include VERSION .DEFAULT_GOAL := up .PHONY: test-formats build run up down restart logs ps validate test test-params test-all formats test-unit lint smoke test-isolation version release @@ -36,16 +36,11 @@ test-isolation: ## Untrusted HTML: no JavaScript, no remote fetches (starts ${ version: ## Print VERSION @echo $(VERSION) -# Sets VERSION to today's date (UTC), YYYY.MM.DD — or YYYY.MM.DD.N when that -# date is already released (tagged). Commit and push to master to publish: -# CI then pushes the image and creates the GitHub release. -release: ## Set VERSION to today's date (see README → Versions) - @git fetch -q --tags origin 2>/dev/null || true; \ - v=$$(date -u +%Y.%m.%d); n=0; \ - while git rev-parse -q --verify "refs/tags/$$v" >/dev/null; do n=$$((n+1)); v=$$(date -u +%Y.%m.%d).$$n; done; \ - echo "$$v" > VERSION; \ - echo "VERSION: $(VERSION) -> $$v"; \ - echo "next: rename '## Unreleased' in CHANGELOG.md to '## $$v', then git commit -am 'release: $$v' && git push" +# Sets VERSION to today's date (UTC). Commit and push to master to publish: +# CI then pushes the latest and images and creates the GitHub release. +release: ## Set VERSION to today's date + @sed -i.bak "s/^VERSION=.*/VERSION=$$(date -u +%Y.%m.%d)/" VERSION && rm VERSION.bak + @cat VERSION up: ## Build (if needed) + start docshot (Gotenberg inside) DOCSHOT_VERSION=$(VERSION) $(COMPOSE) up -d --build diff --git a/VERSION b/VERSION index 69dbae9..19352c2 100644 --- a/VERSION +++ b/VERSION @@ -1 +1 @@ -2026.10.25 +VERSION=2026.10.25 From 811d8d98cb657160a0f9fe2e0b866e6c44eeb74d Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Milan=20Felix=20=C5=A0ulc?= Date: Mon, 9 Nov 2026 14:35:46 +0100 Subject: [PATCH 2/2] Docs: README --- README.md | 6 ++---- 1 file changed, 2 insertions(+), 4 deletions(-) diff --git a/README.md b/README.md index 61629bf..390ba34 100644 --- a/README.md +++ b/README.md @@ -329,16 +329,14 @@ make smoke # render one page with the built image make test # end-to-end checks ``` -Releases are dated `YYYY.MM.DD` (see [`VERSION`](VERSION)); what changed is in [`CHANGELOG.md`](CHANGELOG.md). Image tags: +Releases are dated `YYYY.MM.DD` (see [`VERSION`](VERSION)); what changed is in [`CHANGELOG.md`](CHANGELOG.md) and on [GitHub](https://github.com/dockette/docshot/releases). Image tags: | Tag | | |---|---| | `latest` | Latest `master` | | `2026.10.24` | A release; pin this | -| `sha-` | Exact commit | -To release: run `make release`, add the version's section to `CHANGELOG.md`, commit and push. CI publishes the image -and the GitHub release, with that section as its notes. +To release: run `make release`, commit and push. CI publishes the image and the GitHub release. See [how to contribute](https://contributte.org/contributing.html) to this package.