diff --git a/.gitea/workflows/images.yml b/.gitea/workflows/images.yml new file mode 100644 index 0000000..e3c816e --- /dev/null +++ b/.gitea/workflows/images.yml @@ -0,0 +1,172 @@ +name: Test and publish container images + +on: + push: + branches: [main, mk_district] + tags: ['v*'] + workflow_dispatch: + inputs: + publish: + description: Publish tested images to the Gitea registry + required: true + default: 'true' + type: boolean + +# No pull_request trigger: a Docker-capable runner must only run trusted code. +# Gitea 1.24 ignores workflow concurrency/permissions/timeout controls; configure +# runner capacity and timeout explicitly (see docs/operations/gitea-images.md). +jobs: + images: + runs-on: ${{ vars.IMAGE_RUNNER_LABEL || 'ubuntu-latest' }} + env: + REGISTRY: ${{ vars.IMAGE_REGISTRY || 'git.anya.jp' }} + IMAGE_OWNER: ${{ vars.IMAGE_OWNER || 'anya' }} + DOCKER_BUILD_SUMMARY: 'false' + DOCKER_BUILD_RECORD_UPLOAD: 'false' + steps: + - name: Check runner and publication configuration + id: config + shell: bash + env: + EVENT_NAME: ${{ github.event_name }} + REQUEST_PUBLISH: ${{ github.event.inputs.publish }} + REGISTRY_USERNAME: ${{ secrets.REGISTRY_USERNAME }} + REGISTRY_PASSWORD: ${{ secrets.REGISTRY_TOKEN }} + run: | + set -euo pipefail + docker version + publish=true + if [[ "$EVENT_NAME" == workflow_dispatch && "$REQUEST_PUBLISH" == false ]]; then + publish=false + fi + if [[ "$publish" == true && ( -z "$REGISTRY_USERNAME" || -z "$REGISTRY_PASSWORD" ) ]]; then + echo 'Set Actions secrets REGISTRY_USERNAME and REGISTRY_TOKEN (write:package), or manually run with publish=false.' >&2 + exit 1 + fi + [[ "$REGISTRY" =~ ^[a-z0-9][a-z0-9.-]*(:[0-9]+)?$ ]] || { echo 'Invalid IMAGE_REGISTRY' >&2; exit 1; } + [[ "$IMAGE_OWNER" =~ ^[a-z0-9][a-z0-9_-]*$ ]] || { echo 'Invalid IMAGE_OWNER' >&2; exit 1; } + echo "publish=$publish" >> "$GITHUB_OUTPUT" + echo "prefix=$REGISTRY/$IMAGE_OWNER" >> "$GITHUB_OUTPUT" + + - name: Check out the exact revision without persisting credentials + uses: https://github.com/actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # v4.2.2 + with: + persist-credentials: false + + - name: Identify the commit-specific image version + id: version + shell: bash + run: | + set -euo pipefail + revision="$(git rev-parse HEAD)" + [[ "$revision" =~ ^[a-f0-9]{40}$ ]] + echo "revision=$revision" >> "$GITHUB_OUTPUT" + echo "tag=sha-$revision" >> "$GITHUB_OUTPUT" + + - name: Set up an isolated BuildKit builder + uses: https://github.com/docker/setup-buildx-action@e468171a9de216ec08956ac3ada2f0791b6bd435 # v3.11.1 + with: + version: v0.34.0 + buildkitd-config-inline: | + [worker.oci] + max-parallelism = 2 + + - name: Test Go packages in the application build environment + uses: https://github.com/docker/build-push-action@263435318d21b8e681c14492fe198d362a7d2c83 # v6.18.0 + with: + context: . + file: Dockerfile + target: test + platforms: linux/amd64 + push: false + + - name: Log in to the Gitea container registry + if: steps.config.outputs.publish == 'true' + uses: https://github.com/docker/login-action@184bdaa0721073962dff0199f1fb9940f07167d1 # v3.5.0 + with: + registry: ${{ env.REGISTRY }} + username: ${{ secrets.REGISTRY_USERNAME }} + password: ${{ secrets.REGISTRY_TOKEN }} + + # Build all three first: a compilation failure must not publish a partial + # release. Loading also permits a local image inspection before publishing. + - name: Build PagesWiki + uses: https://github.com/docker/build-push-action@263435318d21b8e681c14492fe198d362a7d2c83 # v6.18.0 + with: + context: . + file: Dockerfile + target: runtime + platforms: linux/amd64 + load: true + push: false + tags: ${{ steps.config.outputs.prefix }}/pageswiki-app:${{ steps.version.outputs.tag }} + labels: | + org.opencontainers.image.revision=${{ steps.version.outputs.revision }} + org.opencontainers.image.source=${{ github.server_url }}/${{ github.repository }} + + - name: Build adaptor gateway and vim.wasm + uses: https://github.com/docker/build-push-action@263435318d21b8e681c14492fe198d362a7d2c83 # v6.18.0 + with: + context: . + file: Dockerfile.adapter-gateway + platforms: linux/amd64 + load: true + push: false + tags: ${{ steps.config.outputs.prefix }}/pageswiki-adaptor-gateway:${{ steps.version.outputs.tag }} + labels: | + org.opencontainers.image.revision=${{ steps.version.outputs.revision }} + org.opencontainers.image.source=${{ github.server_url }}/${{ github.repository }} + + - name: Build Excalidraw viewer + uses: https://github.com/docker/build-push-action@263435318d21b8e681c14492fe198d362a7d2c83 # v6.18.0 + with: + context: . + file: Dockerfile.excalidraw-viewer + platforms: linux/amd64 + load: true + push: false + tags: ${{ steps.config.outputs.prefix }}/pageswiki-excalidraw-viewer:${{ steps.version.outputs.tag }} + labels: | + org.opencontainers.image.revision=${{ steps.version.outputs.revision }} + org.opencontainers.image.source=${{ github.server_url }}/${{ github.repository }} + + - name: Verify runtime files and build-context exclusions + shell: bash + env: + PREFIX: ${{ steps.config.outputs.prefix }} + TAG: ${{ steps.version.outputs.tag }} + run: | + set -euo pipefail + docker run --rm --network none --entrypoint /bin/sh "$PREFIX/pageswiki-app:$TAG" -c \ + 'test -x /pageswiki && test -d /src/templates && test -d /src/static && test ! -e /src/.env && test ! -e /src/.git && test ! -e /src/data && test ! -e /src/data2 && test ! -e /src/.deployment-backups' + docker run --rm --network none --entrypoint /bin/sh "$PREFIX/pageswiki-adaptor-gateway:$TAG" -c \ + 'test -x /adapter-gateway && test -s /vimwasm/vendor/vim.wasm && test -s /vimwasm/HackNerdFont-Regular.ttf' + docker run --rm --network none --entrypoint /bin/sh "$PREFIX/pageswiki-excalidraw-viewer:$TAG" -c \ + 'test -s /usr/share/nginx/html/index.html && nginx -t' + + - name: Publish all built images + if: steps.config.outputs.publish == 'true' + shell: bash + env: + PREFIX: ${{ steps.config.outputs.prefix }} + TAG: ${{ steps.version.outputs.tag }} + run: | + set -euo pipefail + for image in pageswiki-app pageswiki-adaptor-gateway pageswiki-excalidraw-viewer; do + docker push "$PREFIX/$image:$TAG" + done + echo "Published all three images: $PREFIX/:$TAG" + echo 'Deploy only after this workflow has completed successfully; registry pushes are not atomic.' + + - name: Remove only the per-run image tags from the runner + if: always() && steps.version.outputs.tag != '' + shell: bash + env: + PREFIX: ${{ steps.config.outputs.prefix }} + TAG: ${{ steps.version.outputs.tag }} + run: | + for image in pageswiki-app pageswiki-adaptor-gateway pageswiki-excalidraw-viewer; do + if docker image inspect "$PREFIX/$image:$TAG" >/dev/null 2>&1; then + docker image rm "$PREFIX/$image:$TAG" || echo "Could not remove local CI tag: $image:$TAG" >&2 + fi + done diff --git a/Dockerfile b/Dockerfile index d655660..2bf5919 100644 --- a/Dockerfile +++ b/Dockerfile @@ -1,4 +1,4 @@ -FROM golang:1.25-alpine +FROM golang:1.25-alpine AS source WORKDIR /src @@ -10,6 +10,10 @@ RUN go mod download COPY . . +FROM source AS test +RUN go test ./... + +FROM source AS runtime RUN go build -o /pageswiki ./cmd/pageswiki EXPOSE 8081 diff --git a/README.md b/README.md index ec623ba..49adcdd 100644 --- a/README.md +++ b/README.md @@ -2,6 +2,14 @@ Simplest and powerful wiki architecture for personal +## Container CI + +Gitea Actions tests and builds the application, adaptor gateway, and Excalidraw +viewer, then publishes them to the Gitea container registry with commit-SHA tags. +See [Gitea image builds and registry setup](docs/operations/gitea-images.md) for +runner requirements, registry secrets, and the optional registry Compose overlay. +The workflow does not deploy to production. + ## Knowledge City Model Pages Wiki uses urban language for its content hierarchy: diff --git a/docker-compose.registry.yml b/docker-compose.registry.yml new file mode 100644 index 0000000..8df49b3 --- /dev/null +++ b/docker-compose.registry.yml @@ -0,0 +1,11 @@ +# Optional overlay. Never builds locally when used with `up --no-build`. +# Use all three images from the same successful workflow, identified by SHA. +services: + app: + image: ${PAGESWIKI_IMAGE_PREFIX:-git.anya.jp/anya}/pageswiki-app:${PAGESWIKI_IMAGE_TAG:?Set the image tag from a successful Gitea workflow} + app2: + image: ${PAGESWIKI_IMAGE_PREFIX:-git.anya.jp/anya}/pageswiki-app:${PAGESWIKI_IMAGE_TAG:?Set the image tag from a successful Gitea workflow} + adaptor-gateway: + image: ${PAGESWIKI_IMAGE_PREFIX:-git.anya.jp/anya}/pageswiki-adaptor-gateway:${PAGESWIKI_IMAGE_TAG:?Set the image tag from a successful Gitea workflow} + excalidraw-viewer: + image: ${PAGESWIKI_IMAGE_PREFIX:-git.anya.jp/anya}/pageswiki-excalidraw-viewer:${PAGESWIKI_IMAGE_TAG:?Set the image tag from a successful Gitea workflow} diff --git a/docs/operations/gitea-images.md b/docs/operations/gitea-images.md new file mode 100644 index 0000000..3734355 --- /dev/null +++ b/docs/operations/gitea-images.md @@ -0,0 +1,148 @@ +# Gitea Actions でのイメージビルド・保管 + +## 対象と境界 + +`git.anya.jp` は導入時点で Gitea **1.24.6**。ワークフローは +`.gitea/workflows/images.yml`。本番への自動デプロイはしない。 + +| イメージ | Dockerfile | 利用先 | +| --- | --- | --- | +| `git.anya.jp/anya/pageswiki-app` | `Dockerfile` | app / app2 共通 | +| `git.anya.jp/anya/pageswiki-adaptor-gateway` | `Dockerfile.adapter-gateway` | code-server / vim.wasm 連携 | +| `git.anya.jp/anya/pageswiki-excalidraw-viewer` | `Dockerfile.excalidraw-viewer` | Excalidraw Viewer | + +Kroki、Mermaid、code-server は upstream の配布イメージを利用するため、 +このワークフローで再ビルド・再配布しない。現在の対象は `linux/amd64`。 + +## 実行フロー + +1. runner の Docker 接続と、公開時の registry secret を検査。 +2. checkout。Git 認証情報は作業ディレクトリに永続化しない。 +3. 本体 Dockerfile の `test` ステージで `go test ./...`。 +4. 3 イメージを順番にビルド。Go や npm のビルド失敗時には公開しない。 +5. ネットワークなしの一時コンテナで必要な成果物と秘密情報・データの除外、nginx 設定を検査。 +6. すべてのビルド・検査成功後、3 イメージを registry へ push。 +7. runner にロードした当該 CI タグを削除し、Buildx Action が専用 builder を後処理。 + +registry への 3 回の push は原子的ではない。途中で通信・認証・容量エラーが +起きた場合は一部のみ存在し得るため、**必ずワークフロー全体の成功を確認してから利用**する。 +ビルド検証のみの手動実行では push を省略し、registry secret は不要。 + +## Gitea 側の設定 + +### 1. リポジトリの Actions を有効化 + +リポジトリ設定で Actions を有効にする。 + +- リポジトリ: +- 実行履歴: + +`main` / `mk_district` への push、`v*` タグの push が対象。 +`workflow_dispatch` による手動実行も定義している。Gitea の手動実行 UI に +ワークフローが出ない場合は、デフォルトブランチにワークフローを取り込む必要がある。 +本設定を追加しただけでは main へのマージは実施しない。 + +### 2. 専用 runner + +runner の実行環境には以下が必要。 + +- Linux amd64、bash、git、Docker CLI と利用可能な Docker daemon。 +- Node.js 20 対応の JavaScript Action 実行環境。 +- Gitea、GitHub、Docker Hub、Go module proxy、npm registry への疎通。 +- 3 イメージとビルドキャッシュを扱えるディスク容量。 + +既定のジョブラベルは `ubuntu-latest`。通常の同名ラベルでも、実体が Node.js +のみのコンテナでは Docker CLI や daemon が利用できるとは限らない。 +**ジョブ環境内で `docker version` が成功するように構成すること。** +別ラベルの場合は Repository Actions Variable `IMAGE_RUNNER_LABEL` に設定する。 +例: 専用 host runner を `pageswiki-image-builder:host` で登録し、変数には +`pageswiki-image-builder` を指定する。既存 runner へ無条件に host ラベルを追加しない。 + +Docker socket を使えるジョブは daemon の強い権限を持つ。本番サーバーと共用せず、 +信頼するコードのみを実行する専用 runner / daemon を利用する。外部 fork の PR +をこの runner で実行しない。本ワークフローは意図的に PR トリガーを設けていない。 + +Gitea 1.24 では workflow の `concurrency`、`permissions`、job の +`timeout-minutes` に依存できない。runner 側で **capacity=1** と適切な timeout +(目安 2 時間)を設定する。同じコミットの重複実行でも、ロードした CI タグの +後処理が別ジョブと衝突しないよう、レポジトリ用 runner は同一 daemon で直列実行する。 +BuildKit の内部並列度も 2 に制限しているが、これはCPU・メモリの厳密な上限ではない。 + +### 3. Registry 認証 + +Repository Settings → Actions → Secrets に次の値を設定する。 + +| Secret | 内容 | +| --- | --- | +| `REGISTRY_USERNAME` | `anya` 名前空間へ書き込める Gitea アカウント | +| `REGISTRY_TOKEN` | そのアカウントの `write:package` 権限を持つアクセストークン | + +runner 登録トークン、Git clone 用の資格情報、PagesWiki のキャンパストークンとは +別物。値をリポジトリ、Dockerfile、build args、チャットへ貼り付けない。 +可能ならパッケージ公開用の専用アカウントと最小権限を使う。 +Gitea 1.24 のジョブ用自動トークンによるパッケージ公開は前提にしない。 + +公開先を変える場合の Repository Actions Variables: + +| Variable | 既定値 | +| --- | --- | +| `IMAGE_REGISTRY` | `git.anya.jp`(スキームなし) | +| `IMAGE_OWNER` | `anya`(小文字) | +| `IMAGE_RUNNER_LABEL` | `ubuntu-latest` | + +パッケージの公開・非公開設定は Gitea 側で確認する。アプリイメージには +ソースコードが含まれるため、ソースを非公開運用する場合はパッケージも同様に扱う。 + +## タグ・キャッシュ・容量 + +3 イメージすべて同じ `sha-<40桁のコミットID>` タグを使う。 +自動 `latest` / ブランチ別の可変タグは付けないため、古いジョブが後から完了しても +新しいリリースを上書きしない。同一コミットの再実行は同じ SHA タグを再公開し得る。 +base image と npm / apk 等の取得元は完全固定ではないため、**バイト単位で同一の +イメージを指定する必要があるときは registry の digest を利用**する。 + +ビルド中のキャッシュは専用 BuildKit builder 内で共有し、永続 registry cache は +初期導入では作らない。runner のキャッシュや registry 世代は容量監視対象とし、 +将来の保持期間・GC 設定は本番で使用中の digest とロールバック対象を除外して決める。 +ワークフローから daemon 全体の `docker system prune` は実行しない。 + +公式 Action はバージョン名だけでなく完全なコミット SHA に固定。 +Gitea にない GitHub artifact API 依存を避けるため、Docker Action の +build record upload / summary は無効化している。 + +## 本番でビルドせず利用する(手動) + +既存 `docker-compose.yml` はローカルビルド方式のまま保持する。 +registry イメージ利用時のみ `docker-compose.registry.yml` を重ねる。 + +```bash +# パスワード/PATはプロンプトで入力(自動化では --password-stdin を使用) +docker login git.anya.jp + +# ワークフロー全体が成功した実際のコミットを指定する。 +export PAGESWIKI_IMAGE_TAG='sha-<40桁のコミットID>' + +docker compose -f docker-compose.yml -f docker-compose.registry.yml \ + pull app app2 adaptor-gateway excalidraw-viewer + +# バックアップと設定・データの互換性を確認した後に実行する。 +docker compose -f docker-compose.yml -f docker-compose.registry.yml \ + up -d --no-build app app2 adaptor-gateway excalidraw-viewer +``` + +上記タグは例示のプレースホルダー。実コマンドでは実際のタグへ置換する。 +prefix を変える場合は `PAGESWIKI_IMAGE_PREFIX`(既定 `git.anya.jp/anya`)。 +`.env` のキャンパス参加トークンなど、既存のデプロイ設定も引き続き必要。 +ロールバック時もデータ互換性を確認して以前のタグ/digestを明示する。 +ここに記載した本番更新操作はCIからは実行しない。 + +## 公式参照 + +導入時のローカル検証(2026-09-27): Docker test ステージの全 Go テスト、 +3 Dockerfile の実ビルド、成果物/秘密情報除外検査、registry Compose の解決を確認。 +actionlint は Gitea 固有の絶対 Action URL を検証入力でのみ通常形式に置換して成功。 +Gitea 上の runner / secrets の設定と実行成功は、ローカル検証とは別に確認が必要。 + +- [Gitea 1.24 Act Runner](https://docs.gitea.com/1.24/usage/actions/act-runner/) +- [Gitea 1.24 Actions の互換性・制限](https://docs.gitea.com/1.24/usage/actions/comparison/) +- [Gitea Container Registry](https://docs.gitea.com/usage/packages/container/)