bruvtools 🚀

Your Private App Platform - Deploy microservices anywhere, any language, one CLI

Deploy Node.js, Go, Python, Java, PHP, Ruby, or any containerizable application to CapRover, AWS, GCP, or Kubernetes with the same simple commands. Zero vendor lock-in.

🎯 What is bruvtools?

bruvtools transforms any cloud server into your private app platform - like having your own Heroku, Vercel, or Railway. Combined with CapRover, you get:

Feature	Description
✅ Push to deploy	bruvtools deploy my-app and you're live
✅ Auto SSL certificates	HTTPS enabled automatically
✅ Any language	Node.js, Python, Go, Java, PHP, Ruby, Docker
✅ Zero downtime deployments	Rolling updates built-in
✅ Auto scaling	Scale apps up/down as needed
✅ Private & secure	Your own server, your own rules
✅ Cost effective	$5/month vs $25+ on other platforms

🚀 Quick Start: Your Private Platform in 5 Minutes

Step 1: Create Your CapRover Server (2 minutes)

The easiest way to get started is with DigitalOcean's one-click CapRover deployment:

What this gives you:

• ✅ $5/month server with CapRover pre-installed
• ✅ $100 free credit for new DigitalOcean users (2 months free!)
• ✅ Docker & firewall configured automatically
• ✅ Ready to deploy in minutes

Alternative setup: Follow the CapRover Getting Started Guide for manual installation on any cloud provider.

Step 2: Install bruvtools (30 seconds)

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

Step 3: Configure & Deploy (2 minutes)

# 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!

🎯 That's it! Your private app platform is ready. Your app is now live at https://my-app.yourdomain.com with automatic SSL.

🔌 MCP Integration (Cursor.com) - Revolutionary Development Experience

With Model Context Protocol (MCP) support, you get a revolutionary development experience - deploy directly from Cursor.com without ever leaving your editor:

Feature	Description
📋 List all apps	See your entire infrastructure from within your IDE
📊 Pull logs in real-time	Debug without switching windows
🚀 Deploy with AI assistance	Just ask Claude: "Deploy this to production"
📈 Monitor status live	App health, metrics, and scaling from your editor
🔄 Rollback instantly	"Rollback to previous version" - done!
🎯 Smart suggestions	AI recommends optimizations based on your code

🤯 The Experience:

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

This is the future of development - your AI pair programmer that can actually deploy and manage your infrastructure. No context switching, no separate terminals, no deployment dashboards. Just code, ask, and it's live.

See below for a real example of how Claude responds after successful setup.

🔌 MCP Setup for Cursor.com (5 minutes)

Option 1: Automated Setup (Recommended)

For the easiest setup, use the automated script from within the bruvtools repository:

# 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

Note: The setup script must be run from within the bruvtools repository directory as it uses the included mcp-server.js file.

Option 2: Manual Setup

Step 1: Install bruvtools MCP Server

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

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

Step 2: Configure Cursor.com MCP Settings

1. Open Cursor.com Settings:

   • Press Cmd/Ctrl + , to open settings
   • Search for "MCP" or go to Extensions → Model Context Protocol

2. Add bruvtools MCP Server:

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

3. Alternative: Use Local Configuration: If you have bruvtools.yml and .env files in your project:

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

Step 3: Restart Cursor.com and Test the Integration

Open any project in Cursor.com and try these commands with 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]

🎯 What You'll See After Successful Setup:

Example of Claude showing your deployed services through MCP integration

🎯 Enhanced Developer Experience (v0.2.16)

✅ Post-Deployment Health Verification

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!

🔧 Auto-Fixing Common Issues

• Instance Count = 0: Automatically scales to 1 instance
• Port Mismatches: Detects server.js vs Dockerfile port conflicts
• SSL Issues: Provides clear guidance for certificate problems
• Container Crashes: Shows debugging steps and common solutions

🔐 Intelligent Environment Variable Handling

🚨 Large Environment Variable Detection & Auto-Splitting ⚠️ EXPERIMENTAL

bruvtools can detect when environment variables exceed platform limits and offers smart solutions (currently experimental):

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

🔄 Manual Token Reconstruction ✅ WORKING

You can manually implement split environment variables using this pattern:

// 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!

🔧 Configuration Files

bruvtools uses a clean separation between configuration and secrets:

📄 bruvtools.yml - Configuration (Non-Secrets)

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

🔐 .env - Secrets Only

# CapRover Authentication
CAPROVER_PASSWORD=your-caprover-password

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

⚠️ Security: Both files are automatically added to .gitignore and should NEVER be committed to version control.

🏗️ CapRover Setup Details

Prerequisites

• Domain name ($2/year) - for wildcard DNS (*.yourdomain.com)
• Server with public IP ($5/month) - DigitalOcean, Vultr, Linode, etc.
• Docker installed - included in one-click deployment

DNS Configuration

Set up a wildcard A record in your DNS:

• Type: A record
• Host: *.captain (or *.apps, *.dev, etc.)
• Points to: Your server's IP address
• TTL: 300 (or default)

Server Requirements

• Minimum: 1GB RAM, 1 CPU core
• Recommended: 2GB RAM for building larger apps
• OS: Ubuntu 22.04+ (tested and recommended)
• Docker: Version 25.x+ (auto-installed with one-click)

📋 Common Commands

# 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

🚀 Advanced Features

Smart Collision Detection

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

Multi-Environment Deployment

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

🔧 Supported Languages

Language	Auto-Detection	Status
Node.js	package.json	✅ Fully Tested
Go	go.mod	✅ Ready
Python	requirements.txt	✅ Ready
Java	pom.xml, build.gradle	✅ Ready
PHP	composer.json	✅ Ready
Ruby	Gemfile	✅ Ready
Any	Dockerfile	✅ Ready

🌐 Live Examples

• 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

Example API calls:

# 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"

📁 Example Projects

The repository includes ready-to-deploy examples in the examples/ directory:

🚀 Hello World (examples/hello-world)

Simple Node.js web server - perfect for testing your bruvtools setup.

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

💼 CNPJ Enricher (examples/cnpj-enricher)

Brazilian company information API using external data sources.

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

📞 Kommo Contacts API (examples/kommo-contacts-api)

CRM integration microservice for Kommo (AmoCRM) with contact management.

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

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

Healthcare patient search microservice with Google Sheets integration.

Features:

• Patient search by CPF or mobile number
• Google Service Account authentication
• Brazilian phone number normalization
• API key authentication
• Comprehensive logging

# 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"

🎯 Each example includes:

• ✅ Complete source code
• ✅ Dockerfile for deployment
• ✅ captain-definition for CapRover
• ✅ package.json with dependencies
• ✅ Detailed README with API documentation
• ✅ Environment variable configuration

🔧 Quick Deploy Any Example:

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

💰 Cost Comparison

Platform	Monthly Cost	Features
bruvtools + CapRover	$5	Unlimited apps, SSL, scaling, your server
Heroku	$25+	Limited apps, SSL extra, shared resources
Vercel Pro	$20+	Limited functions, bandwidth limits
Railway	$20+	Limited usage, shared infrastructure
AWS/GCP	$50+	Complex setup, hidden costs

💡 With DigitalOcean's $100 credit, you get 20 months free!

🛠️ Troubleshooting

Common Issues

Issue	Solution
"CapRover CLI not found"	npm install -g caprover and restart terminal
"App name not allowed"	Use lowercase letters and hyphens only (e.g., my-app-name)
"Authentication failed"	Check your .env file has correct CAPROVER_PASSWORD
Shows default CapRover page	Wait 2-3 minutes for deployment to complete

⚠️ Environment Variable Caveats & Limitations

🚨 Large Environment Variables (>1000 characters)

The Problem: CapRover and many cloud platforms have strict limits on environment variable sizes:

• CapRover: ~1000 character limit per environment variable
• Heroku: 32KB total for all environment variables
• AWS Lambda: 4KB total for all environment variables
• Docker: No hard limit, but performance degrades with very large values

Common Culprits:

• 🔑 JWT Tokens: Often 1000+ characters (especially with extensive claims)
• 🔐 Private Keys: RSA/ECDSA keys can be 1600+ characters
• 📄 JSON Configs: Large configuration objects
• 🌐 Base64 Encoded Data: Images, certificates, or binary data

✅ Solutions for Large Environment Variables

1. Manual Splitting ✅ WORKING (recommended approach)

   # 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. Alternative Solutions ✅ WORKING

   # 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

✅ Best Practices

1. Keep secrets out of git

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

2. Use appropriate storage for data type

   • Short secrets (<500 chars): Environment variables ✅
   • Long tokens (500-2000 chars): Split environment variables ✅
   • Very long data (>2000 chars): Files or secret management ✅
   • Binary data: Files, never environment variables ❌

3. Test your reconstruction

   // 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!');
   }

📋 Platform-Specific Limits

Platform	Per Variable	Total Limit	Notes
CapRover	~1000 chars	No total limit	Hard limit, fails silently
Heroku	32KB	32KB total	Includes variable names
AWS Lambda	No per-var limit	4KB total	Very restrictive
Docker	No hard limit	Memory dependent	Performance impact
Kubernetes	1MB	No total limit	Base64 encoded in etcd

🪟 Windows PowerShell Support

✅ "Fully" Supported! bruvtools works 'seamlessly' on Windows PowerShell. Well, it should °¿°

# 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

---

Requirements: Node.js 16+ • License: MIT • Version: 0.2.16

🤝 Contributing

We welcome contributions! This is a serious open-source project focused on making deployment simple and reliable.

1. Fork the repository
2. Create a feature branch
3. Test your changes thoroughly
4. Submit a pull request

📞 Support

• Issues: GitHub Issues
• Documentation: GitHub Wiki
• Email: felipecavalcantirj@gmail.com

---

Made with ❤️ by the bruvtools team • Never Give Up! 🚀