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
147 changes: 42 additions & 105 deletions .github/workflows/docker.yml
Original file line number Diff line number Diff line change
Expand Up @@ -4,9 +4,6 @@ on:
workflow_dispatch:

push:
branches: [master]

pull_request:

schedule:
- cron: "0 8 * * 1"
Expand All @@ -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; }

Expand All @@ -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
Expand All @@ -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:<VERSION> release (YYYY.MM.DD); like other dockette
# versions it's rebuilt by the weekly schedule
# dockette/docshot:sha-<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 <date>
- 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:<tag> --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
Expand Down
4 changes: 2 additions & 2 deletions AGENTS.md
Original file line number Diff line number Diff line change
Expand Up @@ -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 `## <VERSION>` (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`, `<VERSION>` and `sha-<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 `<VERSION>`, 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.
Expand All @@ -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

Expand Down
17 changes: 6 additions & 11 deletions Makefile
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down Expand Up @@ -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 <VERSION> 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 <VERSION> 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
Expand Down
6 changes: 2 additions & 4 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -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-<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.

Expand Down
2 changes: 1 addition & 1 deletion VERSION
Original file line number Diff line number Diff line change
@@ -1 +1 @@
2026.10.25
VERSION=2026.10.25
Loading