suthep 0.1.0-beta.1

package/docs/en/architecture.md

@@ -0,0 +1,369 @@
+# Architecture
+
+This document explains how Suthep works under the hood, including its components, deployment strategies, and internal architecture.
+
+> **For Developers**: If you're looking to contribute or extend Suthep, check out the [Developer Guide](./developer-guide.md) for detailed information on development setup, code organization, and contributing guidelines.
+
+## Overview
+
+Suthep is a deployment automation tool that orchestrates multiple components to provide a seamless deployment experience:
+
+```
+┌─────────────────────────────────────────────────────────┐
+│                    Suthep CLI Tool                       │
+│  (init, setup, deploy commands)                         │
+└─────────────────────────────────────────────────────────┘
+                          │
+                          ▼
+        ┌─────────────────────────────────────┐
+        │      Configuration Loader            │
+        │  (Loads and validates suthep.yml)   │
+        └─────────────────────────────────────┘
+                          │
+        ┌─────────────────┴─────────────────┐
+        │                                   │
+        ▼                                   ▼
+┌───────────────┐                  ┌──────────────┐
+│   Docker      │                  │   Nginx      │
+│   Manager     │                  │   Manager    │
+└───────────────┘                  └──────────────┘
+        │                                   │
+        │                                   ▼
+        │                          ┌──────────────┐
+        │                          │   Certbot    │
+        │                          │   Manager    │
+        │                          └──────────────┘
+        │                                   │
+        └───────────────────────────────────┘
+                          │
+                          ▼
+                ┌─────────────────┐
+                │   Deployment    │
+                │   Strategy      │
+                │  (Rolling/      │
+                │   Blue-Green)   │
+                └─────────────────┘
+```
+
+## Core Components
+
+### 1. Configuration System
+
+**File**: `src/utils/config-loader.ts`
+
+The configuration system:
+- Loads YAML configuration files
+- Validates configuration structure
+- Provides type-safe configuration objects
+
+**Type Definitions**: `src/types/config.ts`
+
+All configuration types are defined using TypeScript interfaces:
+- `DeployConfig`: Root configuration object
+- `ServiceConfig`: Individual service configuration
+- `DockerConfig`: Docker-specific settings
+- `HealthCheckConfig`: Health check settings
+- `NginxConfig`: Nginx settings
+- `CertbotConfig`: SSL certificate settings
+- `DeploymentConfig`: Deployment strategy settings
+
+### 2. Docker Manager
+
+**File**: `src/utils/docker.ts`
+
+The Docker manager handles:
+- **Container lifecycle**: Start, stop, remove containers
+- **Image management**: Pull and run Docker images
+- **Port mapping**: Maps host ports to container ports
+- **Environment variables**: Injects environment variables into containers
+- **Container inspection**: Check container status and logs
+
+**Key Functions**:
+- `startDockerContainer()`: Starts or connects to a container
+- `stopDockerContainer()`: Stops a running container
+- `isContainerRunning()`: Checks if a container is running
+- `getContainerLogs()`: Retrieves container logs
+
+**Container Logic**:
+1. Check if container exists
+2. If exists and running: Use existing container
+3. If exists but stopped: Start the container
+4. If doesn't exist and image provided: Create and run new container
+5. If doesn't exist and no image: Error (connect to existing only)
+
+### 3. Nginx Manager
+
+**File**: `src/utils/nginx.ts`
+
+The Nginx manager:
+- **Configuration generation**: Creates Nginx server blocks
+- **Site management**: Enables/disables Nginx sites
+- **Configuration reload**: Tests and reloads Nginx
+
+**Generated Configuration Structure**:
+
+```nginx
+# Upstream definition
+upstream service_backend {
+    server localhost:PORT;
+    keepalive 32;
+}
+
+# HTTP server (redirects to HTTPS if SSL enabled)
+server {
+    listen 80;
+    server_name domain1.com domain2.com;
+    return 301 https://$server_name$request_uri;
+}
+
+# HTTPS server
+server {
+    listen 443 ssl http2;
+    server_name domain1.com domain2.com;
+
+    # SSL configuration
+    ssl_certificate /etc/letsencrypt/live/domain/fullchain.pem;
+    ssl_certificate_key /etc/letsencrypt/live/domain/privkey.pem;
+
+    # Proxy settings
+    location / {
+        proxy_pass http://service_backend;
+        proxy_set_header Host $host;
+        proxy_set_header X-Real-IP $remote_addr;
+        # ... more proxy headers
+    }
+
+    # Health check endpoint
+    location /health {
+        proxy_pass http://service_backend;
+        access_log off;
+    }
+}
+```
+
+**Key Functions**:
+- `generateNginxConfig()`: Creates Nginx configuration
+- `enableSite()`: Creates symlink in sites-enabled
+- `reloadNginx()`: Tests and reloads Nginx
+- `disableSite()`: Removes site from sites-enabled
+
+### 4. Certbot Manager
+
+**File**: `src/utils/certbot.ts`
+
+The Certbot manager handles SSL certificate operations:
+- **Certificate requests**: Obtains certificates from Let's Encrypt
+- **Certificate renewal**: Renews expiring certificates
+- **Certificate revocation**: Revokes certificates
+- **Certificate inspection**: Checks certificate expiration
+
+**Key Functions**:
+- `requestCertificate()`: Requests SSL certificate for a domain
+- `renewCertificates()`: Renews all certificates
+- `checkCertificateExpiration()`: Checks when certificate expires
+- `revokeCertificate()`: Revokes a certificate
+
+**Certificate Request Process**:
+1. Run `certbot certonly --nginx` for each domain
+2. Certbot validates domain ownership
+3. Certbot obtains and stores certificate
+4. Nginx configuration updated with certificate paths
+
+### 5. Deployment Strategy
+
+**File**: `src/utils/deployment.ts`
+
+Suthep supports two deployment strategies:
+
+#### Rolling Deployment
+
+Gradually replaces old instances with new ones:
+
+1. Start new service instance
+2. Wait for health check to pass
+3. Switch traffic to new instance
+4. Stop old instance (if applicable)
+
+**Current Implementation**: Simplified - assumes service is already running and verifies health before proceeding.
+
+#### Blue-Green Deployment
+
+Maintains two identical environments:
+
+1. Deploy to "green" environment
+2. Run health checks on green
+3. Switch router/load balancer to green
+4. Keep blue as backup
+
+**Current Implementation**: Simplified - verifies service health before proceeding.
+
+**Key Functions**:
+- `deployService()`: Main deployment function (routes to strategy)
+- `rollingDeploy()`: Rolling deployment implementation
+- `blueGreenDeploy()`: Blue-green deployment implementation
+- `performHealthCheck()`: Checks service health endpoint
+- `waitForService()`: Waits for service to become healthy
+
+### 6. Health Check System
+
+**File**: `src/utils/deployment.ts`
+
+Health checks ensure services are ready before routing traffic:
+
+1. **Polling**: Checks health endpoint every 2 seconds
+2. **Timeout**: Stops checking after configured timeout
+3. **Validation**: Requires HTTP 200 response
+4. **Failure**: Throws error if service doesn't become healthy
+
+**Health Check Flow**:
+```
+Start deployment
+    ↓
+Wait 2 seconds
+    ↓
+GET /health endpoint
+    ↓
+Is response 200 OK?
+    ├─ Yes → Service healthy ✅
+    └─ No → Wait 2 seconds, retry
+            ↓
+        Timeout exceeded?
+        ├─ No → Retry
+        └─ Yes → Deployment failed ❌
+```
+
+## Command Implementations
+
+### `init` Command
+
+**File**: `src/commands/init.ts`
+
+Interactive configuration creation:
+1. Check if file exists (prompt for overwrite)
+2. Gather project information
+3. Loop through services:
+   - Service details
+   - Docker configuration
+   - Health check configuration
+4. Gather Certbot information
+5. Build configuration object
+6. Save to YAML file
+
+### `setup` Command
+
+**File**: `src/commands/setup.ts`
+
+Prerequisites installation:
+1. Detect operating system
+2. Check if Nginx installed → Install if needed
+3. Start and enable Nginx service
+4. Check if Certbot installed → Install if needed
+5. Verify installations
+
+### `deploy` Command
+
+**File**: `src/commands/deploy.ts`
+
+Main deployment orchestration:
+1. Load and validate configuration
+2. For each service:
+   a. Start Docker container (if configured)
+   b. Deploy service (using strategy)
+   c. Generate Nginx config (HTTP)
+   d. Enable Nginx site
+   e. Request SSL certificates (if HTTPS enabled)
+   f. Update Nginx config (HTTPS)
+   g. Reload Nginx
+   h. Perform health check
+3. Print service URLs
+
+## Data Flow
+
+### Deployment Flow
+
+```
+User runs: suthep deploy
+    ↓
+Load suthep.yml
+    ↓
+For each service:
+    ├─ Start Docker container
+    ├─ Deploy service (strategy)
+    ├─ Generate Nginx config
+    ├─ Enable Nginx site
+    ├─ Request SSL certificate
+    ├─ Update Nginx config (HTTPS)
+    ├─ Reload Nginx
+    └─ Health check
+    ↓
+All services deployed ✅
+```
+
+### Configuration Flow
+
+```
+suthep.yml (YAML)
+    ↓
+config-loader.ts (Load & Parse)
+    ↓
+TypeScript Types (Validate)
+    ↓
+Command Handlers (Use)
+    ↓
+Utility Functions (Execute)
+```
+
+## File System Structure
+
+Suthep creates and manages:
+
+```
+/etc/nginx/
+├── sites-available/
+│   ├── service1.conf  (Generated)
+│   └── service2.conf  (Generated)
+└── sites-enabled/
+    ├── service1.conf  (Symlink)
+    └── service2.conf  (Symlink)
+
+/etc/letsencrypt/
+├── live/
+│   ├── domain1.com/
+│   │   ├── fullchain.pem
+│   │   └── privkey.pem
+│   └── domain2.com/
+│       ├── fullchain.pem
+│       └── privkey.pem
+└── archive/  (Certificate history)
+```
+
+## Error Handling
+
+Suthep uses a fail-fast approach:
+- If any step fails, deployment stops
+- Detailed error messages are shown
+- Exit code 1 indicates failure
+- Previous successful steps remain in place
+
+## Security Considerations
+
+1. **sudo Access**: Required for Nginx and Certbot operations
+2. **SSL Certificates**: Stored in `/etc/letsencrypt/` (root access required)
+3. **Nginx Configs**: Written to system directories (sudo required)
+4. **Docker**: Runs with user permissions (no sudo needed)
+
+## Extensibility
+
+Suthep is designed to be extensible:
+
+1. **New Deployment Strategies**: Add to `deployment.ts`
+2. **New Service Types**: Extend `ServiceConfig` type
+3. **Custom Health Checks**: Modify `performHealthCheck()`
+4. **Additional Providers**: Add new managers (e.g., Traefik, Caddy)
+
+## Performance Considerations
+
+1. **Parallel Deployment**: Currently sequential (can be parallelized)
+2. **Health Check Polling**: 2-second intervals (configurable)
+3. **Nginx Reload**: Only once per service (could batch)
+4. **Certificate Requests**: Sequential per domain (rate limits apply)

package/docs/en/commands.md

@@ -0,0 +1,273 @@
+# Commands Reference
+
+Suthep provides three main commands for managing deployments. This document describes each command in detail.
+
+## `suthep init`
+
+Initialize a new deployment configuration file.
+
+### Usage
+
+```bash
+suthep init [options]
+```
+
+### Options
+
+| Option | Short | Description | Default |
+|--------|-------|-------------|---------|
+| `--file` | `-f` | Configuration file path | `suthep.yml` |
+
+### Description
+
+The `init` command interactively creates a `suthep.yml` configuration file. It will:
+
+1. Prompt for project name and version
+2. Guide you through configuring one or more services
+3. Ask about Docker configuration for each service
+4. Set up health check endpoints
+5. Configure Certbot email and staging mode
+6. Save the configuration to the specified file
+
+### Examples
+
+```bash
+# Create default suthep.yml
+suthep init
+
+# Create custom configuration file
+suthep init -f production.yml
+```
+
+### Interactive Prompts
+
+The command will ask you:
+
+1. **Project name**: Name of your project
+2. **Project version**: Version number
+3. **Service name**: Unique identifier for the service
+4. **Service port**: Port the service runs on (1-65535)
+5. **Domain names**: Comma-separated list of domains
+6. **Use Docker?**: Whether to use Docker
+7. **Docker image**: Image to use (optional, for new containers)
+8. **Container name**: Name of the Docker container
+9. **Container port**: Port inside the container
+10. **Add health check?**: Whether to configure health checks
+11. **Health check path**: HTTP path for health endpoint
+12. **Health check interval**: Check interval in seconds
+13. **Add another service?**: Whether to configure more services
+14. **Email for SSL certificates**: Email for Let's Encrypt
+15. **Use Certbot staging?**: Use staging environment for testing
+
+## `suthep setup`
+
+Setup Nginx and Certbot on the system.
+
+### Usage
+
+```bash
+suthep setup [options]
+```
+
+### Options
+
+| Option | Description |
+|--------|-------------|
+| `--nginx-only` | Only setup Nginx (skip Certbot) |
+| `--certbot-only` | Only setup Certbot (skip Nginx) |
+
+### Description
+
+The `setup` command installs and configures the prerequisites for Suthep:
+
+1. **Nginx Installation**:
+   - Checks if Nginx is already installed
+   - Installs Nginx using the appropriate package manager:
+     - `apt-get` on Debian/Ubuntu
+     - `yum` on RHEL/CentOS
+     - `brew` on macOS
+   - Starts and enables the Nginx service
+
+2. **Certbot Installation**:
+   - Checks if Certbot is already installed
+   - Installs Certbot and the Nginx plugin:
+     - `certbot` and `python3-certbot-nginx` on Linux
+     - `certbot` on macOS via Homebrew
+
+### Examples
+
+```bash
+# Setup both Nginx and Certbot
+suthep setup
+
+# Only setup Nginx
+suthep setup --nginx-only
+
+# Only setup Certbot
+suthep setup --certbot-only
+```
+
+### Platform Support
+
+- **Linux**: Supports Debian/Ubuntu (apt-get) and RHEL/CentOS (yum)
+- **macOS**: Uses Homebrew for installation
+- **Other platforms**: Will show an error message with manual installation instructions
+
+### Requirements
+
+- `sudo` access (for installing system packages)
+- Internet connection (to download packages)
+
+## `suthep deploy`
+
+Deploy a project using the configuration file.
+
+### Usage
+
+```bash
+suthep deploy [options]
+```
+
+### Options
+
+| Option | Short | Description | Default |
+|--------|-------|-------------|---------|
+| `--file` | `-f` | Configuration file path | `suthep.yml` |
+| `--no-https` | | Skip HTTPS setup | `false` |
+| `--no-nginx` | | Skip Nginx configuration | `false` |
+
+### Description
+
+The `deploy` command is the main deployment command. It performs the following steps for each service:
+
+1. **Load Configuration**: Reads and validates the configuration file
+2. **Docker Management**: Starts or connects to Docker containers (if configured)
+3. **Service Deployment**: Deploys the service using the configured strategy
+4. **Nginx Configuration**: Generates and enables Nginx reverse proxy configuration
+5. **SSL Certificate**: Requests SSL certificates from Let's Encrypt (if HTTPS enabled)
+6. **Nginx Reload**: Tests and reloads Nginx configuration
+7. **Health Check**: Performs health check to verify service is running
+
+### Deployment Flow
+
+For each service in your configuration:
+
+```
+1. Start Docker container (if configured)
+   ↓
+2. Deploy service (rolling or blue-green strategy)
+   ↓
+3. Generate Nginx configuration (HTTP)
+   ↓
+4. Enable Nginx site
+   ↓
+5. Request SSL certificates (if --no-https not used)
+   ↓
+6. Update Nginx configuration (HTTPS)
+   ↓
+7. Reload Nginx
+   ↓
+8. Perform health check (if configured)
+   ↓
+9. Service deployed successfully!
+```
+
+### Examples
+
+```bash
+# Deploy using default suthep.yml
+suthep deploy
+
+# Deploy using custom configuration file
+suthep deploy -f production.yml
+
+# Deploy without HTTPS (HTTP only)
+suthep deploy --no-https
+
+# Deploy without Nginx (only Docker/health checks)
+suthep deploy --no-nginx
+
+# Deploy without both HTTPS and Nginx
+suthep deploy --no-https --no-nginx
+```
+
+### Error Handling
+
+If any step fails, the deployment will:
+- Show a detailed error message
+- Exit with a non-zero status code
+- Not proceed with remaining services (if one fails)
+
+### Output
+
+The command provides detailed output including:
+- Configuration loading status
+- Service deployment progress
+- Docker container status
+- Nginx configuration status
+- SSL certificate status
+- Health check results
+- Final service URLs
+
+Example output:
+
+```
+🚀 Deploying Services
+
+📄 Loading configuration from suthep.yml...
+✅ Configuration loaded for project: my-app
+   Services: api, webapp
+
+📦 Deploying service: api
+  🐳 Managing Docker container...
+  ⚙️  Configuring Nginx reverse proxy...
+  ✅ Nginx configured for api.example.com
+  🔐 Setting up HTTPS certificates...
+  ✅ SSL certificate obtained for api.example.com
+  🔄 Reloading Nginx...
+  🏥 Performing health check...
+  ✅ Service api is healthy
+
+✨ Service api deployed successfully!
+
+🎉 All services deployed successfully!
+
+📋 Service URLs:
+   api: https://api.example.com
+```
+
+## Global Options
+
+All commands support these global options:
+
+| Option | Short | Description |
+|--------|-------|-------------|
+| `--version` | `-V` | Show version number |
+| `--help` | `-h` | Show help for command |
+
+### Examples
+
+```bash
+# Show version
+suthep --version
+
+# Show help for deploy command
+suthep deploy --help
+```
+
+## Exit Codes
+
+- `0`: Success
+- `1`: Error occurred (see error message for details)
+
+## Command Aliases
+
+After running `npm link`, the `suthep` command is available globally. You can also use it directly from the project directory:
+
+```bash
+# From project directory
+npm run dev -- deploy
+
+# Or after building
+node dist/index.js deploy
+```