bruvtools 🚀

bruvtools 🚀

プライベートなアプリプラットフォーム ― どこでも、どんな言語でも、単一の CLI でマイクロサービスをデプロイ

同じシンプルなコマンドで、Node.js、Go、Python、Java、PHP、Ruby、またはコンテナ化可能なアプリケーションを CapRover、AWS、GCP、Kubernetes にデプロイできます。ベンダーロックインはありません。

🎯 bruvtools とは？

bruvtools は、あらゆるクラウドサーバーをプライベートなアプリプラットフォームに変えます。自分専用の Heroku、Vercel、Railway を持つようなものです。CapRover と組み合わせると、次の機能を利用できます。

機能	説明
✅ プッシュしてデプロイ	bruvtools deploy my-app を実行すれば、すぐに公開されます
✅ SSL 証明書を自動取得	HTTPS が自動的に有効になります
✅ あらゆる言語に対応	Node.js、Python、Go、Java、PHP、Ruby、Docker
✅ ダウンタイムなしのデプロイ	ローリングアップデートを標準搭載
✅ 自動スケーリング	必要に応じてアプリをスケールアップ／ダウンできます
✅ プライベートで安全	自分のサーバー、自分のルール
✅ コスト効率に優れる	月額 5 ドル。他のプラットフォームの 25 ドル以上と比べてお得です

🚀 クイックスタート：5 分でプライベートプラットフォームを構築

ステップ 1：CapRover サーバーを作成する（2 分）

最も簡単な始め方は、DigitalOcean のワンクリック CapRover デプロイを利用することです。

利用できる内容：

• ✅ CapRover がプリインストールされた月額 5 ドルのサーバー
• ✅ DigitalOcean の新規ユーザー向け100 ドル分の無料クレジット（2 か月無料！）
• ✅ Docker とファイアウォールを自動設定
• ✅ 数分でデプロイ可能

**別のセットアップ方法：**任意のクラウドプロバイダーに手動でインストールする場合は、CapRover 入門ガイドに従ってください。

ステップ 2：bruvtools をインストールする（30 秒）

npm install -g bruvtools
bruvtools --version  # Should show: 0.2.16

ステップ 3：設定してデプロイする（2 分）

# Clone and test the working example
git clone https://github.com/fcavalcantirj/bruvtools.git
cd bruvtools/examples/hello-world

# Setup bruvtools (one time)
bruvtools init
# This creates:
# - bruvtools.yml (configuration: machine names, domains, projects)
# - .env (secrets: passwords, API keys)
# ⚠️  IMPORTANT: Never commit bruvtools.yml or .env to version control!

# Deploy with smart auto-creation and collision detection
bruvtools deploy my-app
# ✅ Checks if app exists
# ✅ Auto-creates app if needed  
# ✅ Handles name collisions (my-app-1, my-app-2, etc.)
# ✅ Deploys with clear step-by-step progress
# ✅ Your app is live with HTTPS!

🎯 これで完了です！ プライベートなアプリプラットフォームを利用できます。アプリは自動 SSL によって https://my-app.yourdomain.com で公開されています。

🔌 MCP 連携（Cursor.com）— 革新的な開発体験

Model Context Protocol（MCP）に対応することで、革新的な開発体験を実現できます。エディターを離れることなく、Cursor.com から直接デプロイできます。

機能	説明
📋 すべてのアプリを一覧表示	IDE 内からインフラ全体を確認できます
📊 ログをリアルタイムで取得	ウィンドウを切り替えずにデバッグできます
🚀 AI の支援を受けてデプロイ	Claude に「これを本番環境にデプロイして」と頼むだけです
📈 ステータスをリアルタイムで監視	アプリのヘルス状態、メトリクス、スケーリングをエディターから確認できます
🔄 即座にロールバック	「前のバージョンにロールバックして」と頼めば完了です
🎯 スマートな提案	AI がコードに基づいて最適化を提案します

🤯 その体験：

You: "Deploy this Node.js app to my-api-v2"
Claude: ✅ Deploying to CapRover...
        ✅ App created with collision detection  
        ✅ Building Docker image...
        ✅ Live at https://my-api-v2.yourdomain.com
        ✅ SSL certificate auto-configured
        
You: "Show me the logs"
Claude: [Real-time logs streaming in your editor]

You: "Scale this to 3 replicas"  
Claude: ✅ Scaled to 3 replicas, load balanced automatically

これが開発の未来です。インフラを実際にデプロイして管理できる AI ペアプログラマーです。コンテキストの切り替えも、別のターミナルも、デプロイ用ダッシュボードも必要ありません。コードを書いて、頼めば、すぐに公開されます。

セットアップ完了後に Claude が応答する実例を以下でご覧ください。

🔌 Cursor.com 向け MCP セットアップ（5 分）

オプション 1：自動セットアップ（推奨）

最も簡単にセットアップするには、bruvtools リポジトリ内から自動セットアップスクリプトを実行します。

# Clone the repository to get the setup script
git clone https://github.com/fcavalcantirj/bruvtools.git
cd bruvtools

# Run the automated MCP setup
chmod +x setup-mcp.sh
./setup-mcp.sh

# Follow the prompts for global or project-specific installation

**注：**セットアップスクリプトは、同梱の mcp-server.js ファイルを使用するため、bruvtools リポジトリのディレクトリ内から実行する必要があります。

オプション 2：手動セットアップ

ステップ 1：bruvtools MCP サーバーをインストールする

# Install bruvtools globally (if not already installed)
npm install -g bruvtools

# Verify MCP server is available
bruvtools --version  # Should show: 0.2.16

ステップ 2：Cursor.com の MCP 設定を構成する

1. Cursor.com の設定を開く：

   • Cmd/Ctrl + , を押して設定を開きます
   • 「MCP」を検索するか、Extensions → Model Context Protocol に移動します

2. bruvtools MCP サーバーを追加する：

   {
     "mcpServers": {
       "bruvtools": {
         "command": "bruvtools",
         "args": ["mcp"],
         "env": {
           "CAPROVER_PASSWORD": "your-caprover-password",
           "CAPROVER_DOMAIN": "your-domain.com",
           "CAPROVER_MACHINE": "your-machine-name"
         }
       }
     }
   }
   

3. 代替方法：ローカル設定を使用する： プロジェクトに bruvtools.yml ファイルと .env ファイルがある場合：

   {
     "mcpServers": {
       "bruvtools": {
         "command": "bruvtools",
         "args": ["mcp"],
         "cwd": "${workspaceFolder}"
       }
     }
   }
   

ステップ 3：Cursor.com を再起動して連携をテストする

Cursor.com で任意のプロジェクトを開き、Claude で次のコマンドを試してください：

You: "List all my deployed apps"
Claude: [Shows your CapRover apps with URLs and status]

You: "Deploy this project as my-new-app"
Claude: [Deploys your current project to CapRover]

🎯 セットアップが成功すると表示される内容：

MCP 連携を通じて、Claude がデプロイ済みのサービスを表示する例

🎯 強化された開発者エクスペリエンス（v0.2.16）

✅ デプロイ後のヘルスチェック

bruvtools deploy my-app
# ✅ Step 1: Creating app...
# ✅ Step 2: Packaging...  
# ✅ Step 3: Deploying...
# ✅ Step 4: Enabling SSL...
# 🔍 Step 5: Verifying deployment health...
#    ✅ Instance count: 1
#    ✅ App is responding correctly!
# 🎉 Deployment completed successfully!

🔧 よくある問題の自動修正

• インスタンス数 = 0：インスタンス数を自動的に 1 にスケールします
• ポートの不一致：server.js と Dockerfile のポート競合を検出します
• SSL の問題：証明書の問題に関する明確なガイダンスを提供します
• コンテナのクラッシュ：デバッグ手順とよくある解決策を表示します

🔐 インテリジェントな環境変数の処理

🚨 大きな環境変数の検出と自動分割 ⚠️ 実験的

bruvtools は、環境変数がプラットフォームの制限を超えた場合に検出し、スマートな解決策を提案できます（現在は実験的機能です）：

bruvtools init
# 🔍 Analyzing environment variables...
# ⚠️  Large environment variable detected: JWT_TOKEN (1083 characters)
# 💡 CapRover has ~1000 character limits on environment variables

🔄 トークンの手動再構成 ✅ 動作確認済み

次のパターンを使用して、分割された環境変数を手動で実装できます：

// Universal function (manually add to your project)
function getEnvVar(varName) {
  // First try to get the variable directly
  if (process.env[varName]) {
    return process.env[varName];
  }
  
  // If not found, try to reconstruct from split parts
  let reconstructed = '';
  let partIndex = 1;
  
  while (true) {
    const partName = `${varName}_${partIndex}`;
    const part = process.env[partName];
    
    if (part) {
      reconstructed += part;
      partIndex++;
    } else {
      break;
    }
  }
  
  return reconstructed || undefined;
}

// Use in your app
const JWT_TOKEN = getEnvVar('JWT_TOKEN'); // Works with both single and split tokens!

🔧 設定ファイル

bruvtools では、設定とシークレットを明確に分離しています：

📄 bruvtools.yml - 設定（シークレット以外）

default_provider: caprover
providers:
  caprover: 
    machine: your-caprover-machine-name
    domain: your-domain.com
projects:
  my-app:
    provider: caprover
    port: 80

🔐 .env - シークレットのみ

# CapRover Authentication
CAPROVER_PASSWORD=your-caprover-password

# Optional: App secrets
DATABASE_URL=postgresql://user:pass@host:port/db
API_KEY=your-api-key

⚠️ セキュリティ：両方のファイルは自動的に .gitignore に追加されます。バージョン管理に絶対にコミットしないでください。

🏗️ CapRover のセットアップ詳細

前提条件

• ドメイン名（$2/年）：ワイルドカード DNS（*.yourdomain.com）用
• パブリック IP アドレスを持つサーバー（$5/月）：DigitalOcean、Vultr、Linode など
• Docker のインストール：ワンクリックデプロイに含まれています

DNS の設定

DNS にワイルドカード A レコードを設定します：

• タイプ：A レコード
• ホスト：*.captain（または *.apps、*.dev など）
• 参照先：サーバーの IP アドレス
• TTL：300（またはデフォルト）

サーバーの要件

• 最小構成：1GB RAM、CPU コア 1 個
• 推奨構成：大規模なアプリのビルドには 2GB RAM
• OS：Ubuntu 22.04 以降（テスト済み、推奨）
• Docker：バージョン 25.x 以降（ワンクリックで自動インストール）

📋 よく使うコマンド

# Interactive setup (one time)
bruvtools init

# View all deployed apps/services
bruvtools services     # Show all deployed apps with URLs
bruvtools apps         # Same as services (alias)
bruvtools deployed     # Same as services (alias)  
bruvtools dashboard    # Same as services (alias)

# Deploy and manage apps
bruvtools deploy <app-name>    # Deploy with smart auto-creation
bruvtools create <app-name>    # Create app manually (optional)
bruvtools status <app-name>    # Check app status
bruvtools logs <app-name>      # View app logs
bruvtools scale <app> <count>  # Scale app replicas
bruvtools test <app-name>      # Test app connectivity

🚀 高度な機能

スマートな競合検出

bruvtools deploy my-app
# ✅ App "my-app" created and deployed

bruvtools deploy my-app  
# ⚠️  App "my-app" already exists, using "my-app-1" instead
# ✅ App "my-app-1" created and deployed

マルチ環境デプロイ

# Deploy to different environments
bruvtools deploy my-app-dev     # Development
bruvtools deploy my-app-staging # Staging  
bruvtools deploy my-app-prod    # Production

🔧 対応言語

言語	自動検出	ステータス
Node.js	package.json	✅ テスト済み
Go	go.mod	✅ 利用可能
Python	requirements.txt	✅ 利用可能
Java	pom.xml, build.gradle	✅ 利用可能
PHP	composer.json	✅ 利用可能
Ruby	Gemfile	✅ 利用可能
その他	Dockerfile	✅ 利用可能

🌐 公開中の例

• Hello World：https://hello-world.your-domain.com
• CNPJ Enricher：https://cnpj-enricher.your-domain.com
• Kommo Integration：https://kommo-contacts-api.your-domain.com
• ABEC Med API：https://abecmed-api-legacy.your-domain.com

API 呼び出しの例：

# Get Brazilian company information by CNPJ (tax ID)
curl "https://cnpj-enricher.your-domain.com/ficha?cnpj=11222333000181"

# Search patient by CPF (with API key)
curl -X GET "https://abecmed-api-legacy.your-domain.com/patient-search?cpf=024.804.267-00" \
  -H "X-API-KEY: your-api-key"

# Test Kommo integration
curl "https://kommo-contacts-api.your-domain.com/healthcheck"

📁 サンプルプロジェクト

リポジトリには、examples/ ディレクトリにすぐにデプロイできるサンプルが含まれています：

🚀 Hello World（examples/hello-world）

シンプルな Node.js ウェブサーバーです。bruvtools のセットアップをテストするのに最適です。

cd bruvtools/examples/hello-world
bruvtools deploy hello-world

💼 CNPJ Enricher（examples/cnpj-enricher）

外部データソースを使用する、ブラジル企業情報 API です。

cd bruvtools/examples/cnpj-enricher
bruvtools deploy cnpj-enricher

📞 Kommo Contacts API（examples/kommo-contacts-api）

連絡先管理機能を備えた、Kommo（AmoCRM）向け CRM 連携マイクロサービスです。

cd bruvtools/examples/kommo-contacts-api
bruvtools deploy kommo-contacts-api

🏥 ABEC Med API Legacy (examples/abecmed-api-legacy)

Google Sheets と連携する、医療患者検索マイクロサービスです。

機能：

• CPF または携帯電話番号による患者検索
• Google サービスアカウント認証
• ブラジルの電話番号の正規化
• API キー認証
• 包括的なログ記録

# Setup Google Service Account key first
ls examples/abecmed-api-legacy/keys/abecmed-368dfd6bae7c.json

# Deploy the service
cd bruvtools/examples/abecmed-api-legacy
bruvtools deploy abecmed-api-legacy

# Test the API
curl -X GET "https://abecmed-api-legacy.your-domain.com/patient-search?cpf=024.804.267-00" \
  -H "X-API-KEY: adcd2e35-787d-4dd2-ba8c-76085a99d2a4"

🎯 各サンプルに含まれるもの：

• ✅ 完全なソースコード
• ✅ デプロイ用の Dockerfile
• ✅ CapRover 用の captain-definition
• ✅ 依存関係を記載した package.json
• ✅ API ドキュメントを含む詳細な README
• ✅ 環境変数の設定

🔧 サンプルをすばやくデプロイ：

git clone https://github.com/fcavalcantirj/bruvtools.git
cd bruvtools/examples/[example-name]
bruvtools deploy [app-name]

💰 コストの比較

プラットフォーム	月額費用	機能
bruvtools + CapRover	$5	アプリ数無制限、SSL、スケーリング、自分のサーバー
Heroku	$25+	アプリ数に制限あり、SSL は別料金、共有リソース
Vercel Pro	$20+	関数数に制限あり、帯域幅に制限あり
Railway	$20+	使用量に制限あり、共有インフラストラクチャ
AWS/GCP	$50+	複雑なセットアップ、隠れたコスト

💡 DigitalOcean の $100 クレジットを利用すれば、20 か月間無料です！

🛠️ トラブルシューティング

よくある問題

問題	解決策
「CapRover CLI が見つかりません」	npm install -g caprover を実行し、ターミナルを再起動してください
「アプリ名が許可されていません」	小文字とハイフンのみを使用してください（例：my-app-name）
「認証に失敗しました」	.env ファイルに正しい CAPROVER_PASSWORD が設定されているか確認してください
CapRover のデフォルトページが表示される	デプロイが完了するまで 2～3 分お待ちください

⚠️ 環境変数に関する注意事項と制限

🚨 大きな環境変数（1000 文字超）

問題：CapRover や多くのクラウドプラットフォームでは、環境変数のサイズに厳しい制限があります。

• CapRover：環境変数ごとに約 1000 文字まで
• Heroku：すべての環境変数を合計して 32KB
• AWS Lambda：すべての環境変数を合計して 4KB
• Docker：厳密な上限はありませんが、値が非常に大きいとパフォーマンスが低下します

よくある原因：

• 🔑 JWT トークン：1000 文字を超えることがよくあります（特にクレームが多い場合）
• 🔐 秘密鍵：RSA/ECDSA 鍵は 1600 文字を超えることがあります
• 📄 JSON 設定：大きな設定オブジェクト
• 🌐 Base64 エンコードデータ：画像、証明書、バイナリデータ

✅ 大きな環境変数への対処方法

1. 手動で分割する ✅ 動作確認済み（推奨）

   # Split a 1083-character JWT token manually
   export JWT_TOKEN_1="first_part_here"
   export JWT_TOKEN_2="second_part_here"
   export JWT_TOKEN_3="third_part_here"
   
   # Add getEnvVar() function to your code (manual implementation)
   # Use getEnvVar('JWT_TOKEN') to reconstruct automatically
   

2. 代替方法 ✅ 動作確認済み

   # Option 1: Store in files (for very large data)
   echo "large_private_key_content" > /app/private.key
   # Then read in your app: fs.readFileSync('/app/private.key', 'utf8')
   
   # Option 2: Use external secret management
   # - AWS Secrets Manager
   # - HashiCorp Vault  
   # - Azure Key Vault
   # - Google Secret Manager
   

✅ ベストプラクティス

1. シークレットを Git に含めない

   # Always in .gitignore:
   .env
   .env.local
   .env.production
   bruvtools.yml
   

2. データの種類に応じた適切な保存先を使う

   • 短いシークレット（500 文字未満）：環境変数 ✅
   • 長いトークン（500～2000 文字）：環境変数を分割 ✅
   • 非常に長いデータ（2000 文字超）：ファイルまたはシークレット管理 ✅
   • バイナリデータ：ファイルを使用し、環境変数は使わない ❌

3. 再構成をテストする

   // Always test that your tokens work after reconstruction
   const token = getEnvVar('JWT_TOKEN');
   console.log(`Token length: ${token ? token.length : 0} characters`);
   if (!token || token.length < 100) {
     throw new Error('JWT token reconstruction failed!');
   }
   

📋 プラットフォームごとの制限

プラットフォーム	変数ごとの上限	合計上限	備考
CapRover	約 1000 文字	合計上限なし	厳密な上限があり、エラーを表示せずに失敗します
Heroku	32KB	合計 32KB	変数名を含みます
AWS Lambda	変数ごとの上限なし	合計 4KB	非常に厳しい制限です
Docker	厳密な上限なし	メモリに依存	パフォーマンスに影響します
Kubernetes	1MB	合計上限なし	etcd で Base64 エンコードされます

🪟 Windows PowerShell のサポート

✅ 「完全に」サポートされています！ bruvtools は Windows PowerShell で「シームレスに」動作します。ええ、動作するはずです °¿°

# 1. Install both tools
npm install -g bruvtools caprover

# 2. Verify installation
bruvtools --version  # Should show: 0.2.16
caprover --version   # Should show: 2.x.x

# 3. Deploy normally (same as Mac/Linux)
bruvtools init
bruvtools deploy my-app

---

要件：Node.js 16+ • ライセンス：MIT • バージョン：0.2.16

🤝 コントリビューション

コントリビューションを歓迎します！デプロイをシンプルで信頼性の高いものにすることを目指す、本格的なオープンソースプロジェクトです。

1. リポジトリをフォークします
2. 機能ブランチを作成します
3. 変更を十分にテストします
4. プルリクエストを送信します

📞 サポート

• 問題：GitHub Issues
• ドキュメント：GitHub Wiki
• メール：[email protected]

---

bruvtools チームが ❤️ を込めて作成 • 決して諦めないでください！ 🚀