suthep 0.1.0 → 0.2.0-beta.1

package/docs/configuration.md

@@ -1,347 +0,0 @@
-# Configuration Reference
-
-Suthep uses a YAML configuration file (default: `suthep.yml`) to define your deployment. This document describes all available configuration options.
-
-## Configuration File Structure
-
-```yaml
-project:
-  name: string
-  version: string
-
-services:
-  - name: string
-    port: number
-    domains: string[]
-    docker?: DockerConfig
-    healthCheck?: HealthCheckConfig
-    environment?: Record<string, string>
-
-nginx:
-  configPath: string
-  reloadCommand: string
-
-certbot:
-  email: string
-  staging: boolean
-
-deployment:
-  strategy: 'rolling' | 'blue-green'
-  healthCheckTimeout: number
-```
-
-## Project Configuration
-
-### `project.name`
-
-- **Type**: `string`
-- **Required**: Yes
-- **Description**: Name of your project
-
-```yaml
-project:
-  name: my-awesome-app
-```
-
-### `project.version`
-
-- **Type**: `string`
-- **Required**: Yes
-- **Description**: Version of your project
-
-```yaml
-project:
-  version: 1.0.0
-```
-
-## Service Configuration
-
-Each service represents an application or service that will be deployed and exposed via Nginx.
-
-### `services[].name`
-
-- **Type**: `string`
-- **Required**: Yes
-- **Description**: Unique name for the service. Used for Nginx configuration files and Docker containers.
-
-```yaml
-services:
-  - name: api
-```
-
-### `services[].port`
-
-- **Type**: `number`
-- **Required**: Yes
-- **Description**: Port number where the service is listening (1-65535)
-
-```yaml
-services:
-  - name: api
-    port: 3000
-```
-
-### `services[].domains`
-
-- **Type**: `string[]`
-- **Required**: Yes
-- **Description**: Array of domain names or subdomains that will route to this service
-
-```yaml
-services:
-  - name: api
-    domains:
-      - api.example.com
-      - www.api.example.com
-```
-
-### `services[].docker` (Optional)
-
-Docker configuration for containerized services.
-
-#### `docker.image`
-
-- **Type**: `string`
-- **Required**: No
-- **Description**: Docker image to use. If omitted, Suthep will connect to an existing container.
-
-```yaml
-services:
-  - name: webapp
-    docker:
-      image: nginx:latest
-```
-
-#### `docker.container`
-
-- **Type**: `string`
-- **Required**: Yes (if `docker` is specified)
-- **Description**: Name of the Docker container
-
-```yaml
-services:
-  - name: webapp
-    docker:
-      container: webapp-container
-```
-
-#### `docker.port`
-
-- **Type**: `number`
-- **Required**: Yes (if `docker` is specified)
-- **Description**: Port inside the container that the service listens on
-
-```yaml
-services:
-  - name: webapp
-    port: 8080
-    docker:
-      port: 80  # Container's internal port
-```
-
-**Note**: The `service.port` is the host port, and `docker.port` is the container port. Suthep will map `service.port:docker.port`.
-
-### `services[].healthCheck` (Optional)
-
-Health check configuration for the service.
-
-#### `healthCheck.path`
-
-- **Type**: `string`
-- **Required**: Yes (if `healthCheck` is specified)
-- **Description**: HTTP path to the health check endpoint
-
-```yaml
-services:
-  - name: api
-    healthCheck:
-      path: /health
-```
-
-#### `healthCheck.interval`
-
-- **Type**: `number`
-- **Required**: Yes (if `healthCheck` is specified)
-- **Description**: Health check interval in seconds
-
-```yaml
-services:
-  - name: api
-    healthCheck:
-      interval: 30
-```
-
-### `services[].environment` (Optional)
-
-- **Type**: `Record<string, string>`
-- **Required**: No
-- **Description**: Environment variables to pass to Docker containers
-
-```yaml
-services:
-  - name: api
-    docker:
-      image: myapp/api:latest
-      container: api-container
-      port: 3000
-    environment:
-      NODE_ENV: production
-      DATABASE_URL: postgresql://localhost:5432/mydb
-      API_KEY: secret-key
-```
-
-## Nginx Configuration
-
-### `nginx.configPath`
-
-- **Type**: `string`
-- **Required**: Yes
-- **Default**: `/etc/nginx/sites-available`
-- **Description**: Path where Nginx configuration files will be stored
-
-```yaml
-nginx:
-  configPath: /etc/nginx/sites-available
-```
-
-### `nginx.reloadCommand`
-
-- **Type**: `string`
-- **Required**: Yes
-- **Description**: Command to test and reload Nginx configuration
-
-```yaml
-nginx:
-  reloadCommand: sudo nginx -t && sudo systemctl reload nginx
-```
-
-## Certbot Configuration
-
-### `certbot.email`
-
-- **Type**: `string`
-- **Required**: Yes
-- **Description**: Email address for Let's Encrypt certificate notifications
-
-```yaml
-certbot:
-  email: admin@example.com
-```
-
-### `certbot.staging`
-
-- **Type**: `boolean`
-- **Required**: Yes
-- **Description**: Use Let's Encrypt staging environment (for testing). Set to `true` during development to avoid rate limits.
-
-```yaml
-certbot:
-  staging: false  # Use production certificates
-```
-
-**Important**: Set `staging: true` when testing to avoid hitting Let's Encrypt rate limits.
-
-## Deployment Configuration
-
-### `deployment.strategy`
-
-- **Type**: `'rolling' | 'blue-green'`
-- **Required**: Yes
-- **Description**: Deployment strategy to use
-
-```yaml
-deployment:
-  strategy: rolling
-```
-
-**Options**:
-- `rolling`: Gradually replaces old instances with new ones (default)
-- `blue-green`: Maintains two identical environments and switches between them
-
-### `deployment.healthCheckTimeout`
-
-- **Type**: `number`
-- **Required**: Yes
-- **Description**: Maximum time (in milliseconds) to wait for a service to become healthy
-
-```yaml
-deployment:
-  healthCheckTimeout: 30000  # 30 seconds
-```
-
-## Complete Example
-
-```yaml
-project:
-  name: my-awesome-app
-  version: 1.0.0
-
-services:
-  # Simple Node.js API
-  - name: api
-    port: 3000
-    domains:
-      - api.example.com
-    healthCheck:
-      path: /health
-      interval: 30
-    environment:
-      NODE_ENV: production
-
-  # Docker-based web application
-  - name: webapp
-    port: 8080
-    docker:
-      image: nginx:latest
-      container: webapp-container
-      port: 80
-    domains:
-      - example.com
-      - www.example.com
-    healthCheck:
-      path: /
-      interval: 30
-
-  # Connect to existing Docker container
-  - name: database-proxy
-    port: 5432
-    docker:
-      container: postgres-container
-      port: 5432
-    domains:
-      - db.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
-```
-
-## Configuration Validation
-
-Suthep validates your configuration file when you run `suthep deploy`. Common validation errors:
-
-- Missing required fields
-- Invalid port numbers (must be 1-65535)
-- Invalid email format
-- Duplicate service names
-- Missing Docker container name when Docker is enabled
-
-## Environment Variables
-
-You can use environment variables in your configuration file by using `${VAR_NAME}` syntax (if your YAML parser supports it), or by using a templating tool before deployment.
-
-## Best Practices
-
-1. **Use staging mode during development**: Set `certbot.staging: true` to avoid rate limits
-2. **Always configure health checks**: Helps ensure services are ready before traffic is routed
-3. **Use descriptive service names**: Makes Nginx configs easier to manage
-4. **Keep configuration in version control**: Track changes to your deployment configuration
-5. **Test locally first**: Use staging certificates and test domains before production