Files
pages/docs/operations/gitea-images.md
T
Anya Tokugawa 61ecd1ffbd
Build and publish container images / images (push) Successful in 10m42s
ci: isolate temporary test databases from runner overlay I/O
2026-11-08 06:08:09 +09:00

178 lines
9.3 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# Gitea Actions でのイメージビルド・保管
## 対象とフロー
`.gitea/workflows/images.yml` は checkout → テスト → ビルド → registry への push を担当する。
runner の環境構築や Gitea の事前疎通診断は行わず、本番へ自動デプロイもしない。
導入先は Gitea 1.24.6、対象は `linux/amd64`。
| イメージ(prefix: `git.anya.jp/anya/`) | Dockerfile |
| --- | --- |
| `pageswiki-app`(app / app2 共通) | `Dockerfile` |
| `pageswiki-adaptor-gateway` | `Dockerfile.adapter-gateway` |
| `pageswiki-excalidraw-viewer` | `Dockerfile.excalidraw-viewer` |
Kroki、Mermaid、code-server は upstream の配布イメージを使用する。
`main` / `mk_district` への push、手動実行でビルド・公開する。
`v*` タグは別の `release.yml` でビルド済みイメージを昇格し、再ビルドしない。
採番は [SemVer 2.0.0 の運用規則](versioning.md) に従う。
本体の `test` ステージで `go test ./...` を実行し、3 イメージのビルドが成功した後に push する。
3 回の push は原子的ではないため、**ワークフロー全体の成功を確認してから利用**する。
最後に当該ジョブのローカル CI タグと専用 builder を後処理する。
## runner 環境(初回・環境変更時のみ)
`ubuntu-latest` は runner を選ぶラベルであり、ツールの存在を保証するものではない。
workflow の `container.image` で Gitea 公式ジョブイメージを digest 固定する。
その中の Node.js、git、bash、Docker CLI を使い、毎回のインストールや探索は行わない。
Node は tool cache 内にあるため、workflow の `PATH` に明示する。
**ジョブイメージの更新時には Node のパスも併せて確認・更新する。**
2026-09-27 にローカル実行で確認した組み合わせ:
- イメージ: `docker.gitea.com/runner-images:ubuntu-latest@sha256:fd911d7417bfbf0f454530e447da95b58001e1df41bbc5e1a8dd35d432575aae`
- Node: `/opt/acttoolcache/node/24.19.0/x64/bin/node`
Docker daemon、外部ソース・パッケージ取得先への接続、ビルド用ディスク容量は必要。
Docker socket を使うジョブは強い権限を持つため、信頼するコードのみを実行する。
外部 PR はトリガーにしていない。将来は本番と別の CI 専用 daemon へ分離する。
### 提示された Docker 版 Runner 3 の構成
ホストの Docker ソケットを利用する場合は **`docker.io/gitea/runner:3`(通常版)** を使う。
`3-dind` / `3-dind-rootless` とソケットの bind mount を混在させない。
runner が利用する daemon と `anya-npm-net` が存在する daemon は一致させる。
別 daemon に同名ネットワークを作っても接続は共有されない。
Gitea 側 Compose のラベルで Docker 実行方式を明示する。
workflow の `container.image` が実際のジョブ用イメージを指定する。
```yaml
# Gitea 側 docker-compose.yml の runner.environment
GITEA_RUNNER_LABELS: "ubuntu-latest:docker://docker.gitea.com/runner-images:ubuntu-latest"
```
`./runner/data:/data` と `./runner/config.yaml:/config.yaml` の配置なら、
既存の `runner/config.yaml` へ以下をマージする。`.runner` は消さない。
環境変数のラベルは設定ファイルより優先する。
```yaml
runner:
file: /data/.runner
capacity: 1
timeout: 2h
container:
docker_host: "unix:///var/run/docker.sock"
options: "--add-host=git.anya.jp:172.18.0.10"
# 既存ネットワークを使い、自動的な /16 の作成を避ける。
network: "anya-npm-net"
```
既存の options があれば追記する。runner サービスの socket volume と
`extra_hosts: ["git.anya.jp:172.18.0.10"]` は維持する。
実行中ジョブの完了後、Gitea 側 Compose ディレクトリで反映する。
```bash
docker compose up -d --no-deps --force-recreate runner
```
restart だけでは環境変数変更は反映されない。登録し直す必要はない。
PagesWiki 側の Compose を変更しても runner の設定には反映されない。
Gitea 1.24 では workflow の concurrency / timeout-minutes に依存せず、
runner の capacity / timeout で制御する。同じ daemon 上の当該ビルドは直列実行し、
重複ジョブのタグ後処理が衝突しないようにする。BuildKit 内部の並列度は 2。
### 名前解決の境界
| 通信元 | 名前解決の設定 |
| --- | --- |
| runner コンテナ | runner サービスの extra_hosts |
| ジョブコンテナ | container.options の --add-host |
| docker push を行う daemon | daemon ホストの DNS / hosts(DinD なら daemon コンテナ自身) |
hosts はコンテナ間で自動継承されない。push は Docker daemon で行うため、
BuildKit には registry 用 hosts の追加は不要。
URL は HTTPS のホスト名を維持し、TLS 検証は無効化しない。
重複ネットワークを作らず、新設時は非重複の /27 等を選ぶ。
疎通診断は問題発生時に運用者が行い、通常のビルドには組み込まない。
## Gitea リポジトリ設定
[リポジトリ](https://git.anya.jp/anya/wikipages)で Actions を有効化し、
[実行履歴](https://git.anya.jp/anya/wikipages/actions)で結果を確認する。
Repository Settings → Actions → Secrets:
| Secret | 内容 |
| --- | --- |
| REGISTRY_USERNAME | anya 名前空間へ書き込める Gitea アカウント |
| REGISTRY_TOKEN | そのアカウントの write:package 権限を持つアクセストークン |
runner 登録トークンとは別物。リポジトリ、Dockerfile、build args、チャットへ値を載せない。
Gitea 1.24 の自動ジョブトークンによるパッケージ公開は前提にしない。
任意の Repository Actions Variables:
| Variable | 既定値 |
| --- | --- |
| IMAGE_REGISTRY | git.anya.jp(スキームなし) |
| IMAGE_OWNER | anya(小文字) |
| IMAGE_RUNNER_LABEL | ubuntu-latest |
アプリイメージにはソースコードが含まれるため、パッケージの公開範囲にも注意する。
## テスト用一時領域
Dockerfileのtest段階では、全Goテストを`-p 1`でパッケージ単位に直列化する。
テスト用`TMPDIR`は最大2GiBのtmpfsとし、SQLiteの一時DBをrunnerのoverlay filesystemから分離する。
コンパイラ用`GOTMPDIR`はディスク側の`/tmp`に残す。tmpfsは当該RUNの間だけ存在し、
runtime段階や本番の保存先・WAL・接続タイムアウトには影響しない。
CI run 54では、直列化後も既存の壁紙・Ordoschnellic・Seheweitのテストが
SQLite接続初期化の5秒タイムアウトで失敗した。ストレージ競合を避ける措置であり、
テスト除外・再試行による成功扱い・本番の期限緩和は行わない。
tmpfsは最大2GiBのメモリを消費し得るため、runnerにはコンパイラ等と合わせた余裕が必要。
実ファイル保存の移行確認は、CIとは別に本番DBの隔離コピーで行う。
## タグ・容量・本番利用
3 イメージ共通で `sha-<40桁のコミットID>` を使用し、自動 latest は付けない。
同じコミットの再実行は同じタグを再公開し得る。依存取得元まで完全固定ではないため、
バイト単位の固定には registry の digest を利用する。
公式 Action はコミット SHA 固定。Gitea にない GitHub artifact API への依存を避けるため、
Docker Action の build record upload / summary は無効化する。
ビルド中は専用 BuildKit builder のキャッシュを共有し、永続 registry cache は未導入。
容量・保持世代は別途管理し、本番使用中とロールバック対象は削除しない。
workflow から daemon 全体の docker system prune は行わない。
本番利用は手動。既存 Compose はローカルビルド方式のまま維持し、
registry 利用時だけ overlay を重ねる。
```bash
# PAT はプロンプトで入力(自動化では --password-stdin)。
docker login git.anya.jp
# 全ステップが成功した実際のコミット ID に置き換える。
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 等のデプロイ設定も必要。ロールバック時もデータ互換性を確認する。
## 公式参照
- [Gitea Runner のラベル](https://docs.gitea.com/runner/labels/)
- [Gitea Runner の設定](https://docs.gitea.com/runner/configuration/)
- [Gitea 1.24 Actions の互換性・制限](https://docs.gitea.com/1.24/usage/actions/comparison/)
- [Gitea Container Registry](https://docs.gitea.com/usage/packages/container/)
- [Docker コンテナの DNS と hosts](https://docs.docker.com/engine/network/#dns-services)
- [Dockerfileの一時tmpfsマウント](https://docs.docker.com/reference/dockerfile/#run---mounttype-tmpfs)