suthep 0.1.0 → 0.2.0-beta.1

package/docs/architecture.md

@@ -1,367 +0,0 @@
-# Architecture
-
-This document explains how Suthep works under the hood, including its components, deployment strategies, and internal architecture.
-
-## 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/commands.md

@@ -1,273 +0,0 @@
-# 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
-```