suthep 0.1.0-beta.1 → 0.2.0-beta.1

package/docs/english/03-quick-start.md

@@ -0,0 +1,256 @@
+# Quick Start Guide
+
+This guide will help you deploy your first service with Suthep in just a few minutes.
+
+## Step 1: Initialize Configuration
+
+Create a new configuration file interactively:
+
+```bash
+suthep init
+```
+
+This command will prompt you for:
+- Project name and version
+- Service details (name, port, domains)
+- Docker configuration (if needed)
+- Health check settings
+- SSL certificate email
+
+Alternatively, you can copy the example configuration:
+
+```bash
+cp suthep.example.yml suthep.yml
+```
+
+Then edit `suthep.yml` with your settings.
+
+## Step 2: Setup Prerequisites
+
+Install and configure Nginx and Certbot:
+
+```bash
+suthep setup
+```
+
+This will:
+- Install Nginx (if not already installed)
+- Install Certbot (if not already installed)
+- Configure system dependencies
+
+**Note:** This command requires sudo privileges.
+
+## Step 3: Deploy Your Service
+
+Deploy your project:
+
+```bash
+suthep deploy
+```
+
+This command will:
+1. Configure Nginx reverse proxy for all services
+2. Obtain SSL certificates via Certbot (if enabled)
+3. Deploy services with zero-downtime strategy
+
+## Example: Deploying a Simple API
+
+Let's walk through deploying a Node.js API service:
+
+### 1. Create Configuration
+
+Create `suthep.yml`:
+
+```yaml
+project:
+  name: my-api
+  version: 1.0.0
+
+services:
+  - name: api
+    port: 3000
+    domains:
+      - api.example.com
+    healthCheck:
+      path: /health
+      interval: 30
+    environment:
+      NODE_ENV: production
+
+nginx:
+  configPath: /etc/nginx/sites-available
+  reloadCommand: sudo nginx -t && sudo systemctl reload nginx
+
+certbot:
+  email: admin@example.com
+  staging: false
+
+deployment:
+  strategy: rolling
+  healthCheckTimeout: 30000
+```
+
+### 2. Setup Prerequisites
+
+```bash
+suthep setup
+```
+
+### 3. Deploy
+
+```bash
+suthep deploy
+```
+
+### 4. Verify Deployment
+
+After deployment, Suthep will display service URLs:
+
+```
+📋 Service URLs:
+   api: https://api.example.com
+```
+
+Visit the URL in your browser to verify the service is running.
+
+## Example: Deploying a Docker Container
+
+To deploy a Docker container:
+
+```yaml
+services:
+  - name: webapp
+    port: 8080
+    docker:
+      image: nginx:latest
+      container: webapp-container
+      port: 80
+    domains:
+      - example.com
+      - www.example.com
+```
+
+Then run:
+
+```bash
+suthep deploy
+```
+
+## Common Commands
+
+### Check Service Status
+
+```bash
+# View Nginx configuration
+sudo nginx -t
+
+# Check running containers
+docker ps
+
+# View service logs
+docker logs <container-name>
+```
+
+### Update Configuration
+
+1. Edit `suthep.yml`
+2. Redeploy:
+   ```bash
+   suthep redeploy
+   ```
+
+### Stop Services
+
+```bash
+# Stop a specific service
+suthep down <service-name>
+
+# Stop all services
+suthep down --all
+```
+
+### Start Services
+
+```bash
+# Start a specific service
+suthep up <service-name>
+
+# Start all services
+suthep up --all
+```
+
+## What Happens During Deployment?
+
+When you run `suthep deploy`, Suthep:
+
+1. **Loads Configuration** - Reads your `suthep.yml` file
+2. **Starts Docker Containers** - If Docker is configured, starts containers
+3. **Configures Nginx** - Generates and writes Nginx configuration files
+4. **Enables Sites** - Creates symlinks to enable Nginx sites
+5. **Obtains SSL Certificates** - Requests certificates from Let's Encrypt
+6. **Updates Nginx for HTTPS** - Adds SSL configuration to Nginx
+7. **Reloads Nginx** - Applies all changes
+8. **Performs Health Checks** - Verifies services are running correctly
+
+## Troubleshooting Quick Start
+
+### Domain Not Resolving
+
+Ensure your domain points to your server:
+
+```bash
+# Check DNS
+nslookup api.example.com
+
+# Verify server IP matches
+curl -I http://api.example.com
+```
+
+### Port Already in Use
+
+If you get a "port already in use" error:
+
+1. **Find what's using the port:**
+   ```bash
+   sudo lsof -i :3000
+   ```
+
+2. **Stop the conflicting service** or **change the port** in `suthep.yml`
+
+### SSL Certificate Issues
+
+If SSL certificate creation fails:
+
+1. **Check domain DNS** - Ensure domain points to your server
+2. **Use staging mode** for testing:
+   ```yaml
+   certbot:
+     staging: true
+   ```
+
+3. **Check firewall** - Ensure ports 80 and 443 are open
+
+### Nginx Configuration Errors
+
+If Nginx fails to reload:
+
+```bash
+# Test Nginx configuration
+sudo nginx -t
+
+# Check Nginx error logs
+sudo tail -f /var/log/nginx/error.log
+```
+
+## Next Steps
+
+Now that you've deployed your first service:
+
+- [Configuration Guide](./04-configuration.md) - Learn about all configuration options
+- [Commands Reference](./05-commands.md) - Explore all available commands
+- [Examples](./06-examples.md) - See more deployment examples
+
+---
+
+**Previous:** [Installation](./02-installation.md) | **Next:** [Configuration Guide →](./04-configuration.md)
+

package/docs/english/04-configuration.md

@@ -0,0 +1,358 @@
+# Configuration Guide
+
+This guide covers all configuration options available in Suthep's `suthep.yml` file.
+
+## Configuration File Structure
+
+The `suthep.yml` file uses YAML format and consists of several sections:
+
+```yaml
+project:
+  # Project metadata
+
+services:
+  # Service definitions
+
+nginx:
+  # Nginx configuration
+
+certbot:
+  # SSL certificate configuration
+
+deployment:
+  # Deployment strategy settings
+```
+
+## Project Configuration
+
+The `project` section contains metadata about your project:
+
+```yaml
+project:
+  name: my-app        # Project name
+  version: 1.0.0      # Project version
+```
+
+### Fields
+
+| Field | Required | Description |
+|-------|----------|-------------|
+| `name` | Yes | Unique identifier for your project |
+| `version` | Yes | Project version (for tracking) |
+
+## Services Configuration
+
+The `services` array defines all services to deploy. Each service can have multiple configurations.
+
+### Basic Service
+
+```yaml
+services:
+  - name: api
+    port: 3000
+    domains:
+      - api.example.com
+```
+
+### Service Fields
+
+| Field | Required | Type | Description |
+|-------|----------|------|-------------|
+| `name` | Yes | string | Unique service identifier |
+| `port` | Yes | number | Port number the service runs on (host port) |
+| `domains` | Yes | array | Array of domain names for this service |
+| `path` | No | string | URL path prefix (default: `/`) |
+| `docker` | No | object | Docker configuration (see below) |
+| `healthCheck` | No | object | Health check configuration (see below) |
+| `environment` | No | object | Environment variables as key-value pairs |
+
+### Docker Configuration
+
+Configure Docker container deployment:
+
+```yaml
+services:
+  - name: webapp
+    port: 8080
+    docker:
+      image: nginx:latest        # Docker image to pull
+      container: webapp-container # Container name
+      port: 80                    # Container internal port
+```
+
+#### Docker Fields
+
+| Field | Required | Description |
+|-------|----------|-------------|
+| `image` | No* | Docker image to pull and run |
+| `container` | Yes | Name for the Docker container |
+| `port` | Yes | Internal port the container listens on |
+
+\* `image` is optional if connecting to an existing container.
+
+#### Connect to Existing Container
+
+To connect to an already running container, omit the `image` field:
+
+```yaml
+services:
+  - name: database-proxy
+    port: 5432
+    docker:
+      container: postgres-container
+      port: 5432
+```
+
+### Health Check Configuration
+
+Configure health monitoring for your service:
+
+```yaml
+services:
+  - name: api
+    healthCheck:
+      path: /health      # Health check endpoint
+      interval: 30       # Check interval in seconds
+```
+
+#### Health Check Fields
+
+| Field | Required | Default | Description |
+|-------|----------|---------|-------------|
+| `path` | Yes | - | HTTP endpoint path for health checks |
+| `interval` | No | 30 | Time between health checks (seconds) |
+
+### Environment Variables
+
+Set environment variables for your service:
+
+```yaml
+services:
+  - name: api
+    environment:
+      NODE_ENV: production
+      DATABASE_URL: postgresql://localhost:5432/mydb
+      API_KEY: your-api-key
+```
+
+### Path-Based Routing
+
+Route different services on the same domain using paths:
+
+```yaml
+services:
+  # API service on /api path
+  - name: api
+    port: 3001
+    path: /api
+    domains:
+      - example.com
+
+  # UI service on root path
+  - name: ui
+    port: 3000
+    path: /
+    domains:
+      - example.com
+```
+
+## Nginx Configuration
+
+Configure Nginx settings:
+
+```yaml
+nginx:
+  configPath: /etc/nginx/sites-available
+  reloadCommand: sudo nginx -t && sudo systemctl reload nginx
+```
+
+### Nginx Fields
+
+| Field | Required | Default | Description |
+|-------|----------|---------|-------------|
+| `configPath` | No | `/etc/nginx/sites-available` | Path where Nginx configs are stored |
+| `reloadCommand` | No | `sudo nginx -t && sudo systemctl reload nginx` | Command to reload Nginx |
+
+## Certbot Configuration
+
+Configure SSL certificate settings:
+
+```yaml
+certbot:
+  email: admin@example.com  # Email for Let's Encrypt
+  staging: false            # Use staging environment (for testing)
+```
+
+### Certbot Fields
+
+| Field | Required | Description |
+|-------|----------|-------------|
+| `email` | Yes | Email address for Let's Encrypt notifications |
+| `staging` | No | Use staging environment (default: `false`) |
+
+**Note:** Use `staging: true` for testing to avoid rate limits.
+
+## Deployment Configuration
+
+Configure deployment strategy:
+
+```yaml
+deployment:
+  strategy: rolling              # Deployment strategy
+  healthCheckTimeout: 30000      # Health check timeout (ms)
+```
+
+### Deployment Fields
+
+| Field | Required | Default | Description |
+|-------|----------|---------|-------------|
+| `strategy` | No | `rolling` | Deployment strategy (`rolling` or `blue-green`) |
+| `healthCheckTimeout` | No | `30000` | Maximum time to wait for health check (milliseconds) |
+
+### Deployment Strategies
+
+#### Rolling Deployment
+
+Gradually replaces old containers with new ones:
+
+```yaml
+deployment:
+  strategy: rolling
+```
+
+#### Blue-Green Deployment
+
+Creates new containers, switches traffic, then removes old containers:
+
+```yaml
+deployment:
+  strategy: blue-green
+```
+
+## Complete Configuration Example
+
+Here's a complete example with all options:
+
+```yaml
+project:
+  name: my-app
+  version: 1.0.0
+
+services:
+  # Simple API service
+  - name: api
+    port: 3000
+    domains:
+      - api.example.com
+    healthCheck:
+      path: /health
+      interval: 30
+    environment:
+      NODE_ENV: production
+
+  # Docker webapp
+  - name: webapp
+    port: 8080
+    docker:
+      image: nginx:latest
+      container: webapp-container
+      port: 80
+    domains:
+      - example.com
+      - www.example.com
+    healthCheck:
+      path: /
+      interval: 30
+
+  # Multiple services on same domain
+  - name: api-v2
+    port: 3001
+    path: /api
+    domains:
+      - example.com
+    docker:
+      image: myapp/api:latest
+      container: api-v2-container
+      port: 3001
+
+nginx:
+  configPath: /etc/nginx/sites-available
+  reloadCommand: sudo nginx -t && sudo systemctl reload nginx
+
+certbot:
+  email: admin@example.com
+  staging: false
+
+deployment:
+  strategy: rolling
+  healthCheckTimeout: 30000
+```
+
+## Configuration Best Practices
+
+### 1. Use Descriptive Service Names
+
+```yaml
+# Good
+- name: user-api
+- name: payment-service
+
+# Avoid
+- name: service1
+- name: app
+```
+
+### 2. Set Appropriate Health Check Intervals
+
+```yaml
+# For critical services
+healthCheck:
+  interval: 15  # Check every 15 seconds
+
+# For less critical services
+healthCheck:
+  interval: 60  # Check every minute
+```
+
+### 3. Use Staging for Testing
+
+```yaml
+certbot:
+  staging: true  # Use staging for testing
+```
+
+### 4. Organize Services by Domain
+
+Group related services together in your configuration:
+
+```yaml
+services:
+  # API services
+  - name: api
+    domains: [api.example.com]
+  - name: api-v2
+    domains: [api-v2.example.com]
+
+  # Web services
+  - name: webapp
+    domains: [example.com, www.example.com]
+```
+
+## Validation
+
+Suthep validates your configuration before deployment. Common validation errors:
+
+- **Missing required fields** - Ensure all required fields are present
+- **Invalid port numbers** - Ports must be between 1 and 65535
+- **Duplicate service names** - Each service must have a unique name
+- **Invalid domain format** - Domains must be valid hostnames
+
+## Next Steps
+
+- [Commands Reference](./05-commands.md) - Learn about all available commands
+- [Examples](./06-examples.md) - See real-world configuration examples
+
+---
+
+**Previous:** [Quick Start](./03-quick-start.md) | **Next:** [Commands Reference →](./05-commands.md)
+