suthep 0.1.0-beta.1

package/docs/en/port-binding.md

@@ -0,0 +1,268 @@
+# Port Binding Guide
+
+This guide explains how port binding works in Suthep when deploying Docker containers.
+
+## How Port Binding Works
+
+When you deploy a service with Docker, Suthep automatically binds ports between the host machine and the container using Docker's port mapping feature.
+
+### Port Mapping Format
+
+The port binding follows this format:
+```
+hostPort:containerPort
+```
+
+Where:
+- **hostPort** (`service.port`): The port on your host machine (accessible at `localhost:hostPort`)
+- **containerPort** (`service.docker.port`): The port inside the Docker container (what your application listens on)
+
+### Configuration
+
+In your `suthep.yml` file:
+
+```yaml
+services:
+  - name: api
+    port: 3001              # Host port (exposed on host machine)
+    docker:
+      image: myapp/api:latest
+      container: api-container
+      port: 3001            # Container port (inside the container)
+```
+
+This configuration creates a Docker port mapping: `3001:3001`
+
+### How It Works
+
+1. **Docker Command Generated**:
+   ```bash
+   docker run -d -p 3001:3001 --name api-container myapp/api:latest
+   ```
+
+2. **Port Mapping**:
+   - Traffic to `localhost:3001` on the host → forwarded to port `3001` inside the container
+   - Your application inside the container listens on port `3001`
+   - Nginx connects to `localhost:3001` to reach your service
+
+3. **Nginx Configuration**:
+   ```nginx
+   upstream api {
+       server localhost:3001;  # Connects to host port
+   }
+   ```
+
+## Common Scenarios
+
+### Same Port on Host and Container
+
+When your app listens on the same port inside and outside the container:
+
+```yaml
+- name: api
+  port: 3000              # Host: 3000
+  docker:
+    port: 3000            # Container: 3000
+```
+
+**Result**: `docker run -p 3000:3000 ...`
+
+### Different Ports (Host Port ≠ Container Port)
+
+When you want to expose a different host port than the container port:
+
+**Example: Bind host port 3002 to container port 3000**
+
+```yaml
+- name: api
+  port: 3002              # Host: 3002 (external, accessible at localhost:3002)
+  docker:
+    port: 3000            # Container: 3000 (internal, app listens on 3000 inside)
+```
+
+**Result**: `docker run -p 3002:3000 ...`
+- External access: `localhost:3002` → forwards to container port `3000`
+- Container internal: your app listens on port `3000`
+- Nginx connects to: `localhost:3002`
+
+**Another Example: Host 8080 → Container 80**
+
+```yaml
+- name: web
+  port: 8080              # Host: 8080 (external)
+  docker:
+    port: 80              # Container: 80 (internal, Nginx listens on 80)
+```
+
+**Result**: `docker run -p 8080:80 ...`
+- External access: `localhost:8080` → forwards to container port `80`
+- Container internal: Nginx listens on port `80`
+
+### Multiple Services on Same Domain
+
+When multiple services share a domain but use different ports:
+
+```yaml
+services:
+  - name: api
+    port: 3001            # Host port 3001
+    path: /api
+    domains:
+      - example.com
+    docker:
+      port: 3001          # Container port 3001
+
+  - name: ui
+    port: 3000            # Host port 3000
+    path: /
+    domains:
+      - example.com
+    docker:
+      port: 3000          # Container port 3000
+```
+
+**Result**:
+- API: `localhost:3001` → container port `3001`
+- UI: `localhost:3000` → container port `3000`
+- Nginx routes:
+  - `example.com/api/*` → `localhost:3001`
+  - `example.com/*` → `localhost:3000`
+
+## Port Conflict Detection
+
+Suthep automatically detects and prevents port conflicts:
+
+### Configuration Validation
+
+Before deployment, Suthep checks:
+- ✅ No two services use the same host port
+- ✅ No two Docker containers have the same name
+
+**Error Example**:
+```
+Port conflict: Service "api" uses port 3000 which is already used by: webapp.
+Each service must use a unique port.
+```
+
+### Runtime Port Check
+
+When creating containers, Suthep:
+1. Checks if the port is already bound by another container
+2. Catches Docker port binding errors
+3. Provides clear error messages
+
+**Error Example**:
+```
+Port 3000 is already in use by another container.
+Please use a different port for service "api".
+```
+
+## Advanced Port Binding
+
+### Binding to Specific Interface
+
+Currently, Suthep binds to all interfaces (`0.0.0.0`). To bind to a specific interface, you would need to modify the Docker command manually or use Docker Compose.
+
+### Port Range Binding
+
+For binding port ranges, you would need to use Docker Compose or modify the container creation manually.
+
+### UDP Ports
+
+Currently, Suthep only supports TCP ports. For UDP, you would need to manually configure Docker.
+
+## Troubleshooting
+
+### Port Already in Use
+
+**Problem**: `Port X is already in use`
+
+**Solutions**:
+1. Check what's using the port:
+   ```bash
+   sudo lsof -i :3000
+   # or
+   sudo netstat -tulpn | grep 3000
+   ```
+
+2. Stop the conflicting service or container
+3. Use a different port in your configuration
+
+### Container Port Mismatch
+
+**Problem**: Container can't be reached
+
+**Check**:
+1. Verify your app listens on the correct port inside the container
+2. Ensure `docker.port` matches your app's listening port
+3. Check container logs:
+   ```bash
+   docker logs container-name
+   ```
+
+### Port Not Accessible
+
+**Problem**: Can't access service on host port
+
+**Check**:
+1. Verify container is running:
+   ```bash
+   docker ps
+   ```
+
+2. Check port mapping:
+   ```bash
+   docker port container-name
+   ```
+
+3. Test connection:
+   ```bash
+   curl http://localhost:PORT
+   ```
+
+## Best Practices
+
+1. **Use Unique Host Ports**: Each service should use a unique host port
+2. **Match Container Ports**: Set `docker.port` to match what your app listens on inside the container
+3. **Document Port Usage**: Keep track of which ports are used by which services
+4. **Use High Ports for Development**: Use ports above 8000 for development to avoid conflicts
+5. **Check Before Deploying**: Verify ports aren't in use before deployment
+
+## Examples
+
+### Simple Node.js API
+
+```yaml
+- name: api
+  port: 3000
+  docker:
+    image: node:18
+    container: api-container
+    port: 3000  # App listens on 3000 inside container
+```
+
+### Nginx Web Server
+
+```yaml
+- name: web
+  port: 8080
+  docker:
+    image: nginx:alpine
+    container: web-container
+    port: 80    # Nginx listens on 80 inside container
+```
+
+**Result**: Host port `8080` → Container port `80`
+
+### PostgreSQL Database
+
+```yaml
+- name: db
+  port: 5432
+  docker:
+    image: postgres:15
+    container: postgres-container
+    port: 5432
+```
+
+**Result**: Host port `5432` → Container port `5432`

package/docs/en/troubleshooting.md

@@ -0,0 +1,441 @@
+# Troubleshooting
+
+This guide helps you resolve common issues when using Suthep.
+
+## Common Issues
+
+### Permission Denied Errors
+
+**Problem**: Getting "Permission denied" or "EACCES" errors.
+
+**Solutions**:
+1. Ensure you have `sudo` access:
+   ```bash
+   sudo -v
+   ```
+
+2. For Nginx operations, Suthep requires sudo. Make sure you're running commands that need it with appropriate permissions.
+
+3. Check file permissions:
+   ```bash
+   ls -la /etc/nginx/sites-available
+   ```
+
+### Nginx Not Found
+
+**Problem**: `nginx: command not found`
+
+**Solutions**:
+1. Run the setup command:
+   ```bash
+   suthep setup --nginx-only
+   ```
+
+2. If setup fails, install manually:
+   ```bash
+   # Ubuntu/Debian
+   sudo apt-get update
+   sudo apt-get install nginx
+
+   # RHEL/CentOS
+   sudo yum install nginx
+
+   # macOS
+   brew install nginx
+   ```
+
+3. Verify installation:
+   ```bash
+   nginx -v
+   ```
+
+### Certbot Not Found
+
+**Problem**: `certbot: command not found`
+
+**Solutions**:
+1. Run the setup command:
+   ```bash
+   suthep setup --certbot-only
+   ```
+
+2. If setup fails, install manually:
+   ```bash
+   # Ubuntu/Debian
+   sudo apt-get update
+   sudo apt-get install certbot python3-certbot-nginx
+
+   # RHEL/CentOS
+   sudo yum install certbot python3-certbot-nginx
+
+   # macOS
+   brew install certbot
+   ```
+
+3. Verify installation:
+   ```bash
+   certbot --version
+   ```
+
+### SSL Certificate Request Failed
+
+**Problem**: Certificate request fails with errors like "Failed to obtain SSL certificate"
+
+**Common Causes**:
+1. **Domain not pointing to server**: DNS not configured correctly
+2. **Port 80 blocked**: Firewall blocking HTTP traffic
+3. **Rate limits**: Too many certificate requests (use staging mode)
+4. **Domain already has certificate**: Certificate already exists
+
+**Solutions**:
+1. **Check DNS**:
+   ```bash
+   dig example.com
+   # Should return your server's IP
+   ```
+
+2. **Check firewall**:
+   ```bash
+   sudo ufw status
+   # Ensure ports 80 and 443 are open
+   sudo ufw allow 80
+   sudo ufw allow 443
+   ```
+
+3. **Use staging mode** for testing:
+   ```yaml
+   certbot:
+     staging: true
+   ```
+
+4. **Check existing certificates**:
+   ```bash
+   sudo certbot certificates
+   ```
+
+5. **Revoke and retry** (if needed):
+   ```bash
+   sudo certbot revoke -d example.com
+   ```
+
+### Nginx Configuration Test Fails
+
+**Problem**: `nginx -t` fails with syntax errors
+
+**Solutions**:
+1. Check the generated Nginx config:
+   ```bash
+   sudo cat /etc/nginx/sites-available/service-name.conf
+   ```
+
+2. Test Nginx configuration manually:
+   ```bash
+   sudo nginx -t
+   ```
+
+3. Check Nginx error logs:
+   ```bash
+   sudo tail -f /var/log/nginx/error.log
+   ```
+
+4. Common issues:
+   - Missing SSL certificates (if HTTPS enabled)
+   - Invalid domain names
+   - Port conflicts
+
+### Service Health Check Fails
+
+**Problem**: Health check times out or fails
+
+**Solutions**:
+1. **Verify service is running**:
+   ```bash
+   curl http://localhost:PORT/health
+   ```
+
+2. **Check service logs**:
+   ```bash
+   # For Docker containers
+   docker logs container-name
+
+   # For Node.js services
+   # Check your application logs
+   ```
+
+3. **Verify health check path**:
+   - Ensure the path in configuration matches your service endpoint
+   - Test the endpoint manually
+
+4. **Increase timeout**:
+   ```yaml
+   deployment:
+     healthCheckTimeout: 60000  # Increase to 60 seconds
+   ```
+
+5. **Check service is listening on correct port**:
+   ```bash
+   netstat -tuln | grep PORT
+   # or
+   ss -tuln | grep PORT
+   ```
+
+### Docker Container Issues
+
+**Problem**: Docker container fails to start or connect
+
+**Solutions**:
+1. **Check Docker is running**:
+   ```bash
+   docker ps
+   ```
+
+2. **Check container exists**:
+   ```bash
+   docker ps -a | grep container-name
+   ```
+
+3. **Check container logs**:
+   ```bash
+   docker logs container-name
+   ```
+
+4. **Verify port mapping**:
+   - Ensure host port doesn't conflict with other services
+   - Check if port is already in use:
+     ```bash
+     lsof -i :PORT
+     ```
+
+5. **Check Docker image exists**:
+   ```bash
+   docker images | grep image-name
+   ```
+
+6. **Pull image manually** (if needed):
+   ```bash
+   docker pull image-name:tag
+   ```
+
+### Domain Not Resolving
+
+**Problem**: Can't access service via domain name
+
+**Solutions**:
+1. **Check DNS configuration**:
+   ```bash
+   dig example.com
+   nslookup example.com
+   ```
+
+2. **Verify DNS points to server**:
+   - Check your DNS provider settings
+   - Ensure A record points to your server's IP
+
+3. **Test locally** (add to /etc/hosts for testing):
+   ```bash
+   sudo echo "127.0.0.1 example.com" >> /etc/hosts
+   ```
+
+4. **Check Nginx is serving the domain**:
+   ```bash
+   curl -H "Host: example.com" http://localhost
+   ```
+
+### Port Already in Use
+
+**Problem**: Port conflict errors
+
+**Solutions**:
+1. **Find what's using the port**:
+   ```bash
+   sudo lsof -i :PORT
+   # or
+   sudo netstat -tulpn | grep PORT
+   ```
+
+2. **Stop conflicting service** or change port in configuration
+
+3. **For Docker containers**, check if port mapping conflicts:
+   ```bash
+   docker ps | grep PORT
+   ```
+
+### Nginx Site Not Enabled
+
+**Problem**: Service not accessible even though deployment succeeded
+
+**Solutions**:
+1. **Check if site is enabled**:
+   ```bash
+   ls -la /etc/nginx/sites-enabled/ | grep service-name
+   ```
+
+2. **Manually enable site**:
+   ```bash
+   sudo ln -s /etc/nginx/sites-available/service-name.conf /etc/nginx/sites-enabled/
+   ```
+
+3. **Reload Nginx**:
+   ```bash
+   sudo nginx -t
+   sudo systemctl reload nginx
+   ```
+
+### Configuration File Not Found
+
+**Problem**: `Configuration file not found: suthep.yml`
+
+**Solutions**:
+1. **Check current directory**:
+   ```bash
+   pwd
+   ls -la suthep.yml
+   ```
+
+2. **Specify custom path**:
+   ```bash
+   suthep deploy -f /path/to/config.yml
+   ```
+
+3. **Create configuration**:
+   ```bash
+   suthep init
+   ```
+
+### Service Deployment Fails Midway
+
+**Problem**: Deployment fails for one service, affecting others
+
+**Solutions**:
+1. **Check error message** - it will indicate which service failed
+
+2. **Fix the issue** for the failing service
+
+3. **Redeploy**:
+   ```bash
+   suthep deploy
+   ```
+
+4. **Note**: Suthep uses fail-fast, so if one service fails, deployment stops. Previous services remain deployed.
+
+### SSL Certificate Expired
+
+**Problem**: SSL certificate has expired
+
+**Solutions**:
+1. **Check certificate expiration**:
+   ```bash
+   sudo certbot certificates
+   ```
+
+2. **Renew certificates**:
+   ```bash
+   sudo certbot renew
+   ```
+
+3. **Set up auto-renewal** (recommended):
+   ```bash
+   # Add to crontab
+   sudo crontab -e
+   # Add: 0 0 * * * certbot renew --quiet
+   ```
+
+### Multiple Services on Same Port
+
+**Problem**: Two services configured with the same port
+
+**Solutions**:
+1. **Use different ports** for each service:
+   ```yaml
+   services:
+     - name: api
+       port: 3000
+     - name: webapp
+       port: 3001  # Different port
+   ```
+
+2. **Use Docker port mapping** to map different host ports to same container port
+
+## Debugging Tips
+
+### Enable Verbose Logging
+
+Check Nginx and application logs:
+
+```bash
+# Nginx access logs
+sudo tail -f /var/log/nginx/service-name_access.log
+
+# Nginx error logs
+sudo tail -f /var/log/nginx/service-name_error.log
+
+# Nginx general error log
+sudo tail -f /var/log/nginx/error.log
+```
+
+### Test Nginx Configuration
+
+```bash
+# Test configuration syntax
+sudo nginx -t
+
+# Test specific config file
+sudo nginx -t -c /etc/nginx/sites-available/service-name.conf
+```
+
+### Verify Service Endpoints
+
+```bash
+# Test health endpoint
+curl http://localhost:PORT/health
+
+# Test main endpoint
+curl http://localhost:PORT/
+
+# Test via domain (if DNS configured)
+curl http://example.com
+```
+
+### Check Docker Status
+
+```bash
+# List all containers
+docker ps -a
+
+# Check container status
+docker inspect container-name
+
+# View container logs
+docker logs -f container-name
+```
+
+### Verify SSL Certificates
+
+```bash
+# List all certificates
+sudo certbot certificates
+
+# Check certificate details
+sudo openssl x509 -in /etc/letsencrypt/live/domain.com/cert.pem -text -noout
+```
+
+## Getting Help
+
+If you're still experiencing issues:
+
+1. **Check logs**: Review Nginx, Docker, and application logs
+2. **Verify configuration**: Ensure `suthep.yml` is valid YAML
+3. **Test components individually**: Test Nginx, Certbot, and Docker separately
+4. **Review documentation**: Check [Configuration Reference](./configuration.md) and [Examples](./examples.md)
+5. **Check system requirements**: Ensure all prerequisites are installed
+
+## Prevention
+
+To avoid common issues:
+
+1. **Use staging certificates** during development
+2. **Test health endpoints** before deployment
+3. **Verify DNS** before requesting certificates
+4. **Check port availability** before deployment
+5. **Backup configurations** before making changes
+6. **Monitor logs** during and after deployment