suthep 0.1.0-beta.1

package/docs/en/configuration.md

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