Contents
Gemma データベースの構成要素とバージョン確認
Gemma は遺伝子発現データを統合・検索できるオープンソースプラットフォームで、PostgreSQL、Elasticsearch、ファイルストレージ の 3 層アーキテクチャが基本です。各コンポーネントのバージョンが揃っていないとマイグレーション時に互換性エラーが頻発するため、本セクションでは公式ドキュメント(2024‑11 更新)に基づく推奨バージョンと、実際に稼働中のバージョンを確認する手順を解説します。
PostgreSQL のバージョン確認
PostgreSQL はメタデータ・実験情報を永続化する中心的なリレーショナル DB です。以下のコマンドでサーバー側とクライアント側双方のバージョンを取得できます。
|
1 2 3 4 5 6 |
# サーバーバージョン(psql 接続後) psql -U gemma_user -h $DB_HOST -c "SELECT version();" # クライアントツールのバージョン psql --version |
目安:公式では PostgreSQL 13.x 系が推奨されています。12 系以下は非対応機能(例: パーティショニング)に注意してください。
Elasticsearch のバージョン確認
検索インデックスを担当する Elasticsearch は、Gemma 2.5.0 以降で 8.x 系 が公式サポートとなります。現在稼働中のバージョンは次のように取得します。
|
1 2 3 |
curl -s http://localhost:9200 | jq '.version.number' # 例)8.9.1 |
チェックリスト
GET /_cat/indices?vが正常に返るか
/_cluster/healthのステータスがgreenであること
ファイルストレージの確認ポイント
バイオロジーデータ(FASTQ、BAM 等)は容量が大きくなるため、NFS 互換ファイルシステムまたは S3 互換オブジェクトストアを使用します。マウントポイントやバケットポリシーが正しく設定されているか、次の点を確認してください。
| 項目 | 確認方法 |
|---|---|
| NFS マウント可否 | showmount -e $NFS_SERVER |
| S3 バケットアクセスポリシー | aws s3api get-bucket-policy --bucket <bucket> |
| 書き込み権限 | touch /path/to/storage/.test && rm /path/to/storage/.test |
公式バックアップ取得手順と暗号化キー管理
信頼性の高いバックアップは、障害復旧だけでなく法規制遵守(例: GDPR)にも不可欠です。本節では pg_dump と Gemma が提供する gemma-export スクリプトを組み合わせた手順に加え、暗号化キーの安全な保管・ローテーション方法を具体的に示します。
1. pg_dump によるデータベースダンプ(AES‑256 暗号化)
|
1 2 3 4 5 |
# 鍵は Vault または AWS KMS から取得し、環境変数 $ENC_KEY に格納済みと想定 pg_dump -U gemma_user -h $DB_HOST -Fc --no-owner --no-privileges \ --compress=9 gemma_db | openssl enc -aes-256-cbc -salt \ -pass env:ENC_KEY -out backup_gemma.dump.enc |
-Fcはカスタム形式で、リストア時にテーブル単位の復元が可能です。- 暗号化キーは 平文で保存しない ことが原則です。以下のように外部シークレット管理ツールから取得します。
|
1 2 3 |
# HashiCorp Vault 例 export ENC_KEY=$(vault kv get -field=key secret/gemma/backup-key) |
2. gemma‑export スクリプトによるメタ情報エクスポート
gemma-export は Gemma ソースツリーに同梱されている CLI ユーティリティです。インストール済みかは次で確認できます。
|
1 2 3 |
which gemma-export && gemma-export --version # 出力例)gemma-export version 2.4.1 |
実際のエクスポート手順は以下の通りです(Docker コンテナ内部から実行する場合も同様)。
|
1 2 3 4 5 |
docker exec -i gemma_app bash -c "\ gemma-export --format json > /tmp/gemma_meta.json && \ openssl enc -aes-256-cbc -salt -pass env:ENC_KEY -out /tmp/gemma_meta.json.enc" docker cp gemma_app:/tmp/gemma_meta.json.enc ./backup/ |
- JSON は API 連携に最適、TSV が必要な場合は
--format tsvを指定してください。 - エクスポートファイルも同様に暗号化し、復号キーはバックアップと別管理します。
3. バックアップの二重保存
| 保存先 | 推奨理由 |
|---|---|
| オンプレミス NAS(エアギャップ) | ネットワーク障害時の保護 |
| クラウドオブジェクトストレージ(例: AWS S3、GCS) | 地理的冗長性とライフサイクル管理 |
保存期間は 最低 90 日、法令で求められる場合は更に長く保持してください。
Docker イメージでのデータ取得・エクスポート
Docker 環境を利用すれば、ホスト側に依存しない再現性の高いバックアップが可能です。ただし イメージタグの公式性 と バージョン管理 が重要です。以下では Docker Hub の公式リポジトリ gemma/gemma を例に、実在確認手順と推奨タグ戦略を示します。
1. イメージの公式性を確認する方法
|
1 2 3 4 |
# Docker Hub 上の gemma リポジトリ情報取得 curl -s https://hub.docker.com/v2/repositories/gemma/gemma/tags?page_size=100 \ | jq '.results[] | .name, .last_updated' | head |
latestタグは 常に最新 ですが、突発的な破壊的変更が入る可能性があります。- 本番環境では バージョンタグ(例: 2.5.0) を使用し、イメージの SHA256 ダイジェストでロックすることを推奨します。
|
1 2 3 4 |
docker pull gemma/gemma:2.5.0 docker inspect --format='{{index .RepoDigests 0}}' gemma/gemma:2.5.0 # 出力例)gemma/gemma@sha256:3a1b... |
2. イメージ取得・プライベートレジストリへのプッシュ
|
1 2 3 4 |
docker pull gemma/gemma:2.5.0 # 公式タグを使用 docker tag gemma/gemma:2.5.0 registry.mycompany.com/gemma:2026.03 docker push registry.mycompany.com/gemma:2026.03 |
registry.mycompany.comは社内プライベートレジストリです。- タグ名に 年と月(YYYY.MM) を入れることで、ロールバック時の可視性が向上します。
3. コンテナ内部で pg_dump と gemma‑export を実行
|
1 2 3 4 5 6 7 8 9 10 11 12 13 |
docker run -d --name gemma_app \ -v gemma_data:/var/lib/gemma \ gemma/gemma:2.5.0 # データベースダンプ(暗号化はホスト側で実施) docker exec gemma_app pg_dump -U gemma_user -Fc gemma_db > ./backup/pg_dump.dump # メタ情報エクスポート(暗号化含む例) docker exec gemma_app bash -c "\ gemma-export --format json | \ openssl enc -aes-256-cbc -salt -pass env:ENC_KEY -out /tmp/gemma_meta.json.enc" docker cp gemma_app:/tmp/gemma_meta.json.enc ./backup/ |
- 必要に応じて
--cpusと--memoryオプションでリソース上限を緩め、ダンプ時間の短縮が期待できます(例:--cpus=4 --memory=8g)。
新環境へのインストール手順:Docker Compose と Conda の両対応
移行先のインフラが コンテナ中心 か 軽量仮想環境 かに応じて、Docker Compose と Conda のどちらでも構築できるようにテンプレートを用意しました。ここでは公式推奨バージョン(PostgreSQL 13、Elasticsearch 8.9、Gemma CLI 2.5.0)に合わせた設定例と、実装上の注意点を示します。
Docker Compose 用設定ファイル(docker‑compose.yml)
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 |
version: "3.8" services: postgres: image: postgres:13-alpine environment: POSTGRES_USER: gemma_user POSTGRES_PASSWORD: ${POSTGRES_PASSWORD} POSTGRES_DB: gemma_db volumes: - pg_data:/var/lib/postgresql/data elasticsearch: image: docker.elastic.co/elasticsearch/elasticsearch:8.9.0 environment: - discovery.type=single-node - ES_JAVA_OPTS=-Xms2g -Xmx2g ulimits: memlock: soft: -1 hard: -1 volumes: - es_data:/usr/share/elasticsearch/data gemma: image: registry.mycompany.com/gemma:2026.03 depends_on: - postgres - elasticsearch ports: - "8080:8080" environment: DB_HOST: postgres DB_PORT: 5432 ES_HOST: elasticsearch ES_PORT: 9200 volumes: - gemma_files:/var/lib/gemma/files volumes: pg_data: es_data: gemma_files: |
.envファイルで機密情報を管理し、CI/CD のシークレットストアと連携させます。elasticsearch:8.9.0は Gemma CLI 2.5.0 がサポートする最新安定版です。
Conda 環境用設定ファイル(environment.yml)
|
1 2 3 4 5 6 7 8 9 10 11 |
name: gemma-env channels: - conda-forge dependencies: - python=3.10 - postgresql=13 - openjdk=11 - pip - pip: - gemma-cli==2.5.0 # PyPI に公開されている公式 CLI パッケージ |
Conda 環境でのサービス起動手順
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 |
conda env create -f environment.yml conda activate gemma-env # PostgreSQL のデータディレクトリを作成 initdb -D $CONDA_PREFIX/var/lib/postgresql/data pg_ctl -D $CONDA_PREFIX/var/lib/postgresql/data -l logfile start # Elasticsearch 起動(バックグラウンドで実行) elasticsearch -d -p ${PWD}/es.pid # Gemma CLI 初期化 gemma-cli init --db-host localhost --db-name gemma_db \ --db-user gemma_user --db-pass $POSTGRES_PASSWORD \ --es-host http://localhost:9200 |
- ディレクトリはすべて Conda 環境内に閉じ込めることで、ホストへの影響を最小化します。
gemma-cli initが成功すると、必要なテーブルとインデックスが自動作成されます。
スキーマバージョン管理・マイグレーションとデータ整合性チェック
Gemma のスキーマは頻繁に拡張されるため、Flyway または Liquibase によるバージョン管理が必須です。ここでは Flyway を例に、設定ファイル・マイグレーション実行手順と、移行後のデータ整合性を自動検証するスクリプト例を示します。
Flyway 設定例(flyway.conf)
|
1 2 3 4 5 6 7 |
flyway.url=jdbc:postgresql://localhost:5432/gemma_db flyway.user=gemma_user flyway.password=${DB_PASSWORD} flyway.locations=filesystem:/opt/flyway/sql flyway.baselineVersion=1.0 flyway.baselineOnMigrate=true |
sqlディレクトリにV2026_03__add_new_table.sqlのような バージョン付スクリプト を配置します。
マイグレーション実行
|
1 2 |
flyway -configFiles=flyway.conf migrate |
- 成功時は標準出力に
Successfully applied X migrationsと表示されます。
整合性チェックの自動化スクリプト(check_integrity.sh)
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 |
#!/usr/bin/env bash set -euo pipefail # 1. テーブル行数比較 echo "=== 行数比較 ===" psql -U gemma_user -d gemma_db -c "\ SELECT 'dataset', COUNT(*) FROM dataset UNION ALL \ SELECT 'expression_data', COUNT(*) FROM expression_data;" > /tmp/count_new.txt # 2. MD5 ハッシュで全テーブル内容を検証(ソート必須) echo "=== MD5 ハッシュ比較 ===" psql -U gemma_user -d gemma_db -c "\ SELECT md5(string_agg(t::text, '')) FROM (SELECT * FROM expression_data ORDER BY id) t;" \ > /tmp/md5_new.txt # 3. DEG 解析結果の差分チェック(例として 5 行だけ比較) gemma-cli deg --experiment EXP001 --output /tmp/deg_new.tsv head -n 5 /tmp/deg_new.tsv > /tmp/deg_head_new.tsv diff /tmp/deg_head_old.tsv /tmp/deg_head_new.tsv && echo "DEG 差分なし" echo "=== 整合性チェック完了 ===" |
- スクリプトは CI パイプライン に組み込むことで、リリースごとの回帰検証が自動化できます。
ダウンタイム削減策・セキュリティ設定・パッチ適用・トラブルシューティング
本章では、本番環境への影響を最小限に抑えるための リードレプリカ と ブルー/グリーンデプロイ、さらに API キーや OAuth の安全な移行手順、2026 年版パッチ適用時の注意点、代表的エラーと対処法を網羅します。
リードレプリカ構築とブルー/グリーンデプロイフロー
- PostgreSQL リードレプリカ作成
bash
pg_basebackup -h primary_host -D /var/lib/postgresql/replica \
-U replicator -P --wal-method=stream
# postgresql.conf に hot_standby = on を追記し、再起動 - ブルー(現行)とグリーン(新バージョン)の同時稼働
Docker Compose でgemma_blueとgemma_greenの二つのサービスを立ち上げ、ヘルスチェックが OK になるまで待機。 - トラフィック切替(例:NGINX の upstream を切り替える)
bash
# Blue → Green 切替コマンド例
curl -XPOST http://nginx/api/switch?to=green
効果:サービス停止時間は数秒以内に抑えられ、ロールバックも即座に可能です。
API キー・OAuth の安全な移行手順
| 手順 | 詳細 |
|---|---|
| 1. 新キー生成 | Gemma 管理画面 /admin/api-keys → 「Create new」→ 即時有効化 |
| 2. 秘密情報の暗号化保管 | HashiCorp Vault の secret/gemma/api-key に保存し、アクセスは token‑auth のみ許可 |
| 3. 旧キー無効化 | 新キーが全クライアントに展開されたことを確認後、旧キーを即座に削除 |
| 4. OAuth クライアント登録 | gemma-cli oauth register --client-id $ID --client-secret $SECRET → 環境変数 OAUTH_CLIENT_ID/SECRET に注入 |
- ネットワーク制限は Docker Compose の
network_mode: bridgeから VPC 内プライベートサブネットへ変更し、セキュリティグループで IP アドレスレンジを限定してください。
2026 年パッチ適用と Elasticsearch 8.x 互換性確認
Gemma CLI 2.5.0 以降は Elasticsearch 8.x が公式サポートされています。パッチ適用手順は次の通りです。
|
1 2 3 4 5 6 7 8 |
# Docker イメージを最新版に更新 docker pull gemma/gemma:2.5.1 docker tag gemma/gemma:2.5.1 registry.mycompany.com/gemma:2026.06 docker push registry.mycompany.com/gemma:2026.06 # コンテナ再起動(ダウンタイムを最小化するために Rolling Update 推奨) docker compose up -d --no-deps --scale gemma=2 gemma |
- 互換性チェック
bash
# Gemma CLI のバージョン確認
gemma-cli version # 必ず 2.5.0 以上
# Elasticsearch インデックスマッピングが 8.x 用に自動変換されたか
curl -s http://localhost:9200/_mapping | jq '.'
よくあるエラーと対処法(FAQ)
| エラー | 原因例 | 推奨対策 |
|---|---|---|
psql: could not connect to server |
DB コンテナ未起動、DB_HOST 誤設定 |
docker compose ps で状態確認 → .env の POSTGRES_PASSWORD 再設定 |
| Elasticsearch インデックス不整合 | バージョン差異、マイグレーション未実施 | gemma-cli reindex --force を実行しインデックス再構築 |
permission denied(pg_dump) |
実行ユーザーにスーパーユーザ権限がない | DB 管理者で GRANT ALL ON DATABASE gemma_db TO gemma_user; を付与 |
| 暗号化キー漏洩疑惑 | 環境変数に平文保存 | 秘密情報は Vault/KMS から取得し、プロセス外部に保持しない |
ベストプラクティス:エラーログはすべて 集中ログ管理システム(例:ELK Stack) に集約し、アラート設定を行うことで再発防止が可能です。
まとめ
| 項目 | 推奨構成・手順 |
|---|---|
| コンポーネントバージョン | PostgreSQL 13、Elasticsearch 8.9、Gemma CLI 2.5.0(Docker イメージは gemma/gemma:2.5.0) |
| バックアップ取得 | pg_dump -Fc + AES‑256 暗号化 (openssl enc) → Vault/KMS で管理する鍵で暗号化、gemma-export によるメタ情報 JSON/TSV エクスポート |
| Docker イメージ運用 | バージョンタグ(例 2.5.0)と SHA256 ダイジェストでロックし、プライベートレジストリへプッシュ |
| 新環境構築 | Docker Compose か Conda のいずれでも再現可能。Elasticsearch は 8.x 系を使用 |
| スキーマ管理 | Flyway(または Liquibase)でバージョン管理、CI パイプラインに check_integrity.sh を組み込み |
| ダウンタイム削減 | リードレプリカ+ブルー/グリーンデプロイで数秒以下の切替が実現可能 |
| セキュリティ・キー管理 | Vault/KMS で暗号化鍵を保管、API キーは Vault シークレットとして保存し CI/CD のみ参照 |
| パッチ適用と互換性 | Gemma CLI 2.5.0+ が Elasticsearch 8.x をサポート。イメージ更新後はロールアウト方式でデプロイ |
| トラブルシューティング | 代表的エラー表を参照し、ログ集約・アラート設定で迅速に復旧 |
上記の手順とベストプラクティスに従うことで、Gemma データベースの 安全なバックアップ取得 → 新環境への移行 → 本番稼働 を計画的かつ最小ダウンタイムで実施できます。公式ドキュメント(https://gemma.msl.ubc.ca/docs/)と Docker Hub のリポジトリ情報を併せて定期的に確認し、バージョンや脆弱性情報の最新状態を保つことが成功への鍵です。