# CLAUDE.md — yourls Helm Chart

> **共通ルール(要約)** — 詳細は `P:\Claude\CLAUDE.md`(全体共通)と `P:\Claude\HelmChart\CLAUDE.md`(Helm チャート共通: リリースフロー・ワークフロー・クラスタ構成)を参照。
> 作業前に pull ／ 機能変更時は README 更新 ／ 作業単位ごとに commit → push まで ／ コミットに AI クレジットを付けない ／ pull で入った変更を revert しない ／ Helm・PHP はローカル実行不可(Python のみ可)。

## リポジトリ概要

Raspberry Pi などのベアメタルで稼働することを想定した、Kubernetes 上で動作する Alpine Nginx + YOURLS(URL短縮サービス、PHP-FPM)の Helm チャート。

- **Gitea リポジトリ**: `ssh://git@192.168.9.65/helmchart/yourls`
- **Helm リポジトリ**: `https://git.cafepieters.com/api/packages/helmchart/helm`
- **公式イメージ**: `docker.io/yourls`(`docker-library`配下の公式イメージ。`yourls/yourls`という別名前空間のイメージは非公式であり誤り)

## 実行環境について

YOURLS本体(コアファイル一式)はイメージ内蔵のもの(`docker.io/yourls:<version>-fpm-alpine`)をemptyDirにコピーして使い捨てで起動する(WordPressチャートと同じbitnami方式)。`user/plugins`・`user/pages`・`user/languages`(管理画面経由で追加されるプラグイン・カスタムページ・言語ファイル)のみPVCで永続化する。`user/config.php`はYOURLS公式イメージ同梱の`config-container.php`(環境変数を`getenv()`で読むだけのテンプレート。YOURLS本体はこのファイルに書き込まない)をPod起動のたびにコピーするだけで、永続化はしない。PHPの実行環境はイメージに依存し、本リポジトリにPHPコードは含まれない。

データベースは外部MySQL/MariaDBを前提とし、サブチャートは同梱しない(WordPress/phpfpmチャートと同一方針)。

## 設計上の注意(このチャート固有)

- **YOURLS_SITEは固定値**: WordPressの`WP_HOME`/`WP_SITEURL`のように実行時のHTTP Hostヘッダーから自動導出されない。短縮URL生成に使う固定文字列のため、`values.yourls.site`を実際のドメインに必ず設定する必要がある。
- **Cookie暗号化キー・自動生成パスワードの安定化**: `templates/_helpers.tpl`の`yourls-nginx.existingSecretValue`が`lookup`関数で既存Secretの値を参照し、`helm upgrade`のたびに`cookiekey`や自動生成された`admin-password`がローテーションされない(ログインセッション・既知のパスワードが無効化されるのを防ぐ)。`helm template`(クラスタ未接続)ではlookupが空を返すため、その場合のみ新しい値が生成される(クラスタに適用されないため実害はない)。
- **liveness/readinessの使い分け**: `livenessProbe`は`/robots.txt`(YOURLSがDB接続前に無条件で200を返す固定応答。`yourls-loader.php`のソースで確認済み)を見ており、DB接続の一時的な断でPodが再起動ループに陥らないようにしている。`readinessProbe`は`/`(DB接続を要する)を見ており、DB未接続時はServiceの振り分けから外れる。
- **VIP/グローバルIPの希少性**: 組織CLAUDE.mdの「実運用クラスタ構成」を踏まえ、`service.type`の既定は`ClusterIP`(+Ingress共有)。専用LoadBalancer IPが必要な場合のみ明示的に`LoadBalancer`へ変更する運用とする。
- **非root実行**: `yourls`/`yourls-init`コンテナは`runAsUser/runAsGroup: 82`(www-data)で実行し、Pod全体に`fsGroup: 82`を設定してPVC/emptyDirの書き込み権限を確保する。`nginx`コンテナは公式イメージの挙動(masterはroot、workerは`nginx`ユーザー)に委ね、org内WordPressチャートと同じ方針でsecurityContextの上書きは行わない。

## チャート改修履歴

### ゼロからの再設計(2026-09-12, v1.10.6)

**背景**: 旧チャートが正しく動作しないとの報告を受け、スクラッチで設計をやり直した。

**旧チャートの問題点**(調査により判明):
- `.gitea/workflows/image-update-and-release.yaml`が存在しない`docker.io/yourls/yourls`(個人名前空間)を追跡しており、正しい公式イメージ`docker.io/yourls`(`library/yourls`)ではなかった。
- `image.yourls.tag`が`1.10.2-fpm-alpine`と古く(最新は`1.10.6-fpm-alpine`)、追跡ワークフローの参照先が誤っていたため自動更新も機能していなかった。
- Bitnami MySQLサブチャートに依存しており、org内の他チャート(WordPress/phpfpm)が採用する「外部DB前提・サブチャート非同梱」の方針と乖離していた。ARM(Raspberry Pi)環境でのBitnamiサブチャートの動作も未検証だった。
- セキュリティコンテキストが一切設定されておらず(root実行)、実IP取得・ヘルスチェックの設計(liveness/readinessの使い分け)も無かった。
- `.gitea/workflows/helm-release.yaml`が存在せず、mainブランチpush時のチャート公開が自動化されていなかった。

**新チャートの設計方針**: [YOURLS/containers](https://github.com/YOURLS/containers)(公式Dockerイメージのソース)の`container-entrypoint.sh`・`Dockerfile.template`・`config-container.php`を実際に確認した上で、この組織で実績のあるWordPressチャートの構成パターン(emptyDir+PVC分離、fsGroup非root実行、real IP取得対応、extraEnvFrom/extraEnvによるsecret-manager連携)を踏襲して再構築した。

**対象ファイル**: 全ファイル(スクラッチから再作成)。詳細は README.md を参照。