Documentation Index
Fetch the complete documentation index at: https://docs.jitera.ai/llms.txt
Use this file to discover all available pages before exploring further.
このガイドでは、kubeadm、k3s、RKE2 などのディストリビューションを含むセルフマネージド Kubernetes クラスターに Jitera Self-Hosted をデプロイする手順を説明します。
このガイドの例では、以下のサンプル値を使用しています。実際の値に置き換えてください:
- Helmリリース名 / ネームスペース:
jitera(つまりhelm install jitera ./charts/jitera --namespace jitera)— Kubernetesリソース名はこれがプレフィックスとして付与されます(例:jitera-automation-rails、jitera-ultron)
- MinIOバケット名:
jitera-default、jitera-public、jitera-export、jitera-ultron
- ドメイン:
jitera.yourdomain.com
- MinIOドメイン:
minio.example.com、minio-console.example.com
- シークレット名:
jitera-registry(イメージプルシークレット)、jitera-tls(TLS証明書)
前提条件チェックリスト
まずデプロイ要件のチェックリストを完了してから、以下のオンプレミス固有の項目を確認してください:
このガイドに記載されているサードパーティツールの手順(MetalLB、cert-manager、Longhorn、Rook-Ceph)は例として提供されています。最新の手順については、各ツールの公式ドキュメントを参照してください:
インフラストラクチャ要件
Kubernetes クラスター
| 要件 | 最小値 | 推奨 |
|---|
| ノード数 | 3 | 5+ |
| ノードあたりの CPU | 4 コア | 8+ コア |
| ノードあたりのメモリ | 16 GB | 32+ GB |
| ノードあたりのストレージ | 100 GB SSD | 200+ GB NVMe |
ネットワーク要件
| 要件 | 仕様 |
|---|
| Pod CIDR | /16(65,536 IP) |
| Service CIDR | /16 |
| ロードバランサー | MetalLB またはハードウェア |
| Ingress | NGINX または Traefik |
ストレージ要件
| コンポーネント | サイズ | タイプ |
|---|
| PostgreSQL | 100 GB | SSD |
| MongoDB | 100 GB | SSD |
| Redis | 20 GB | SSD |
| オブジェクトストレージ | 500 GB+ | HDD または SSD |
ストレージプロビジョナーのセットアップ
オプション 1: Local Path Provisioner
開発環境や小規模デプロイメント向け:
# local-path-provisioner をインストール
kubectl apply -f https://raw.githubusercontent.com/rancher/local-path-provisioner/master/deploy/local-path-storage.yaml
# デフォルトのストレージクラスに設定
kubectl patch storageclass local-path -p '{"metadata": {"annotations":{"storageclass.kubernetes.io/is-default-class":"true"}}}'
# 確認
kubectl get storageclass
オプション 2: Longhorn
レプリケーション付きの本番環境向け:
# Longhorn をインストール
helm repo add longhorn https://charts.longhorn.io
helm repo update
helm install longhorn longhorn/longhorn \
--namespace longhorn-system \
--create-namespace \
--set defaultSettings.defaultDataPath="/var/lib/longhorn"
# デフォルトのストレージクラスに設定
kubectl patch storageclass longhorn -p '{"metadata": {"annotations":{"storageclass.kubernetes.io/is-default-class":"true"}}}'
オプション 3: Rook-Ceph
大規模分散ストレージ向け:
# Rook リポジトリをクローン
git clone --single-branch --branch release-1.13 https://github.com/rook/rook.git
cd rook/deploy/examples
# Rook オペレーターをインストール
kubectl create -f crds.yaml -f common.yaml -f operator.yaml
# Ceph クラスターを作成
kubectl create -f cluster.yaml
# ストレージクラスを作成
kubectl create -f csi/rbd/storageclass.yaml
# MetalLB をインストール
kubectl apply -f https://raw.githubusercontent.com/metallb/metallb/v0.14.5/config/manifests/metallb-native.yaml
# Pod の準備を待機
kubectl wait --namespace metallb-system \
--for=condition=ready pod \
--selector=app=metallb \
--timeout=90s
IP アドレスプールの設定
# metallb-config.yaml
apiVersion: metallb.io/v1beta1
kind: IPAddressPool
metadata:
name: default-pool
namespace: metallb-system
spec:
addresses:
- 192.168.1.240-192.168.1.250 # ネットワークに合わせて調整してください
---
apiVersion: metallb.io/v1beta1
kind: L2Advertisement
metadata:
name: default
namespace: metallb-system
spec:
ipAddressPools:
- default-pool
kubectl apply -f metallb-config.yaml
TLS 証明書のオプション
オプション 1: cert-manager と Let’s Encrypt
# cert-manager をインストール
helm repo add jetstack https://charts.jetstack.io
helm repo update
helm install cert-manager jetstack/cert-manager \
--namespace cert-manager \
--create-namespace \
--set crds.enabled=true
# ClusterIssuer を作成
cat <<EOF | kubectl apply -f -
apiVersion: cert-manager.io/v1
kind: ClusterIssuer
metadata:
name: letsencrypt-prod
spec:
acme:
server: https://acme-v02.api.letsencrypt.org/directory
email: admin@yourdomain.com
privateKeySecretRef:
name: letsencrypt-prod
solvers:
- http01:
ingress:
class: nginx
EOF
オプション 2: 自己署名証明書
# 自己署名証明書を生成
openssl req -x509 -nodes -days 365 -newkey rsa:2048 \
-keyout tls.key \
-out tls.crt \
-subj "/CN=jitera.yourdomain.com"
# Kubernetes シークレットを作成
kubectl create secret tls jitera-tls \
--namespace jitera \
--cert=tls.crt \
--key=tls.key
オプション 3: 既存の証明書
# 既存の証明書ファイルからシークレットを作成
kubectl create secret tls jitera-tls \
--namespace jitera \
--cert=/path/to/fullchain.pem \
--key=/path/to/privkey.pem
インストール手順
ステップ 1: Ingress Controller のインストール
# NGINX Ingress Controller をインストール
helm repo add ingress-nginx https://kubernetes.github.io/ingress-nginx
helm repo update
helm install ingress-nginx ingress-nginx/ingress-nginx \
--namespace ingress-nginx \
--create-namespace
# 外部 IP が割り当てられていることを確認(MetalLB 経由)
kubectl get svc -n ingress-nginx ingress-nginx-controller
ステップ 2: Namespace とシークレットの作成
# Namespace を作成
kubectl create namespace jitera
# レジストリシークレットを作成
kubectl create secret docker-registry jitera-registry \
--namespace jitera \
--docker-server=registry.jitera.com \
--docker-username="your-username" \
--docker-password="your-password"
ステップ 3: MinIO(オブジェクトストレージ)のデプロイ
Jiteraは、ファイルアップロード、生成されたコードアーティファクト、プロジェクトエクスポートのためにオブジェクトストレージを必要とします。オンプレミスデプロイメントでは、MinIOがS3互換ストレージを提供します。バケット要件とCORSの詳細についてはオブジェクトストレージ設定を、CORS設定手順についてはMinIO CORSドキュメントを参照してください。
クラスター内MinIO
組み込みのMinIOデプロイメントを有効にします:
minio:
enabled: true
mode: distributed # または standalone
replicas: 4 # 分散モードの場合
persistence:
enabled: true
size: 10Gi
resources:
requests:
memory: "512Mi"
cpu: "250m"
limits:
memory: "2Gi"
cpu: "1000m"
storage:
provider: Minio
secret:
minio:
AWS_ACCESS_KEY_ID: "<MINIO_ACCESS_KEY>"
AWS_SECRET_ACCESS_KEY: "<MINIO_SECRET_KEY>"
AWS_REGION: "ap-northeast-1"
AWS_BUCKET: "jitera-default"
AWS_PUBLIC_BUCKET: "jitera-public"
AWS_EXPORT_PROJECT_BUCKET: "jitera-export"
AWS_ULTRON_BUCKET: "jitera-ultron"
S3_FORCE_PATH_STYLE: "true"
ingress:
minio:
enabled: true
domainName: minio.example.com
console:
enabled: true
domainName: minio-console.example.com
認証情報の生成:
# アクセスキーの生成
pwgen 20 1
# シークレットキーの生成
pwgen 40 1
外部MinIO
既存のMinIOデプロイメントを使用する場合:
minio:
enabled: false
storage:
provider: Minio
secret:
minio:
AWS_ACCESS_KEY_ID: "<MINIO_ACCESS_KEY>"
AWS_SECRET_ACCESS_KEY: "<MINIO_SECRET_KEY>"
AWS_REGION: "ap-northeast-1"
AWS_BUCKET: "jitera-default"
AWS_PUBLIC_BUCKET: "jitera-public"
AWS_EXPORT_PROJECT_BUCKET: "jitera-export"
AWS_ULTRON_BUCKET: "jitera-ultron"
S3_FORCE_PATH_STYLE: "true"
# 外部MinIOエンドポイントの設定
ultron:
env:
S3_ENDPOINT: "https://minio.external.com"
MinIOを使用する場合、互換性のためにS3_FORCE_PATH_STYLEを"true"に設定する必要があります。
組み込みのMinIOデプロイメントを使用する場合、Helmチャートが必要なバケットと認証情報を自動的に作成します。外部MinIOの場合は、アクセスキーとシークレットキーに4つのバケットすべてに対する読み書き権限が必要です — s3:GetObject、s3:PutObject、s3:DeleteObject、s3:ListBucket権限を持つポリシーを作成し、アクセスキーにアタッチしてください。
詳細なインストールオプションについてはMinIOドキュメントを参照してください。
ステップ 4: メールの設定
オンプレミスデプロイメントでは、外部SMTPプロバイダー(例:SendGrid — SMTPサービスを参照)または組み込みのPostfixメールサーバーを使用できます。
外部SMTP
mailer:
smtp_settings:
address: smtp.yourdomain.com # SMTPサーバーアドレス
user_name: "<SMTP_USERNAME>"
password: "<SMTP_PASSWORD>"
default_from_email: "noreply@yourdomain.com"
組み込みメールサーバー(Postfix)
エアギャップ環境やテスト用に、Jiteraには組み込みのPostfixメールサーバーが含まれています。
組み込みメールサーバーはテストとエアギャップデプロイメント用です。本番環境では、配信性の向上のためにマネージドメールサービスを使用してください。
smtp:
enabled: true
replicaCount: 1
config:
hostname: mail.yourdomain.com
allowedNetworks: "10.0.0.0/8,172.16.0.0/12,192.168.0.0/16"
messageSizeLimit: "52428800"
auth:
enabled: false
resources:
requests:
memory: "256Mi"
cpu: "100m"
limits:
memory: "512Mi"
cpu: "500m"
mailer:
smtp_settings:
address: jitera-smtp.jitera.svc.cluster.local
user_name: ""
password: ""
default_from_email: "noreply@yourdomain.com"
組み込みサーバーでSMTP認証を有効にする場合:
smtp:
enabled: true
auth:
enabled: true
users:
- username: jitera
password: "<SMTP_PASSWORD>"
mailer:
smtp_settings:
address: jitera-smtp.jitera.svc.cluster.local
user_name: jitera
password: "<SMTP_PASSWORD>"
default_from_email: "noreply@yourdomain.com"
ステップ 5: Values ファイルの作成
# values-onprem.yaml
global:
domain: jitera.yourdomain.com
imageRegistry: registry.jitera.com
imagePullSecrets:
- name: jitera-registry
# シークレット
secrets:
jiteraRegistry:
username: "your-registry-username"
password: "your-registry-password"
github:
clientId: "your-github-client-id"
clientSecret: "your-github-client-secret"
openai:
apiKey: "your-openai-api-key"
# ストレージ - MinIO(S3 互換)
storage:
type: s3
s3:
endpoint: "http://minio.minio:9000"
bucket: jitera
accessKeyId: "minioadmin"
secretAccessKey: "minioadmin123"
region: "ap-northeast-1"
forcePathStyle: true
# メール - 汎用 SMTP
email:
smtp:
host: smtp.yourdomain.com
port: 587
username: "smtp-username"
password: "smtp-password"
fromAddress: "noreply@yourdomain.com"
fromName: "Jitera"
tls: true
# Ingress - cert-manager 付き NGINX
ingress:
enabled: true
className: nginx
annotations:
cert-manager.io/cluster-issuer: letsencrypt-prod
nginx.ingress.kubernetes.io/proxy-body-size: "100m"
tls:
enabled: true
secretName: jitera-tls
# 自己署名または既存の証明書の場合(cert-manager なし):
# ingress:
# enabled: true
# className: nginx
# annotations:
# nginx.ingress.kubernetes.io/proxy-body-size: "100m"
# tls:
# enabled: true
# secretName: jitera-tls # 事前に作成したシークレット
# データベース - クラスター内
postgresql:
enabled: true
primary:
persistence:
enabled: true
size: 100Gi
storageClass: "" # デフォルトのストレージクラスを使用
mongodb:
enabled: true
persistence:
enabled: true
size: 100Gi
storageClass: ""
redis:
enabled: true
master:
persistence:
enabled: true
size: 20Gi
storageClass: ""
# リソース割り当て
api:
replicas: 2
resources:
requests:
cpu: "500m"
memory: "1Gi"
limits:
cpu: "2"
memory: "4Gi"
web:
replicas: 2
resources:
requests:
cpu: "200m"
memory: "512Mi"
limits:
cpu: "1"
memory: "2Gi"
worker:
replicas: 2
resources:
requests:
cpu: "500m"
memory: "1Gi"
limits:
cpu: "2"
memory: "4Gi"
# ノードアフィニティ(オプション)
nodeSelector: {}
# Tolerations(オプション)
tolerations: []
ステップ 6: Jitera のインストール
# Jitera Helmチャートzipを展開
unzip jitera-helm-chart.zip
# Jiteraをインストール
helm install jitera ./charts/jitera \
--namespace jitera \
--values values-onprem.yaml \
--wait \
--timeout 15m
エアギャップ環境でのデプロイ
インターネットアクセスがない環境では、以下の追加手順に従ってください。
ステップ 1: コンテナイメージのミラーリング
インターネットアクセスが可能なマシンで:
# ミラーリングするイメージのリスト
IMAGES=(
"registry.jitera.com/jitera/api:latest"
"registry.jitera.com/jitera/web:latest"
"registry.jitera.com/jitera/worker:latest"
"registry.jitera.com/jitera/automation:latest"
"postgres:15"
"mongo:6"
"redis:7"
"minio/minio:latest"
)
# イメージをプルして保存
for img in "${IMAGES[@]}"; do
docker pull $img
done
docker save ${IMAGES[@]} -o jitera-images.tar
ステップ 2: プライベートレジストリへのイメージのロード
# イメージをロード
docker load -i jitera-images.tar
# プライベートレジストリにタグ付けしてプッシュ
PRIVATE_REGISTRY="registry.internal.local"
for img in "${IMAGES[@]}"; do
new_tag="${PRIVATE_REGISTRY}/${img#*/}"
docker tag $img $new_tag
docker push $new_tag
done
ステップ 3: エアギャップ用 Values の更新
# values-airgapped.yaml
global:
imageRegistry: registry.internal.local
# プライベートレジストリに認証が必要な場合
imagePullSecrets:
- name: private-registry
# イメージリポジトリの上書き
postgresql:
image:
registry: registry.internal.local
repository: library/postgres
tag: "15"
mongodb:
image:
registry: registry.internal.local
repository: library/mongo
tag: "6"
redis:
image:
registry: registry.internal.local
repository: library/redis
tag: "7"
ステップ 4: オフラインでの Helm チャートのインストール
# Jitera Helmチャートzipをエアギャップ環境に転送
# 展開してローカルチャートからインストール
unzip jitera-helm-chart.zip
helm install jitera ./charts/jitera \
--namespace jitera \
--values values-airgapped.yaml
インストール後の確認
ステップ 1: Pod の確認
kubectl get pods -n jitera
ステップ 2: DNS の設定
両方のホスト名(メインドメインとチャットドメイン)をロードバランサーIPに向けるDNSレコードを作成します。ホスト名の詳細についてはデプロイ要件を参照してください。
app.example.com A <load-balancer-ip>
chat.example.com A <load-balancer-ip>
ステップ 3: アプリケーションの確認
# ヘルスエンドポイントをテスト
curl -k https://jitera.yourdomain.com/api/health
# アプリケーションにアクセス
# https://jitera.yourdomain.com にアクセスしてください
トラブルシューティング
ストレージプロビジョナーの問題
# PVC のステータスを確認
kubectl get pvc -n jitera
# Pending の場合、ストレージクラスを確認
kubectl describe pvc <pvc-name> -n jitera
# ストレージプロビジョナーのログを確認
kubectl logs -n longhorn-system -l app=longhorn-manager
MinIOオブジェクトストレージの問題
# 設定されているストレージプロバイダーを確認
kubectl get configmap jitera-ultron -n jitera -o jsonpath='{.data.STORAGE_DISK}'
# MinIO Pod のステータスを確認
kubectl get pods -n jitera -l app=minio
# MinIO のログを確認
kubectl logs -n jitera -l app=minio --tail=100
# よくある問題:
# - ストレージ不足(PVC を確認)
# - 分散モードに必要なレプリカ数の不足(最低 4)
# MinIO コンソールをポートフォワードして確認
kubectl port-forward svc/jitera-minio-console 9001:9001 -n jitera
# http://localhost:9001 でアクセス
# minio.rootUser / minio.rootPassword で設定した認証情報でログイン
# mc クライアントで MinIO アクセスを確認
kubectl exec -it deploy/jitera-minio -n jitera -- \
mc ls local/jitera-default/
# Automation シークレット(secrets.yml)のストレージ設定を確認
kubectl get secret jitera-automation -n jitera \
-o jsonpath='{.data.secrets\.yml}' | base64 -d | grep -A 5 'storage_service\|aws:'
# Pod から MinIO への接続をテスト
kubectl exec -it deploy/jitera-automation-rails -n jitera -- \
curl -I http://jitera-minio:9000/minio/health/live
ロードバランサーの問題
# MetalLB speaker のログを確認
kubectl logs -n metallb-system -l component=speaker
# IP プールの設定を確認
kubectl get ipaddresspool -n metallb-system
# サービスの外部 IP を確認
kubectl get svc -n ingress-nginx
証明書の問題
# 証明書のステータスを確認
kubectl get certificate -n jitera
# cert-manager のログを確認
kubectl logs -n cert-manager -l app=cert-manager
# 自己署名証明書の問題の場合
openssl s_client -connect jitera.yourdomain.com:443 -servername jitera.yourdomain.com
ネットワーク接続
# 内部 DNS をテスト
kubectl run -it --rm debug --image=busybox --restart=Never -- nslookup jitera-api.jitera.svc.cluster.local
# 外部接続をテスト
kubectl run -it --rm debug --image=curlimages/curl --restart=Never -- curl -I https://api.github.com
データベース接続
# PostgreSQL をテスト
kubectl run -it --rm psql --image=postgres:15 --restart=Never -- \
psql -h jitera-postgresql -U jitera -d jitera
# MongoDB をテスト
kubectl run -it --rm mongo --image=mongo:6 --restart=Never -- \
mongosh "mongodb://jitera-mongodb:27017/jitera"
# Redis をテスト
kubectl run -it --rm redis --image=redis:7 --restart=Never -- \
redis-cli -h jitera-redis-master ping
メールのテスト
# Rails コンソールにアクセス
kubectl exec -it deploy/jitera-automation-rails -n jitera -- rails console
# テストメールの送信
ActionMailer::Base.mail(
from: 'noreply@yourdomain.com',
to: 'test@example.com',
subject: 'Test Email',
body: 'This is a test email from Jitera.'
).deliver_now
# 環境変数の確認
kubectl exec -it deploy/jitera-automation-rails -n jitera -- \
env | grep -i smtp
# メールエラーの automation ログ確認
kubectl logs deploy/jitera-automation-rails -n jitera | grep -i mail
# 組み込み SMTP ログの確認
kubectl logs deploy/jitera-smtp -n jitera
メール接続拒否
# SMTP サーバーへの到達性を確認
kubectl exec -it deploy/jitera-automation-rails -n jitera -- \
telnet smtp.example.com 587
# ファイアウォールで送信ポート 587(または 465、25)が許可されていることを確認
メール認証失敗
- 認証情報が正しいことを確認します
- SMTP ユーザー名の形式が正しいことを確認します(例:SendGrid の場合は
apikey)
# シークレット値の確認
kubectl get secret jitera-mailer -n jitera -o yaml
メールが配信されない
- 迷惑メール/ジャンクフォルダを確認します
- ドメインの SPF/DKIM レコードを確認します
- メールプロバイダーでドメインが検証済みであることを確認します
- メールプロバイダーのログ/ダッシュボードでバウンスを確認します
組み込み SMTP が送信しない
# Postfix の状態確認
kubectl exec -it deploy/jitera-smtp -n jitera -- postfix status
# メールキューの確認
kubectl exec -it deploy/jitera-smtp -n jitera -- mailq
# キューの強制フラッシュ
kubectl exec -it deploy/jitera-smtp -n jitera -- postfix flush
関連ドキュメント