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

package/example/README.md

@@ -1,85 +1,314 @@
-# Local Docker Setup
+# Suthep Configuration Examples
 
-This directory contains configuration files for running services locally with Docker.
+This directory contains comprehensive examples showing how to configure Suthep for various deployment scenarios.
 
-## Files
+## Directory Structure
 
-- `example.yml` - Suthep deployment configuration
-- `docker-compose.yml` - Docker Compose configuration for local development
+```
+example/
+├── services/              # Individual service configurations
+│   ├── api-no-docker.yml           # Service without Docker container
+│   ├── webapp-docker.yml           # Service with Docker image
+│   ├── dashboard-docker.yml        # Service with Docker + environment variables
+│   ├── database-proxy.yml          # Connecting to existing Docker container
+│   ├── api-path-routing.yml        # API service with path-based routing
+│   └── ui-path-routing.yml         # UI service with path-based routing
+├── configs/               # Complete configuration files
+│   ├── suthep-complete.yml         # All service types combined
+│   ├── suthep-no-docker.yml        # Services without Docker
+│   ├── suthep-docker-only.yml      # All Docker services
+│   └── suthep-path-routing.yml     # Path-based routing example
+├── nginx/                 # Nginx configuration examples
+│   ├── nginx-template.conf         # Single service template
+│   └── nginx-multi-service.conf    # Multi-service template
+├── docker/                # Docker-related examples
+│   ├── docker-compose.example.yml  # Docker Compose example
+│   └── Dockerfile.example          # Example Dockerfile
+└── README.md              # This file
+```
 
-## Quick Start
+## Service Types
 
-To run the services locally with Docker Compose:
+### 1. Services Without Docker
 
-```bash
-# Start all services
-docker-compose up -d
+These services run directly on the host machine (managed by PM2, systemd, supervisor, etc.).
+
+**Example:** `services/api-no-docker.yml`
+
+```yaml
+- name: api
+  port: 3000
+  domains:
+    - api.example.com
+  healthCheck:
+    path: /health
+    interval: 30
+```
+
+**Use Cases:**
+- Node.js apps managed by PM2
+- Python apps with Gunicorn/systemd
+- Go binaries running as systemd services
+- Any process listening on a specific port
+
+### 2. Services With Docker Image
 
-# View logs
-docker-compose logs -f
+Suthep will pull the image and create a new container.
 
-# Stop all services
-docker-compose down
+**Example:** `services/webapp-docker.yml`
 
-# Stop and remove volumes
-docker-compose down -v
+```yaml
+- name: webapp
+  port: 8080
+  docker:
+    image: nginx:latest
+    container: webapp-container
+    port: 80
+  domains:
+    - example.com
 ```
 
-## Services
+**Use Cases:**
+- Applications packaged as Docker images
+- Third-party services from Docker Hub
+- Services that need containerization
 
-Based on `example.yml`, this Docker Compose file includes:
+### 3. Services Connecting to Existing Containers
 
-1. **webapp** (port 8080)
-   - Image: `nginx:latest`
-   - Container: `webapp-container`
-   - Maps to container port 80
+Connect to containers already running (e.g., from docker-compose).
 
-2. **dashboard** (port 5000)
-   - Image: `myapp/dashboard:latest` (you may need to build this)
-   - Container: `dashboard-container`
-   - Environment variables: `DATABASE_URL`, `REDIS_URL`
+**Example:** `services/database-proxy.yml`
 
-3. **postgres** (port 5432)
-   - Image: `postgres:latest`
-   - Container: `postgres-container`
-   - Database: `dashboard`
-   - Default credentials: `postgres/postgres`
+```yaml
+- name: database-proxy
+  port: 5432
+  docker:
+    container: postgres-container
+    port: 5432
+  domains:
+    - db.example.com
+```
+
+**Use Cases:**
+- Containers managed by docker-compose
+- Pre-existing containers
+- Infrastructure services (databases, Redis, etc.)
+
+### 4. Path-Based Routing
+
+Multiple services on the same domain using different paths.
+
+**Example:** `services/api-path-routing.yml` + `services/ui-path-routing.yml`
+
+```yaml
+# API on /api path
+- name: api
+  port: 3001
+  path: /api
+  domains:
+    - muacle.com
+
+# UI on root path
+- name: ui
+  port: 3000
+  path: /
+  domains:
+    - muacle.com
+```
 
-4. **redis** (port 6379)
-   - Image: `redis:latest`
-   - Container: `redis-container`
+**Use Cases:**
+- Monorepo deployments
+- Microservices on single domain
+- API + UI on same domain
 
-## Notes
+## Complete Configuration Examples
 
-- The **api** service from `example.yml` is not included here as it's a Node.js service (not Docker-based)
-- All services are connected via a Docker network named `suthep-network`
-- The dashboard service depends on postgres and redis, so they will start in order
-- PostgreSQL data is persisted in a Docker volume
+### Complete Example
+**File:** `configs/suthep-complete.yml`
 
-## Building Custom Images
+Combines all service types in a single configuration. Great for understanding all options.
 
-If you need to build the dashboard image:
+### No Docker Example
+**File:** `configs/suthep-no-docker.yml`
+
+All services run directly on the host. Perfect for traditional deployments without containerization.
+
+### Docker Only Example
+**File:** `configs/suthep-docker-only.yml`
+
+All services are Docker containers. Ideal for fully containerized architectures.
+
+### Path Routing Example
+**File:** `configs/suthep-path-routing.yml`
+
+Shows how to route multiple services on the same domain using paths.
+
+## Using the Examples
+
+### Option 1: Copy a Complete Config
 
 ```bash
-# Build the dashboard image
-docker build -t myapp/dashboard:latest ./path-to-dashboard
+# Copy a complete example
+cp example/configs/suthep-complete.yml suthep.yml
+
+# Edit with your settings
+nano suthep.yml
 
-# Or update the docker-compose.yml to build from source:
-# dashboard:
-#   build: ./path-to-dashboard
-#   ...
+# Deploy
+suthep deploy
 ```
 
-## Accessing Services
+### Option 2: Build from Individual Services
 
-Once running, services are available at:
+```bash
+# Create your config file
+cat > suthep.yml << EOF
+project:
+  name: my-app
+  version: 1.0.0
+
+services:
+EOF
+
+# Add services from examples
+cat example/services/api-no-docker.yml >> suthep.yml
+cat example/services/webapp-docker.yml >> suthep.yml
+
+# Add nginx and certbot config
+cat >> suthep.yml << EOF
 
-- Webapp: http://localhost:8080
-- Dashboard: http://localhost:5000
-- PostgreSQL: localhost:5432
-- Redis: localhost:6379
+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
+EOF
+
+# Deploy
+suthep deploy
+```
+
+### Option 3: Mix and Match
+
+Combine individual service examples to create your custom configuration:
+
+```bash
+# Start with project header
+cat > suthep.yml << EOF
+project:
+  name: my-custom-app
+  version: 1.0.0
+
+services:
+EOF
+
+# Add specific services you need
+cat example/services/api-no-docker.yml >> suthep.yml
+cat example/services/database-proxy.yml >> suthep.yml
+
+# Add standard config
+cat >> suthep.yml << EOF
+
+nginx:
+  configPath: /etc/nginx/sites-available
+  reloadCommand: sudo nginx -t && sudo systemctl reload nginx
+
+certbot:
+  email: your-email@example.com
+  staging: false
+
+deployment:
+  strategy: rolling
+  healthCheckTimeout: 30000
+EOF
+```
+
+## Additional Files
+
+### Nginx Templates
+
+The `nginx/` directory contains example configurations that Suthep generates automatically. You typically don't need to edit these manually, but they're useful for understanding how Suthep configures Nginx.
+
+### Docker Examples
+
+The `docker/` directory contains:
+- `docker-compose.example.yml`: Shows how to run containers that Suthep can connect to
+- `Dockerfile.example`: Example Dockerfile for building your application images
+
+## Configuration Reference
+
+### Service Configuration
+
+| Property | Required | Description |
+|----------|----------|-------------|
+| `name` | ✅ | Unique identifier for the service |
+| `port` | ✅ | Port number the service runs on (host port) |
+| `domains` | ✅ | Array of domain names or subdomains |
+| `docker` | ❌ | Docker configuration (see below) |
+| `path` | ❌ | Path prefix (e.g., `/api`, `/`). Defaults to `/` |
+| `healthCheck` | ❌ | Health check configuration |
+| `environment` | ❌ | Environment variables (key-value pairs) |
+
+### Docker Configuration
+
+When using Docker:
+
+```yaml
+docker:
+  image: nginx:latest      # Image to pull (required if creating new container)
+  container: my-container  # Container name (required)
+  port: 80                 # Internal container port (required)
+```
+
+- **With image**: Suthep creates a new container from the image
+- **Without image**: Suthep connects to an existing container
+
+### Health Check Configuration
+
+```yaml
+healthCheck:
+  path: /health        # HTTP endpoint path
+  interval: 30         # Check interval in seconds
+```
+
+### Deployment Configuration
+
+```yaml
+deployment:
+  strategy: rolling              # Options: rolling, blue-green
+  healthCheckTimeout: 30000      # Timeout in milliseconds
+```
+
+## Quick Start
 
+1. **Choose an example** from `configs/` or build from `services/`
+2. **Copy to `suthep.yml`** in your project root
+3. **Edit the configuration** with your actual domains and settings
+4. **Run setup** (first time only):
+   ```bash
+   suthep setup
+   ```
+5. **Deploy**:
+   ```bash
+   suthep deploy
+   ```
 
+## Tips
 
+- **Testing**: Set `certbot.staging: true` when testing to avoid rate limits
+- **Path Routing**: Order matters - most specific paths should be defined first
+- **Existing Containers**: Ensure containers are running and accessible before deployment
+- **Port Conflicts**: Each service must use a unique port
+- **Container Names**: Each Docker container must have a unique name
 
+## Need Help?
 
+- Check the main [README.md](../README.md) for command reference
+- Review the [suthep.example.yml](../suthep.example.yml) in the project root
+- See individual service examples in `services/` for specific use cases

package/example/suthep-complete.yml

@@ -0,0 +1,103 @@
+# Complete Example Configuration
+# This combines all service types for a comprehensive deployment
+
+project:
+  name: my-app
+  version: 1.0.0
+
+services:
+  # Service 1: Simple API without Docker (runs directly on host)
+  - name: api
+    port: 3000
+    domains:
+      - api.example.com
+      - www.api.example.com
+    healthCheck:
+      path: /health
+      interval: 30
+    environment:
+      NODE_ENV: production
+      PORT: 3000
+
+  # Service 2: Web application with Docker image
+  - name: webapp
+    port: 8080
+    docker:
+      image: nginx:latest
+      container: webapp-container
+      port: 80
+    domains:
+      - example.com
+      - www.example.com
+    healthCheck:
+      path: /
+      interval: 30
+
+  # Service 3: Dashboard with Docker and environment variables
+  - name: dashboard
+    port: 5000
+    docker:
+      image: myapp/dashboard:latest
+      container: dashboard-container
+      port: 5000
+    domains:
+      - dashboard.example.com
+      - admin.example.com
+    healthCheck:
+      path: /api/health
+      interval: 60
+    environment:
+      DATABASE_URL: postgresql://localhost:5432/dashboard
+      REDIS_URL: redis://localhost:6379
+
+  # Service 4: Connect to existing Docker container
+  - name: database-proxy
+    port: 5432
+    docker:
+      container: postgres-container
+      port: 5432
+    domains:
+      - db.example.com
+
+  # Service 5: Path-based routing - API on /api path
+  - name: api-v2
+    port: 3001
+    path: /api
+    domains:
+      - muacle.com
+    docker:
+      image: myapp/api:latest
+      container: api-v2-container
+      port: 3001
+    healthCheck:
+      path: /health
+      interval: 30
+
+  # Service 6: Path-based routing - UI on root path
+  - name: ui
+    port: 3000
+    path: /
+    domains:
+      - muacle.com
+    docker:
+      image: myapp/ui:latest
+      container: ui-container
+      port: 3000
+    healthCheck:
+      path: /
+      interval: 30
+
+# Nginx Configuration
+nginx:
+  configPath: /etc/nginx/sites-available
+  reloadCommand: sudo nginx -t && sudo systemctl reload nginx
+
+# Certbot Configuration (SSL/TLS certificates)
+certbot:
+  email: admin@example.com
+  staging: false  # Set to true for testing
+
+# Deployment Strategy
+deployment:
+  strategy: rolling  # Options: rolling, blue-green
+  healthCheckTimeout: 30000  # milliseconds

package/example/suthep-docker-only.yml

@@ -0,0 +1,71 @@
+# Example: Configuration with Docker Only
+# All services are deployed as Docker containers
+
+project:
+  name: docker-app
+  version: 1.0.0
+
+services:
+  # Frontend application
+  - name: frontend
+    port: 3000
+    docker:
+      image: myapp/frontend:latest
+      container: frontend-container
+      port: 3000
+    domains:
+      - example.com
+      - www.example.com
+    healthCheck:
+      path: /
+      interval: 30
+
+  # Backend API
+  - name: backend
+    port: 4000
+    docker:
+      image: myapp/backend:latest
+      container: backend-container
+      port: 4000
+    domains:
+      - api.example.com
+    healthCheck:
+      path: /api/health
+      interval: 30
+    environment:
+      NODE_ENV: production
+      DATABASE_URL: postgresql://db:5432/mydb
+
+  # Worker service
+  - name: worker
+    port: 5000
+    docker:
+      image: myapp/worker:latest
+      container: worker-container
+      port: 5000
+    domains:
+      - worker.example.com
+    healthCheck:
+      path: /health
+      interval: 60
+
+  # Redis proxy (connecting to existing container)
+  - name: redis-proxy
+    port: 6379
+    docker:
+      container: redis-container
+      port: 6379
+    domains:
+      - redis.example.com
+
+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

package/example/suthep-no-docker.yml

@@ -0,0 +1,51 @@
+# Example: Configuration without Docker
+# All services run directly on the host machine
+# Useful for services managed by PM2, systemd, supervisor, etc.
+
+project:
+  name: my-app
+  version: 1.0.0
+
+services:
+  # Node.js API service (e.g., running with PM2)
+  - name: api
+    port: 3000
+    domains:
+      - api.example.com
+    healthCheck:
+      path: /health
+      interval: 30
+    environment:
+      NODE_ENV: production
+      PORT: 3000
+
+  # Python web service (e.g., running with Gunicorn)
+  - name: web
+    port: 8000
+    domains:
+      - example.com
+      - www.example.com
+    healthCheck:
+      path: /health
+      interval: 30
+
+  # Go microservice
+  - name: auth
+    port: 4000
+    domains:
+      - auth.example.com
+    healthCheck:
+      path: /status
+      interval: 60
+
+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

package/example/{muacle.yml → suthep-path-routing.yml}

@@ -1,5 +1,9 @@
+# Example: Path-based Routing Configuration
+# Multiple services on the same domain using different paths
+# This is useful for monorepo deployments or microservices
+
 project:
-  name: muacle-app
+  name: path-routing-app
   version: 1.0.0
 
 services:
@@ -16,8 +20,6 @@ services:
     healthCheck:
       path: /health
       interval: 30
-    environment:
-      NODE_ENV: production
 
   # UI service on root path
   - name: ui
@@ -33,15 +35,28 @@ services:
       path: /
       interval: 30
 
+  # Admin service on /admin path
+  - name: admin
+    port: 3002
+    path: /admin
+    domains:
+      - muacle.com
+    docker:
+      image: myapp/admin:latest
+      container: admin-container
+      port: 3002
+    healthCheck:
+      path: /health
+      interval: 30
+
 nginx:
   configPath: /etc/nginx/sites-available
   reloadCommand: sudo nginx -t && sudo systemctl reload nginx
 
 certbot:
-  email: admin@muacle.com
+  email: admin@example.com
   staging: false
 
 deployment:
   strategy: rolling
   healthCheckTimeout: 30000
-