サーバーインストール（docker compose）

正規のインストールは自己完結型 tarball と sudo ./install.sh です。 tarball にはすべての docker イメージ（ongrid、ongrid-web、 singchia/frontier）が同梱されているので Docker Hub からの pull は不要 —— 制限された環境やエアギャップでも動作します。

エアギャップ固有の話は エアギャップインストール を、 より素早いウォークスルーは クイックスタート を、 docker を使わない systemd ネイティブインストールは Linux サーバープラットフォーム を参照してください。

前提条件

以下を持つ Linux ホスト：

• 最小 4 GB RAM、推奨 8 GB（Prometheus + Loki + Tempo + MySQL + manager がすべてここに同居）。
• 20 GB 以上の空きディスク が /var/lib/ongrid（データルート）配下にあること。 別の場所にしたければ ONGRID_DATA_DIR=… で調整 —— NFS / iSCSI / NVMe いずれも 動作します。単純な bind-mount です。
• Docker ≥ 24、docker compose v2 サブコマンド付き （docker compose version が表示されること）。
• openssl —— tls.crt / tls.key が事前に置かれていない場合、初回起動時に install.sh が自己署名 TLS 証明書を発行するのに使用。
• インバウンド TCP/443 をブラウザと各 edge から開放。
• インバウンド TCP/40012 を各 edge から開放（frontier ブローカー）。
• 公開 IP またはドメイン（すべての edge から到達可能）。これが ONGRID_PUBLIC_URL に入り、 最もありがちな設定ミスの単独 1 位です。

ONGRID_PUBLIC_URL にプライベート IP を使わない

インストーラーは IP を自動検出し確認を求めます。10.x / 192.168.x / 172.16-31.x のアドレスを受け入れたものの、edge がパブリックインターネット上に ある場合、ログとトレースの push は静かに失敗します。コントロールプレーンのトンネル （nginx と独立して動作）は引き続き動くため、UI 上で edge は健全に見えます —— しかし Loki と Tempo は空のままです。

インストール

# Pick the latest tag at https://github.com/ongridio/ongrid/releases
VER=v0.7.159

gh release download "$VER" \
    --repo ongridio/ongrid \
    -p 'ongrid-*-linux-amd64.tar.xz*'

# Verify the sha256 — the .sha256 sidecar ships with each release.
sha256sum -c "ongrid-${VER}-linux-amd64.tar.xz.sha256"

tar xf "ongrid-${VER}-linux-amd64.tar.xz"
cd     "ongrid-${VER}-linux-amd64"

sudo ./install.sh

便利なフラグ：

フラグ	内容
--mode systemd	docker を使わないネイティブ systemd インストールに切り替え。systemd/install-systemd.sh にディスパッチ。Linux サーバープラットフォーム を参照。
--with-deps	systemd 専用。apt/dnf 経由で mariadb + nginx + grafana を自動インストールし、ピン留めされた prom / loki / tempo / qdrant バイナリを sha256 検証付きで取得。
--profile monitoring	compose 専用。Prometheus をホスト側の 9090 ポートに公開（ラップトップ開発で便利、本番ではデフォルト OFF）。
--no-seed	compose 専用。管理者ブートストラップバナーの出力をスキップ（インストール再実行時）。
--force	compose 専用。既存インストールの上に再インストール（.env とデータボリュームは保持）。

install.sh の動作

順に：

1. プリフライト。 docker CLI が $PATH にあり、デーモンが到達可能で、 docker compose v2 が存在することを確認。いずれかが欠ければ早期終了。

2. 設定をステージング —— ${ONGRID_INSTALL_DIR:-/opt/ongrid}/ 配下に：

   • docker-compose.yml、.env.example、VERSION、frontier.yaml、
   • prometheus.yml（prom コンテナの /etc/prometheus/ に bind-mount）、
   • prometheus-rules.yml（ADR-026 セルフオブザーバビリティアラート）、
   • loki-config.yaml、tempo-config.yaml、
   • grafana/ provisioning、
   • searxng/ 設定、
   • edge/（アーキ別 edge バイナリ + プラグインバイナリ + アップグレードバンドル）。

3. ホストデータディレクトリ作成 —— ${ONGRID_DATA_DIR:-/var/lib/ongrid}/ 配下、各コンテナイメージが動作する uid に chown：

   • mysql/ → 999:999（mysql:8.0）
   • prometheus/ → 65534:65534（prom は nobody）
   • loki/ → 10001:10001
   • tempo/ → 10001:10001
   • grafana/ → 472:472
   • embeddings/ → 65532:65532（manager nonroot ユーザー）

   初回起動でこれを怠ると、prom/loki/tempo/grafana が permission denied on /<datadir> でクラッシュします。

4. 同梱の埋め込みモデルをステージング —— オフライン RAG 用、 /var/lib/ongrid/embeddings/fast-bge-small-zh-v1.5/。カスタムモデルに 既に差し替えてある場合、インストーラーは触りません。

5. nginx 設定をリフレッシュ —— tarball から。${INSTALL_DIR}/certs/ に 証明書がなければ、365 日有効な自己署名証明書を生成 （CN=ongrid、SAN: DNS:ongrid、DNS:localhost、IP:127.0.0.1）。

6. docker イメージをロード —— images/ongrid.tar、images/frontier.tar、 images/ongrid-web.tar を docker load。レジストリ pull は不要。

7. .env を作成または再利用。 ${INSTALL_DIR}/.env が存在すれば保持 （--force でもオペレーター編集 .env は上書きしません）。なければ .env.example からコピー。続いて空欄を強力なランダム値で埋める：

   • MYSQL_ROOT_PASSWORD、MYSQL_PASSWORD —— 24 文字、
   • ONGRID_JWT_SECRET —— 64 文字、
   • ONGRID_ADMIN_PASSWORD —— 20 文字（最終バナー用に記録）、
   • GRAFANA_ADMIN_PASSWORD —— 20 文字。

8. ONGRID_PUBLIC_URL のプロンプト（空欄の場合）。30 秒カウントダウン、 デフォルトは推測されたホスト。/dev/tty を読むので curl ... | bash でも生き残る。

9. docker compose up -d を --env-file .env 付きで実行。-f 引数なしなので、 調整用の docker-compose.override.yml を置いていれば自動ロードされます。

10. https://localhost/healthz を最大 60 秒間ポーリング —— nginx 経由。 manager の /healthz は MySQL に到達可能でエージェントカーネルが配線されると 200 を返します。

11. インストールバナーを表示 —— Web URL、API URL、トンネルエンドポイント、 ブートストラップ管理者メール + パスワード（初回インストール時のみ）。

インストール後

このようなバナーが表示されます：

===============================================================
  ongrid installation complete
===============================================================

Install dir:     /opt/ongrid
Version:         v0.7.159

Web UI:          https://203.0.113.10/
API URL:         https://203.0.113.10/api/v1
Tunnel endpoint: 203.0.113.10:40012   (for edges)

TLS: self-signed cert in /opt/ongrid/certs/ — browsers will warn
      on first visit. Replace tls.crt + tls.key with a real cert and
      'docker compose -f /opt/ongrid/docker-compose.yml restart nginx'.

---------------- bootstrap admin ----------------
email:    admin@example.com
password: 9Xp4hKqf1bL2zRq3Wn7v
>> Record this password NOW. It will not be shown again.
-------------------------------------------------

管理者パスワードを記録

ブートストラップパスワードは 一度だけ 表示されます。/opt/ongrid/.env（mode 0600）にも保存されます。 両方失った場合は reset-admin-password CLI または DB を直接編集してリセット —— 初回起動チェックリスト を参照。

スタックを検証

# All containers should be Up
sudo docker compose -f /opt/ongrid/docker-compose.yml ps

# Manager health
curl -fk https://localhost/healthz

# Tail manager logs
sudo docker compose -f /opt/ongrid/docker-compose.yml logs -f ongrid

# Browse to the UI
open https://<your-host>/   # accept the TLS warning

TLS 証明書の差し替え

自己署名は試用には十分ですが、すべてのブラウザが警告を出します。 本番では本物の証明書（Let's Encrypt、社内 CA など）を /opt/ongrid/certs/ に置きます：

sudo cp fullchain.pem /opt/ongrid/certs/tls.crt
sudo cp privkey.pem   /opt/ongrid/certs/tls.key
sudo chmod 600        /opt/ongrid/certs/tls.key
sudo chmod 644        /opt/ongrid/certs/tls.crt
sudo docker compose -f /opt/ongrid/docker-compose.yml restart nginx

install.sh と upgrade.sh はオペレーター提供の証明書を上書きしません。

ワイルドカードも可

nginx は certs/ の *.crt / *.key を提供します。コンテナが探すファイル名は tls.crt と tls.key のみです。証明書マネージャー（certbot、acme.sh、 cert-manager）が正本を別の場所に置いている場合はシンボリックリンクで構いません。

ファイルの配置

パス	所有者	用途
/opt/ongrid/docker-compose.yml	root	Compose 定義。
/opt/ongrid/.env	root, 0600	シークレット + 調整値。
/opt/ongrid/certs/	root, 0700	tls.crt、tls.key。
/opt/ongrid/edge/	root	Edge バイナリ、アップグレードバンドル（edge-bundle-<arch>-<ver>.tar.gz）、install.sh、apply-pending-upgrade.sh。nginx の /edge/ で読み取り専用提供。
/opt/ongrid/prometheus.yml	root	Prom scrape + remote_write 設定。
/opt/ongrid/grafana/	root	Provisioning yaml（datasource、ダッシュボード）。
/var/lib/ongrid/mysql/	999:999	MySQL データ。バックアップ対象。
/var/lib/ongrid/prometheus/	65534:65534	Prom TSDB。デフォルトで 90 日保持、20GB 上限。
/var/lib/ongrid/loki/	10001:10001	Loki チャンク + インデックス。
/var/lib/ongrid/tempo/	10001:10001	Tempo ブロック。
/var/lib/ongrid/qdrant/	root	ベクトルストア。
/var/lib/ongrid/grafana/	472:472	Grafana 状態（ダッシュボード、ユーザー、SA トークン）。
/var/lib/ongrid/embeddings/	65532:65532	オフライン BGE モデルキャッシュ。
/var/log/ongrid/	混在	Manager ログファイル。

次は

• 初回起動チェックリスト —— モデルプロバイダー、 Prom 保持期間、public URL、タイムゾーン、最初のインシデント。
• Edge インストール —— 最初の edge を登録。
• アップグレード —— upgrade.sh のフロー、 stage-then-swap、.previous ロールバック。
• 環境変数 —— 調整可能な全 ONGRID_* 環境変数。