suthep 0.1.0 → 0.2.0-beta.1

package/docs/troubleshooting.md

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

package/example/docker-compose.yml

@@ -1,72 +0,0 @@
-version: "3.8"
-
-services:
-  # Example 2: Docker container service from example.yml
-  webapp:
-    image: nginx:latest
-    container_name: webapp-container
-    ports:
-      - "8080:80"
-    networks:
-      - suthep-network
-    healthcheck:
-      test: ["CMD", "curl", "-f", "http://localhost/"]
-      interval: 30s
-      timeout: 10s
-      retries: 3
-    restart: unless-stopped
-
-  # Example 3: Multiple subdomains with Docker from example.yml
-  dashboard:
-    image: myapp/dashboard:latest
-    container_name: dashboard-container
-    ports:
-      - "5000:5000"
-    networks:
-      - suthep-network
-    environment:
-      DATABASE_URL: postgresql://postgres:5432/dashboard
-      REDIS_URL: redis://redis:6379
-    healthcheck:
-      test: ["CMD", "curl", "-f", "http://localhost:5000/api/health"]
-      interval: 60s
-      timeout: 10s
-      retries: 3
-    depends_on:
-      - postgres
-      - redis
-    restart: unless-stopped
-
-  # Database service for database-proxy example
-  postgres:
-    image: postgres:latest
-    container_name: postgres-container
-    ports:
-      - "5432:5432"
-    networks:
-      - suthep-network
-    environment:
-      POSTGRES_DB: dashboard
-      POSTGRES_USER: postgres
-      POSTGRES_PASSWORD: postgres
-    volumes:
-      - postgres-data:/var/lib/postgresql/data
-    restart: unless-stopped
-
-  # Redis service for dashboard
-  redis:
-    image: redis:latest
-    container_name: redis-container
-    ports:
-      - "6379:6379"
-    networks:
-      - suthep-network
-    restart: unless-stopped
-
-networks:
-  suthep-network:
-    driver: bridge
-
-volumes:
-  postgres-data:
-

package/example/suthep.yml

@@ -1,31 +0,0 @@
-project:
-  name: my-app
-  version: 1.0.0
-
-services:
-
-  # Example 2: Docker container service
-  - name: webapp
-    port: 3000
-    docker:
-      image: frontend-api:latest
-      container: webapp-container
-      port: 80
-    domains:
-      - example.com
-      - www.example.com
-    healthCheck:
-      path: /
-      interval: 30
-
-nginx:
-  configPath: /etc/nginx/sites-available
-  reloadCommand: sudo nginx -t && sudo systemctl reload nginx
-
-certbot:
-  email: admin@example.com
-  staging: true  # Set to true for testing
-
-deployment:
-  strategy: rolling  # Options: rolling, blue-green
-  healthCheckTimeout: 30000  # milliseconds