@172ai/containers-mcp-server 1.8.4 → 1.9.2

package/README.md

@@ -363,6 +363,399 @@ This provides detailed information about:
 - Error details and stack traces
 - Performance metrics
 
+## 🏭 Production Deployment Guide
+
+### Resource Allocation
+
+The platform supports configurable CPU and memory resources for optimal performance:
+
+#### CPU Options
+- **1 vCPU**: Light workloads, simple web services, development
+- **2 vCPUs**: Web applications, small databases, API services
+- **4 vCPUs**: Heavy web apps, medium databases, data processing
+- **8 vCPUs**: Large databases, intensive processing, high-traffic apps
+
+#### Memory Options
+- **1Gi**: Lightweight services, static sites, simple APIs
+- **2Gi**: Web applications, small databases, moderate traffic
+- **4Gi**: Medium databases, data processing, higher traffic
+- **8Gi**: Large databases, memory-intensive apps, high traffic
+- **16Gi**: Enterprise databases, big data processing, heavy workloads
+
+#### Resource Sizing Guidelines
+
+**Web Applications:**
+```bash
+# Small/Medium (< 1000 users)
+start_execution({
+  containerId: "your-container-id",
+  cpu: "2",
+  memory: "2Gi",
+  durationDays: 7
+})
+
+# Large (1000+ users)
+start_execution({
+  containerId: "your-container-id",
+  cpu: "4",
+  memory: "8Gi",
+  durationDays: 30
+})
+```
+
+**Database Workloads:**
+```bash
+# PostgreSQL/MySQL
+start_execution({
+  containerId: "your-db-container",
+  cpu: "4",
+  memory: "8Gi",
+  durationDays: 30
+})
+
+# MongoDB/Elasticsearch
+start_execution({
+  containerId: "your-nosql-container",
+  cpu: "8",
+  memory: "16Gi",
+  durationDays: 30
+})
+```
+
+**Workflow Automation (n8n, Zapier alternatives):**
+```bash
+start_execution({
+  containerId: "workflow-container",
+  cpu: "4",
+  memory: "8Gi",
+  durationDays: 30,
+  envVars: {
+    DB_TYPE: "sqlite",
+    DB_SQLITE_DATABASE: "/home/node/.n8n/database.sqlite",
+    N8N_BASIC_AUTH_ACTIVE: "true",
+    N8N_BASIC_AUTH_USER: "admin",
+    N8N_BASIC_AUTH_PASSWORD: "secure-password"
+  }
+})
+```
+
+### Performance Optimization
+
+#### Resource Planning
+1. **Start Conservative**: Begin with 2 CPU / 2Gi memory
+2. **Monitor Metrics**: Use `get_container_metrics` to track utilization
+3. **Scale Gradually**: Increase resources based on actual usage patterns
+4. **Cost Optimization**: Right-size resources to avoid over-provisioning
+
+#### Common Optimization Patterns
+```bash
+# Development/Testing
+cpu: "1", memory: "1Gi"
+
+# Production Web Apps
+cpu: "2-4", memory: "2Gi-4Gi"
+
+# Production Databases
+cpu: "4-8", memory: "8Gi-16Gi"
+
+# Data Processing/ETL
+cpu: "8", memory: "16Gi"
+```
+
+### Environment Variable Management
+
+#### Production Environment Setup
+```bash
+# Security
+NODE_ENV=production
+API_TIMEOUT=30000
+RATE_LIMIT_PER_MINUTE=1000
+
+# Database Configuration
+DB_TYPE=sqlite
+DB_SQLITE_DATABASE=/app/data/database.sqlite
+DB_SQLITE_POOL_SIZE=10
+DB_SQLITE_ENABLE_WAL=true
+
+# Application Specific
+N8N_BASIC_AUTH_ACTIVE=true
+N8N_HOST=0.0.0.0
+N8N_PORT=5678
+N8N_PROTOCOL=http
+```
+
+#### Environment Variable Best Practices
+1. **Never hardcode secrets** in Dockerfiles
+2. **Use .env files** for local development
+3. **Override at runtime** using start_execution envVars
+4. **Validate critical vars** in application startup
+5. **Document required variables** in your container description
+
+## 📚 Application Deployment Examples
+
+### Example 1: n8n Workflow Automation
+
+Complete production deployment for n8n workflow automation platform:
+
+```javascript
+// 1. Create the container with comprehensive Dockerfile
+const container = await create_container({
+  name: "n8n-workflow-automation",
+  description: "Production n8n workflow automation with SQLite persistence",
+  dockerfile: `FROM n8nio/n8n:latest
+
+# Set up data directory with proper permissions
+USER root
+RUN mkdir -p /home/node/.n8n && chown -R node:node /home/node/.n8n
+USER node
+
+# Production environment configuration
+ENV NODE_ENV=production
+ENV DB_TYPE=sqlite
+ENV DB_SQLITE_DATABASE=/home/node/.n8n/database.sqlite
+ENV DB_SQLITE_POOL_SIZE=10
+ENV DB_SQLITE_ENABLE_WAL=true
+ENV N8N_BASIC_AUTH_ACTIVE=true
+ENV N8N_HOST=0.0.0.0
+ENV N8N_PORT=5678
+
+# Health check
+HEALTHCHECK --interval=30s --timeout=10s --start-period=60s --retries=3 \\
+  CMD curl -f http://localhost:5678/healthz || exit 1
+
+EXPOSE 5678
+CMD ["n8n", "start"]`,
+  tags: ["workflow-automation", "n8n", "production"],
+  envVars: [
+    { key: "N8N_BASIC_AUTH_USER", value: "admin" },
+    { key: "N8N_BASIC_AUTH_PASSWORD", value: "secure-password-change-me" }
+  ]
+})
+
+// 2. Build the container
+await build_container({ containerId: container.id })
+
+// 3. Start with production resources
+await start_execution({
+  containerId: container.id,
+  cpu: "4",
+  memory: "8Gi",
+  durationDays: 30
+})
+```
+
+### Example 2: PostgreSQL Database
+
+```javascript
+const dbContainer = await create_container({
+  name: "postgresql-production",
+  description: "Production PostgreSQL database with persistent storage",
+  dockerfile: `FROM postgres:15-alpine
+
+# Install extensions
+RUN apk add --no-cache postgresql-contrib
+
+# Configuration
+ENV POSTGRES_DB=myapp
+ENV POSTGRES_USER=appuser
+ENV PGDATA=/var/lib/postgresql/data/pgdata
+
+# Optimization for production
+RUN echo "shared_preload_libraries = 'pg_stat_statements'" >> /usr/share/postgresql/postgresql.conf.sample
+RUN echo "max_connections = 200" >> /usr/share/postgresql/postgresql.conf.sample
+RUN echo "shared_buffers = 256MB" >> /usr/share/postgresql/postgresql.conf.sample
+
+EXPOSE 5432`,
+  envVars: [
+    { key: "POSTGRES_PASSWORD", value: "secure-db-password" }
+  ]
+})
+
+await start_execution({
+  containerId: dbContainer.id,
+  cpu: "4",
+  memory: "8Gi",
+  durationDays: 30
+})
+```
+
+### Example 3: Node.js Web Application
+
+```javascript
+const webAppContainer = await create_container({
+  name: "nodejs-web-app",
+  description: "Production Node.js web application with monitoring",
+  dockerfile: `FROM node:18-alpine
+
+WORKDIR /app
+
+# Copy package files
+COPY package*.json ./
+RUN npm ci --only=production
+
+# Copy application code
+COPY . .
+
+# Security: run as non-root user
+RUN addgroup -g 1001 -S nodejs
+RUN adduser -S nodejs -u 1001
+RUN chown -R nodejs:nodejs /app
+USER nodejs
+
+# Environment setup
+ENV NODE_ENV=production
+ENV PORT=3000
+
+# Health check
+HEALTHCHECK --interval=30s --timeout=10s --start-period=30s --retries=3 \\
+  CMD curl -f http://localhost:3000/health || exit 1
+
+EXPOSE 3000
+CMD ["npm", "start"]`,
+  tags: ["nodejs", "web-app", "production"]
+})
+
+await start_execution({
+  containerId: webAppContainer.id,
+  cpu: "2",
+  memory: "4Gi",
+  durationDays: 14
+})
+```
+
+## 🔧 Troubleshooting Guide
+
+### Common Deployment Issues
+
+#### Container Fails to Start
+**Symptoms**: Container status shows "failed" or "stopped"
+**Solutions**:
+1. Check build logs: `get_build_logs({ containerId, buildLogId })`
+2. Verify Dockerfile syntax and base image availability
+3. Ensure EXPOSE ports match application ports
+4. Check for missing dependencies or environment variables
+
+```bash
+# Debug container startup
+get_execution_logs({
+  executionId: "your-execution-id",
+  lines: 100,
+  severity: ["ERROR", "WARNING"]
+})
+```
+
+#### Resource Allocation Problems
+**Symptoms**: Application runs slowly or crashes with OOM errors
+**Solutions**:
+1. Monitor current usage: `get_container_metrics({ containerId })`
+2. Increase memory allocation if utilization > 80%
+3. Add CPU resources if utilization consistently > 70%
+4. Check for memory leaks in application code
+
+```javascript
+// Upgrade resources for running container
+await stop_execution({ containerId })
+await start_execution({
+  containerId,
+  cpu: "4",        // Increased from 2
+  memory: "8Gi",   // Increased from 4Gi
+  durationDays: 30
+})
+```
+
+#### Environment Variable Issues
+**Symptoms**: Application configuration errors, database connection failures
+**Solutions**:
+1. Verify environment variables in Dockerfile
+2. Check runtime override in start_execution
+3. Ensure sensitive values aren't hardcoded
+4. Validate variable formats and required values
+
+```javascript
+// Correct environment variable setup
+await start_execution({
+  containerId: "your-container",
+  envVars: {
+    DATABASE_URL: "sqlite:///app/data/db.sqlite",
+    NODE_ENV: "production",
+    PORT: "8080"
+  }
+})
+```
+
+#### Performance Optimization Issues
+**Symptoms**: Slow response times, high resource usage, timeout errors
+**Solutions**:
+1. **CPU Bottlenecks**:
+   - Monitor CPU metrics regularly
+   - Increase CPU allocation
+   - Optimize application code (async operations, caching)
+
+2. **Memory Issues**:
+   - Check for memory leaks
+   - Increase memory allocation
+   - Implement proper garbage collection
+
+3. **I/O Bottlenecks**:
+   - Use connection pooling for databases
+   - Implement caching strategies
+   - Optimize database queries
+
+#### Network and Connectivity Issues
+**Symptoms**: Cannot access container, API timeouts, connection refused
+**Solutions**:
+1. Verify container is running: `get_execution_status({ containerId })`
+2. Check exposed ports match application ports
+3. Ensure health checks are properly configured
+4. Verify firewall and security group settings
+
+```dockerfile
+# Correct port configuration
+EXPOSE 8080
+HEALTHCHECK --interval=30s CMD curl -f http://localhost:8080/health
+```
+
+### Debug Mode and Logging
+
+Enable comprehensive debugging:
+```bash
+# Server-side debugging
+LOG_LEVEL=debug containers-mcp-server
+
+# Container-specific logging
+get_runtime_logs({
+  executionId: "your-execution-id",
+  lines: 500,
+  severity: ["DEBUG", "INFO", "WARNING", "ERROR"]
+})
+```
+
+### Performance Monitoring
+
+Monitor container performance:
+```javascript
+// Get real-time metrics
+const metrics = await get_container_metrics({ containerId })
+
+// Check key indicators:
+// - CPU utilization < 70% for optimal performance
+// - Memory utilization < 80% to avoid OOM
+// - Request rate trends for scaling decisions
+```
+
+### Getting Help
+
+1. **Check this troubleshooting guide** for common solutions
+2. **Enable debug logging** for detailed error information
+3. **Monitor metrics** to identify performance bottlenecks
+4. **Review execution logs** for application-specific errors
+5. **Check resource allocation** against application requirements
+
+For persistent issues:
+- Include container ID, execution ID, and error logs
+- Provide steps to reproduce the issue
+- Share relevant configuration (Dockerfile, environment variables)
+
 ## Security
 
 ### Best Practices

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@172ai/containers-mcp-server",
-  "version": "1.8.4",
+  "version": "1.9.2",
   "description": "MCP server for 172.ai container management platform - enables AI assistants to manage containers, builds, and files with comprehensive workflow prompts",
   "main": "dist/cli.js",
   "bin": {
@@ -70,14 +70,7 @@
     "LICENSE",
     ".env.example"
   ],
-  "repository": {
-    "type": "git",
-    "url": "https://github.com/172ai/containers-mcp-server.git"
-  },
-  "bugs": {
-    "url": "https://github.com/172ai/containers-mcp-server/issues"
-  },
-  "homepage": "https://github.com/172ai/containers-mcp-server#readme",
+  "homepage": "https://172.ai",
   "publishConfig": {
     "access": "public"
   }