coolify-manager

Coolify Manager

概要

このスキルでは、公式 CLI と API への直接アクセスの両方を通じて、Coolify のデプロイを管理できます。サービスの問題の診断、よくある WordPress の問題の修正、コンテナの管理、セルフホスト型およびクラウドの Coolify インスタンス全体でのデプロイ操作に関するワークフローを提供します。

クイックスタート

前提条件の確認

作業を進める前に、以下を確認してください。

1. ユーザーが Coolify インスタンス（セルフホスト型またはクラウド）にアクセスできること
2. ユーザーが Coolify ダッシュボードの /security/api-tokens から API トークンを取得できること
3. ユーザーが Coolify インスタンスの URL を把握していること

このスキルを使用する場合

ユーザーが以下のような場合に、このスキルを呼び出してください。

• Coolify の名前を挙げた場合
• Coolify でホストされている停止中の WordPress サイトのデバッグが必要な場合
• サービスの正常性、ログ、またはステータスを確認したい場合
• コンテナのターミナルにアクセスする必要がある場合
• デプロイ、サービス、またはアプリケーションを管理したい場合
• Coolify でホストされているサイトで SSL 証明書の問題が発生している場合
• .htaccess または PHP 設定の問題を修正する必要がある場合
• 環境変数または設定を管理したい場合

インストールとセットアップ

ステップ 1：Coolify CLI をインストールする

CLI がまだインストールされていない場合は、同梱のインストールスクリプトを使用してください。

bash scripts/install_coolify_cli.sh

~/.local/bin/coolify にインストールされます。このディレクトリがユーザーの PATH に含まれていることを確認してください。

export PATH="$HOME/.local/bin:$PATH"

永続化するには、この行をユーザーのシェル設定ファイル（~/.bashrc、~/.zshrc など）に追加してください。

ステップ 2：コンテキストを設定する

ユーザーの Coolify インスタンスを追加します。

coolify context add <context-name> <coolify-url> <api-token>

例：

coolify context add production https://coolify.example.com YOUR_API_TOKEN

ステップ 3：接続を確認する

coolify context verify

これにより、認証と接続が成功したことを確認できます。

ヘルスチェック

同梱のヘルスチェックスクリプトを実行します。

bash scripts/check_health.sh

以下が表示されます。

• CLI のバージョン
• 設定済みのコンテキスト
• 接続ステータス
• 利用可能なリソース
• サーバーのステータス

問題の診断

ワークフローの判断ツリー

ユーザーから問題が報告された場合：

1. サービスの可用性に関する問題ですか？

   • サイトが停止している → サービスのステータスを確認する
   • コンテナが応答しない → ログを確認する
   • デプロイに失敗した → デプロイ履歴を確認する

2. WordPress 固有の問題ですか？

   • .htaccess の変更後に 500 エラーが発生した → .htaccess を修正する
   • REST API の警告 → REST API を診断する
   • PHP の制限 → PHP 設定を更新する
   • SSL の問題 → 証明書を確認する

3. パフォーマンスまたは設定に関する問題ですか？

   • 環境変数を変更する必要がある → 環境を管理する
   • スケールする必要がある → リソースを管理する
   • デプロイする必要がある → デプロイを開始する

サービスのステータスを確認する

# List all resources with status
coolify resource list

# Get detailed service info
coolify service get SERVICE_UUID

# Check specific application
coolify app get APP_UUID

ステータスの表示：

• running:healthy - サービスは正常に稼働しています
• running:unhealthy - サービスに問題があります（ログを確認してください）
• stopped - サービスは停止しています
• deploying - デプロイ中です

ログを確認する

# Application logs
coolify app logs APP_UUID

# Get more lines
coolify app logs APP_UUID --lines 500

複数のコンポーネントを持つサービス（データベースを含む WordPress など）の場合は、まずサービスの詳細を取得して、コンポーネントの UUID を特定してください。

coolify service get SERVICE_UUID --format json

次に、JSON 出力からアプリケーション／データベースの UUID を抽出します。

API を直接使用する

CLI で必要な機能が利用できない場合は、API を直接呼び出してください。参照先：references/api_endpoints.md

例 - 詳細なサービス設定を取得する：

curl -H "Authorization: Bearer API_TOKEN" \
  https://coolify-instance.com/api/v1/services/SERVICE_UUID

サービスの管理

起動／停止／再起動

# Services
coolify service start SERVICE_UUID
coolify service stop SERVICE_UUID
coolify service restart SERVICE_UUID

# Applications
coolify app start APP_UUID
coolify app stop APP_UUID
coolify app restart APP_UUID

# Databases
coolify database start DB_UUID
coolify database stop DB_UUID
coolify database restart DB_UUID

アプリケーションをデプロイする

# Deploy by UUID
coolify deploy APP_UUID

# Check deployment status
coolify deploy list APP_UUID

環境変数を管理する

# List env vars
coolify app env list APP_UUID

# Add/update env var
coolify app env set APP_UUID VAR_NAME "value"

# Delete env var
coolify app env delete APP_UUID VAR_NAME

# Restart to apply changes
coolify app restart APP_UUID

WordPress のトラブルシューティング

WordPress 固有の問題については、references/wordpress_fixes.md を参照してください。

WordPress コンテナへのアクセス

Coolify Web Terminal を使用（推奨）：

1. Coolify ダッシュボードに移動します
2. WordPress サービスを開きます
3. サイドバーの「Terminal」をクリックします
4. 「wordpress」コンテナを選択します

Docker を使用（SSH アクセスが可能な場合）：

docker exec -it CONTAINER_NAME bash

WordPress ファイルの場所：/var/www/html/

よくある WordPress の問題

.htaccess の編集後にサイトが停止する

これは、直ちに対処する必要がある重大な問題です。

1. コンテナのターミナルにアクセスします（上記を参照）
2. .htaccess ファイルを確認します。

   cd /var/www/html
   cat .htaccess
   

3. 問題のある行を特定します（通常は最後に追加された行です）
4. 問題のある行を削除します。

   sed -i '$d' /var/www/html/.htaccess
   

5. サービスは直ちに復旧するはずです

PHP 設定の制限

PHP の制限（max_input_vars、アップロード制限など）を増やすには：

正しい構文（= 記号は使用せず、スペースを使用）：

echo "php_value max_input_vars 3000" >> /var/www/html/.htaccess
echo "php_value upload_max_filesize 64M" >> /var/www/html/.htaccess
echo "php_value post_max_size 128M" >> /var/www/html/.htaccess
echo "php_value memory_limit 256M" >> /var/www/html/.htaccess

確認：

tail -5 /var/www/html/.htaccess

REST API の誤検知

サイトは正常に動作しているのに、サイトヘルスで REST API が利用できないと報告される場合：

1. REST API を外部からテストします：

   curl https://site.com/wp-json/
   

2. JSON が返される場合、誤検知です。API は正常に動作しています

3. よくある原因：実際の API ではなく、サイトヘルスのループバックテストがブロックされています

4. .htaccess の HTTP_AUTHORIZATION を確認します：

   grep "HTTP_AUTHORIZATION" /var/www/html/.htaccess
   

   次の内容が含まれている必要があります：

   RewriteRule .* - [E=HTTP_AUTHORIZATION:%{HTTP:Authorization}]
   

WordPress の詳細なトラブルシューティング手順については、references/wordpress_fixes.md をコンテキストに読み込んでください。

SSL 証明書の問題

証明書の状態を確認します：

echo | openssl s_client -servername domain.com -connect domain.com:443 2>/dev/null | openssl x509 -noout -dates -subject -issuer

Coolify は Traefik と Let's Encrypt を使用して SSL を自動化します。証明書は有効期限前に自動更新されます。

証明書が無効な場合：

1. Coolify ダッシュボード → サービス → ドメインを確認します
2. SSL 証明書を再生成します
3. サービス設定の Traefik ラベルを確認します

高度な操作

複数のコンテキストの操作

Coolify インスタンスを切り替えます：

# List contexts
coolify context list

# Switch context
coolify context use staging

# Perform operations
coolify deploy APP_UUID

# Switch back
coolify context use production

JSON 出力による一括操作

jq などのツールで --format json を使用します：

# Get all unhealthy services
coolify resource list --format json | jq '.[] | select(.status | contains("unhealthy"))'

# Get all running applications
coolify resource list --format json | jq '.[] | select(.type=="application" and .status=="running")'

# Extract service UUIDs
coolify service list --format json | jq -r '.[].uuid'

サーバー管理

# List servers with IPs/ports
coolify server list -s

# Validate server connection
coolify server validate SERVER_UUID

# Get server domains
coolify server domains SERVER_UUID

バックアップと復旧

# List databases
coolify database list

# Backup database
coolify database backup DB_UUID

# List backups
coolify database backups DB_UUID

参考資料

このスキルには、包括的な参考資料が含まれています：

CLI コマンドのリファレンス

詳細な CLI コマンド構文、フラグ、例が必要な場合は、references/cli_commands.md を読み込んでください。

API エンドポイントのリファレンス

API を直接呼び出す場合、または CLI が必要な操作に対応していない場合は、references/api_endpoints.md を読み込んでください。

WordPress 修正のリファレンス

.htaccess の問題、PHP 設定、REST API の問題、SSL 証明書など、WordPress 固有の問題をトラブルシューティングする場合は、references/wordpress_fixes.md を読み込んでください。

よくあるパターン

パターン：サービスが停止している

1. 状態を確認します：coolify resource list
2. 詳細を取得します：coolify service get UUID
3. ログを確認します：coolify app logs APP_UUID
4. ログから問題を特定します
5. 修正します（再起動、設定の更新、ファイルの修正）
6. 確認します：coolify resource list

パターン：WordPress サイトの問題

1. コンテナのターミナルにアクセスします（Coolify ダッシュボードから）
2. /var/www/html に移動します
3. .htaccess の構文エラーを確認します
4. REST API をテストします：curl https://site.com/wp-json/
5. 必要に応じて PHP 設定を確認します
6. 変更を加えた場合はサービスを再起動します

パターン：デプロイの問題

1. 最近のデプロイを一覧表示します：coolify deploy list APP_UUID
2. デプロイの詳細を取得します：coolify deploy get DEPLOY_UUID
3. アプリケーションログを確認します：coolify app logs APP_UUID
4. 特定した問題を修正します（環境変数、設定、コード）
5. 新しいデプロイを開始します：coolify deploy APP_UUID

このスキルのトラブルシューティング

CLI が見つからない

~/.local/bin が PATH に含まれていることを確認します：

echo $PATH | grep ".local/bin"

見つからない場合：

export PATH="$HOME/.local/bin:$PATH"

シェル設定ファイルに追加して、永続化します。

接続の失敗

1. API トークンが有効であることを確認します（Coolify ダッシュボードで確認）
2. Coolify インスタンスの URL が正しいことを確認します
3. 手動で接続をテストします：

   curl -H "Authorization: Bearer TOKEN" https://instance.com/api/v1/version
   

4. 必要に応じてコンテキストを再設定します

権限の問題

API トークンに必要な権限があることを確認します：

• 状態／ログの読み取りアクセス
• デプロイ／再起動の書き込みアクセス
• デプロイ開始のデプロイアクセス

Coolify ダッシュボードの /security/api-tokens でトークンの権限を確認します。