@codelook/codebox 🚀

Code containerization and deployment platform with beautiful Ink UI - Box your code, ship it anywhere with ease!

🆕 最新更新 (v0.1.2)

• 🎨 增强的用户体验: 更美观的菜单、更清晰的交互界面
• 🚫 智能错误处理: 友好的错误信息、建议性解决方案
• 🔍 输入验证: 实时验证用户输入，避免配置错误
• 🔄 服务注册中心: 集成 @codelook/codebox-registry 进行服务监控

Features

• 🚀 Quick Deploy - Deploy any project with a single command
• 🐳 Docker Support - First-class support for Docker and Docker Compose
• ☁️ Edge Platform Support - Deploy to Cloudflare Workers, Vercel Edge Functions
• 🤖 CI/CD Ready - Full non-interactive mode for automation
• 🏗️ Remote Build - Build Docker images on server (no local Docker required)
• 📁 Multi-Project - Manage multiple projects and deployment configurations
• 🖥️ Multi-Server - Deploy to multiple servers with different environments
• 🎨 Beautiful UI - Interactive Ink-based terminal UI (when available)
• 📊 History Tracking - Track all deployments with rollback capability
• 🔐 Secure - SSH key and password authentication support
• 🎯 Smart Detection - Automatically detects project type and configuration
• 🌍 Environment Aware - Auto-adapts to TTY, CI, and remote environments
• 🔌 Extensible - Plugin architecture for custom deployment platforms
• 💡 Smart Error Handling - Contextual error messages with helpful suggestions
• ✅ Input Validation - Real-time validation prevents configuration errors
• 📊 Service Monitoring - Built-in service registry for health monitoring

Installation

# Using npm
npm install -g @codelook/codebox

# Using pnpm (recommended)
pnpm add -g @codelook/codebox

# Using yarn
yarn global add @codelook/codebox

# Or use without installing
npx @codelook/codebox

Note: If you encounter any installation issues, please refer to our detailed Installation Guide.

Quick Start

1. Initialize your project

# In your project directory
codebox init

This will automatically detect your project type (Docker, Docker Compose, Node.js, etc.) and create the initial configuration.

2. Add a server

# Interactive mode
codebox

# Then select "Servers" > "Add New Server"

3. Deploy!

# Deploy to all configured servers
codebox deploy

# Or use quick deploy from the interactive menu
codebox
# Then select "Quick Deploy"

Project Types

CodeBox automatically detects and supports:

Traditional Deployment

• 🐳 Docker Compose - Projects with docker-compose.yml
• 🐋 Docker - Projects with Dockerfile
• 📦 Node.js - Projects with package.json
• 📄 Static - Any other project (copies files)

Edge Platforms (NEW!)

• ☁️ Cloudflare Workers - Projects with wrangler.toml or cloudflare/ directory
• ▲ Vercel Edge Functions - Projects with vercel.json or edge functions
• 🦕 Deno Deploy - Projects configured for Deno (coming soon)

Commands

Interactive Mode (Default)

codebox

Launch the beautiful interactive UI to manage everything.

CLI Commands

# Initialize project in current directory
codebox init

# Deploy current project
codebox deploy [server] [options]
  -f, --force        Force deployment even if health checks fail
  -b, --backup       Create backup before deployment
  --dry-run          Show what would be deployed
  --remote-build     Build Docker images on remote server
  --no-interactive   Disable interactive mode

# Deploy to edge platforms
codebox deploy-edge <platform> [options]
  -e, --env          Deployment environment (production/preview/development)
  --project          Project name override
  --config           Custom configuration file
  
  Platforms: cloudflare, vercel, deno

# Manage servers
codebox server list
codebox server add <name>
codebox server remove <name>

# Service management
codebox status              Show status of all deployed services
codebox stop <serviceId>    Stop a deployed service
codebox start <serviceId>   Start a deployed service
codebox destroy <serviceId> Destroy a deployed service

# Show version
codebox --version

Configuration

CodeBox stores its configuration in ~/.codebox/config.json. This includes:

• Server configurations
• Project configurations
• Deployment mappings
• Deployment history
• Global settings

Server Configuration

Servers can be configured with:

• Name - Friendly name for the server
• Host - IP address or domain
• Port - SSH port (default: 22)
• User - SSH username
• Authentication - SSH key (recommended) or password
• Deploy Path - Where to deploy projects on the server

Deployment Features

Health Checks

Configure health checks to ensure deployments are successful:

{
  "healthCheck": {
    "enabled": true,
    "endpoint": "http://localhost:3000/health",
    "interval": 5000,
    "timeout": 30000
  }
}

Hooks

Run custom commands before or after deployment:

{
  "hooks": {
    "preDeploy": ["npm test", "npm run build"],
    "postDeploy": ["npm run migrate", "npm run notify"]
  }
}

Environment Variables

Set environment variables for your deployments:

{
  "env": {
    "NODE_ENV": "production",
    "API_URL": "https://api.example.com"
  }
}

Examples

Deploy a Docker Compose project

1. Create your docker-compose.yml
2. Run codebox init
3. Add a server: codebox > "Servers" > "Add New Server"
4. Deploy: codebox deploy

Deploy a Node.js app

1. Ensure your project has a package.json with a start script
2. Run codebox init
3. Configure your server
4. Deploy - CodeBox will automatically:
   • Upload your files
   • Run npm install --production
   • Start your app with PM2

Deploy to Cloudflare Workers

1. Create your worker.js or use existing cloudflare/ directory
2. Set up your Cloudflare API token:

   export CLOUDFLARE_API_TOKEN=your-token

3. Deploy:

   codebox deploy-edge cloudflare

Deploy to Vercel Edge Functions

1. Create your edge functions in api/ directory
2. Set up your Vercel token:

   export VERCEL_TOKEN=your-token

3. Deploy:

   codebox deploy-edge vercel --env production

Non-Interactive Mode

CodeBox automatically detects when running in non-interactive environments:

• CI/CD pipelines (CI=true)
• Non-TTY terminals
• SSH remote execution
• Docker containers

You can also force non-interactive mode:

# Using environment variable
CODEBOX_NON_INTERACTIVE=true codebox deploy

# Using command flag
codebox deploy --no-interactive

Health Monitoring

CodeBox includes built-in health monitoring for deployed services:

Check Service Health

# Check all services
codebox health-check

# Check specific service
codebox health-check edge-myapp-cloudflare-production

# Output as JSON
codebox health-check --json

View Health Summary

# Get overview of all services
codebox health-summary

# JSON output for integration
codebox health-summary --json

Health check features:

• 🏥 Automatic health monitoring
• 📊 Response time tracking
• 🔔 Status change detection
• 📈 Historical health data
• 🔄 Configurable check intervals

Service Management

List All Deployments

# List edge deployments
codebox edge-list

# List all services
codebox list

Stop Services

# Stop a service (server deployments only)
codebox stop service-id

# Start a stopped service
codebox start service-id

# Destroy a service
codebox destroy service-id

Remote Docker Build

No Docker on your local machine? No problem! Use remote build:

# Build Docker images on the server
codebox deploy --remote-build

# CodeBox auto-detects if Docker is missing
codebox deploy  # Automatically switches to remote build

Security

• SSH keys are recommended over passwords
• All credentials are stored locally in your home directory
• No credentials are ever sent to third parties
• Use environment variables for sensitive data

Troubleshooting

SSH Connection Issues

• Ensure your SSH key has proper permissions: chmod 600 ~/.ssh/id_rsa
• Test connection manually: ssh user@host
• Check firewall settings on the server

Docker Issues

• Ensure Docker is installed on the server
• User must have Docker permissions: sudo usermod -aG docker $USER
• Check Docker daemon is running: systemctl status docker
• If local Docker is missing, use --remote-build flag

Non-Interactive Mode Issues

• If you see "Raw mode is not supported", you're in a non-TTY environment
• Use codebox deploy instead of just codebox
• Set CODEBOX_NON_INTERACTIVE=true to suppress warnings
• For server configuration, edit ~/.codebox/config.json directly

Port Issues

• Ensure required ports are open on the server
• Check for port conflicts with existing services
• Use health checks to verify services are accessible

Contributing

Contributions are welcome! Please read our contributing guidelines and submit PRs.

License

PolyForm Noncommercial License 1.0.0 - see LICENSE file for details.

Made with ❤️ by the UEUI Team