xoa-hl

XOA-hl のソフトウェアのビルドです。Xen Orchestra にホームラボ向けの変更を 加え、RPM としてパッケージ化します。

リポジトリ： Vagrantin/xoa-hl · 言語：Bash / RPM の spec · ライセンス：AGPL-3.0

目的

このリポジトリは Xen Orchestra HomeLab Edition（XOA-hl）をビルドします。 オープンソースの xen-orchestra のサーバーと XO 5 の Web 画面を、固定したアップストリームのコミットから取得し、 ホームラボ向けに手を入れて、XCP-ng 用にパッケージ化したものです。ビルドの たびに、1 つの成果物を GitHub のリリースとして公開します。

この RPM を build-xoa-hl が XOA の VM アプライアンス に入れます。公開された RPM リポジトリからアプライアンスを更新します。 stable/testing チャネルについては対象リリースの アップデートを参照してください。

リポジトリの構成

xoa-hl/
├── UPSTREAM_XO                 ← 固定したアップストリームの xen-orchestra（コミット + バージョン）
├── container/
│   └── Containerfile           ← AlmaLinux 9 のビルド用イメージ（Node 24、yarn、rpm 関連ツール）
├── scripts/
│   ├── build-xo.sh             ← ビルド本体：取得 + パッチ + yarn build + tar
│   └── validate-patches.sh     ← patches/ を metadata.toml と照合する
├── patches/
│   ├── metadata.toml           ← 各パッチの目的と、変更する対象のファイル
│   ├── menu-hide-items.patch   ← Vates のサブスクリプションが必要なメニュー項目を隠す
│   ├── xcp-hl-updates.patch    ← XCP-hl のリポジトリを Patches タブに加える
│   └── xoa-hl-update-api.patch ← アプライアンス独自の「XOA-HL Updates」設定ページ
├── SPECS/
│   └── xoa-hl.spec             ← RPM：/opt/xo のビルド済み XO + systemd ユニット
├── SOURCES/                    ← systemd ユニット、アップデート用スクリプト、sudoers の規則、.repo ファイル
├── pages/                      ← 公開する yum リポジトリのインデックスページと .repo ファイル
└── .github/workflows/
    ├── build-xoa.yml           ← CI：ビルド + RPM + GitHub リリース
    └── pages-repo.yml          ← 最近の RPM を署名付きの yum リポジトリとして再公開

バージョンの固定

ビルドの対象は固定したアップストリームのコミットで、リポジトリの直下にある UPSTREAM_XO ファイルで指定します。

XO_COMMIT=e281c536d3b1e97ccfb3b0826f91b7dbb6c4478c
XO_VERSION=5.113.2

バージョン文字列は、この 2 つを組み合わせたものです。 <XO_VERSION>_<短い SHA> の形で、たとえば 5.113.2_e281c536 になります。 build-xo.sh がこれを out/VERSION に書き出し、CI が RPM のバージョンとして 使います。リリースは v<version>-ce<N> というタグ（たとえば v5.113.2_e281c536-ce17）を push して作ります。N が RPM のリリース番号に なるので、ビルドごとに別のパッケージになり、dnf でアップデートできます。

ビルドの流れ（scripts/build-xo.sh）

ビルドは AlmaLinux 9 のコンテナの中で /build を対象に動きます。

1. 固定した SHA で浅く取得する。 git init + git fetch --depth 1 origin $XO_COMMIT + checkout FETCH_HEAD の順です。 --depth 1 で SHA を直接指定することで、約 1 GB の履歴全体を取得せずに 済み、再現性も保てます。
2. パッチを適用する。 patches/*.patch のそれぞれに patches/metadata.toml の項目があるか（その逆も）を確認してから、 git apply --verbose で 1 つずつ適用します。ce40 では 16 個の宣言済みパッチがあります。例：
   • menu-hide-items：HomeLab の対象外のメニュー項目を非表示にします。 関連するすべての API が存在しないことを意味しません。
   • xcp-hl-updates：Xen Orchestra がホストの updater.py プラグインに 送る問い合わせに XCP-hl のリポジトリを加え、XCP-hl のパッケージが Patches タブに出るようにします。
   • xoa-hl-update-api：アプライアンス独自のアップデート用 API と、 XOA-HL Updates の設定ページを加えます。
3. packages/xo-server/xoahl.config.toml を書き出す。 これは RPM が あとで利用者の設定として入れる実行時の設定です。443 番ポートでの HTTPS、 /opt/xo/xoahl.crt と /opt/xo/xoahl.key、Redis は redis://127.0.0.1:6379/0 を指定します。
4. TLS 生成を RPM インストール時に行う。 ce40 のビルドは共通の秘密鍵を 配布しません。%post がアプライアンスで初期の鍵と証明書を生成します （RSA 4096、3650 日、CN xoa.local、鍵 600、証明書 644）。
5. 導入とビルド。 yarn のあと、すべての workspace（サーバーと XO 5 の Web 画面）で yarn build を実行します。
6. 不要物の削除。 .git、.github、.changesets、docs、 packages/xo-server-test*、packages/xo-server-cloud を削除します。
7. devDependencies の除去。 yarn workspaces focus --production （代替手段は yarn install --production）を使い、workspace の シンボリックリンクは保ちます。
8. パッケージ化。 不要物を削除したモノレポ全体を tar czf out/xoa-hl-<version>.tar.gz でまとめます（**/*.map は除外）。 このアーカイブは RPM のビルドの入力に使うだけで、公開はしません。

RPM（SPECS/xoa-hl.spec）

RPM には、ビルド済みの Xen Orchestra そのもの（約 70 MiB）が入っています。 node_modules にネイティブのアドオンが含まれるため、noarch ではなく x86_64 です。インストールされるものは次のとおりです。

インストール時に %post は次のことを行います。

1. 初回インストール時にだけ利用者の設定を用意します。 /root/.config/xo-server/config.toml が存在しない場合にかぎり、 xoahl.config.toml をそこにコピーします。アップグレード時には手を 触れず、運用側の変更をそのまま残します。
2. 鍵や証明書、または /var/lib/xoa-hl/tls-generated マーカーがない場合に TLS を生成します。マーカーは旧方式の共通鍵を置き換えるためのものです。
3. systemctl enable redis --now を実行し、xo-server を有効にします。 更新タイマーは明示的に設定するまで無効です。

%posttrans はパッケージのトランザクション完了後に xo-server を再起動します。

%preun が xo-server を停止して無効にするのは、最終的なアンインストールの ときだけで、アップグレードのときは行いません。RPM の削除は所有するファイルを 削除しますが、運用者の設定や所有されていない実行時データは残る場合があります。 %postun は最終削除時に systemd を再読み込みします。

ce40 の実行時の依存：Node.js 24（25 未満）、OpenSSL、Redis、 dnf-plugins-core、および Xen Orchestra が リモートストレージに必要とするマウント関連のツール（nfs-utils、 cifs-utils、ntfs-3g、lvm2）です。パッケージには Epoch: 1 が付いて いるため、今の番号の付け方より前のビルドよりも新しいものとして扱われます。

ビルド環境

container/Containerfile がビルド用のイメージを定義します。AlmaLinux 9 に gcc/make/git/patch、Python 3、Node.js 24（NodeSource）、yarn、 rpm-build/rpmdevtools を入れたものです。アーカイブと RPM はどちらも 同じイメージでビルドします。

ビルドは GitHub Actions でのみ行い、ローカルでビルドする手順は用意して いません。CI は Docker でイメージをビルドし、その中で build-xo.sh を 実行します。アーカイブと VERSION ファイルはランナー上の out/ にでき、 RPM のビルドに使われます。

CI のワークフロー（GitHub Actions）

.github/workflows/build-xoa.yml は、v*-ce<N> のタグの push と workflow_dispatch で実行されます。

1. すべてのシェルスクリプトの構文を確認します。scripts/*.sh は bash で、 RPM に入る SOURCES/*.sh は sh で確認します。
2. コンテナのイメージをビルドし、その中で build-xo.sh を実行します （patches/、scripts/、out/、UPSTREAM_XO をマウントします）。
3. out/VERSION を読み、タグの N を RPM のリリース番号にします。
4. 同じイメージの中で、アーカイブを SOURCES/ に置いて rpmbuild -bb SPECS/xoa-hl.spec を実行します。
5. タグと同じ名前の GitHub リリースを作り、RPM を公開します。

.github/workflows/pages-repo.yml は選択したリリースの RPM と署名付き メタデータを公開します。アプライアンスのリポジトリ設定が接続先を定義します。 stable/testing の違いはアップデートを参照してください。

オーケストレーターの xoa-vm-agent が作る VM イメージのリリース （タグの接頭辞は xoa-image-、成果物は XOA-hl.xva）は、イメージを ビルドするリポジトリである build-xoa-hl で公開します。 #22 を参照してください。

他のコンポーネントとの関係

• build-xoa-hl：この RPM を AlmaLinux 9 の アプライアンスに入れ、XVA イメージにまとめます。
• xolite-ce：XO Lite の展開ボタンがこのアプライアンスを 導入します。
• xoa-proxy：アプライアンスのイメージを配信するときに 使う HTTPS/gzip の橋渡し役です。
• xcp-orchestrator （buildorchestration リポジトリ内）：その xoa-vm-agent が build-xoa.yml を実行し、VM イメージのビルドを始める前に RPM の リリースを待ちます。

開発に参加する

問題の報告や変更の提案は、Vagrantin/xcp-hlで issue を作ってください。

確認したリリースの範囲

v5.113.2_e281c536-ce40 / xoa-hl@a28085219cdfe9d20700e6060377f5059e42e6b5.

UPSTREAM_XO, build script, RPM, patch metadata.