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

package/docs/en/docker-ports-config.md

@@ -1,333 +0,0 @@
-# Docker Port Configuration in suthep.yml
-
-This guide explains how to configure and export Docker ports in your `suthep.yml` configuration file.
-
-## Port Configuration Structure
-
-In `suthep.yml`, Docker ports are configured using two fields:
-
-```yaml
-services:
-  - name: my-service
-    port: 3002              # Host port (exposed on your machine)
-    docker:
-      image: myapp/service:latest
-      container: my-container
-      port: 3000            # Container port (inside Docker)
-```
-
-### Port Fields Explained
-
-| Field | Location | Description | Example |
-|-------|----------|-------------|---------|
-| `port` | `service.port` | **Host port** - Port accessible on your host machine | `3002` |
-| `port` | `service.docker.port` | **Container port** - Port your app listens on inside the container | `3000` |
-
-## How Port Mapping Works
-
-Suthep automatically creates a Docker port mapping in the format:
-```
-hostPort:containerPort
-```
-
-**Example Configuration:**
-```yaml
-- name: api
-  port: 3002              # Host port
-  docker:
-    port: 3000           # Container port
-```
-
-**Docker Command Generated:**
-```bash
-docker run -p 3002:3000 --name api-container myapp/api:latest
-```
-
-**Result:**
-- External access: `localhost:3002` → forwards to container port `3000`
-- Inside container: Your app listens on port `3000`
-- Nginx connects to: `localhost:3002`
-
-## Configuration Examples
-
-### Example 1: Same Port on Host and Container
-
-When your app uses the same port inside and outside the container:
-
-```yaml
-services:
-  - name: api
-    port: 3000              # Host: 3000
-    docker:
-      image: myapp/api:latest
-      container: api-container
-      port: 3000            # Container: 3000
-```
-
-**Port Mapping:** `3000:3000`
-
-### Example 2: Different Host and Container Ports
-
-When you want to expose a different host port:
-
-```yaml
-services:
-  - name: api
-    port: 3002              # Host: 3002 (external)
-    docker:
-      image: myapp/api:latest
-      container: api-container
-      port: 3000            # Container: 3000 (internal)
-```
-
-**Port Mapping:** `3002:3000`
-- Access from host: `localhost:3002`
-- App inside container: listens on `3000`
-
-### Example 3: Nginx Container (Port 80 → 8080)
-
-Common scenario: Nginx listens on port 80 inside container, but you expose it on 8080:
-
-```yaml
-services:
-  - name: web
-    port: 8080              # Host: 8080
-    docker:
-      image: nginx:alpine
-      container: web-container
-      port: 80              # Container: 80 (Nginx default)
-```
-
-**Port Mapping:** `8080:80`
-- Access from host: `localhost:8080`
-- Nginx inside container: listens on `80`
-
-### Example 4: Multiple Services with Different Ports
-
-```yaml
-services:
-  # API service
-  - name: api
-    port: 3001              # Host: 3001
-    docker:
-      image: myapp/api:latest
-      container: api-container
-      port: 3000            # Container: 3000
-
-  # Web service
-  - name: web
-    port: 8080              # Host: 8080
-    docker:
-      image: nginx:alpine
-      container: web-container
-      port: 80              # Container: 80
-```
-
-**Port Mappings:**
-- API: `3001:3000`
-- Web: `8080:80`
-
-## Complete Configuration Example
-
-```yaml
-project:
-  name: my-app
-  version: 1.0.0
-
-services:
-  # Service with same host/container port
-  - name: api
-    port: 3000              # Host port
-    domains:
-      - api.example.com
-    docker:
-      image: myapp/api:latest
-      container: api-container
-      port: 3000            # Container port
-    healthCheck:
-      path: /health
-      interval: 30
-
-  # Service with different host/container port
-  - name: web
-    port: 8080              # Host port (external)
-    domains:
-      - example.com
-    docker:
-      image: nginx:alpine
-      container: web-container
-      port: 80              # Container port (internal)
-    healthCheck:
-      path: /
-      interval: 30
-
-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
-```
-
-## Port Export/Exposure
-
-### How Ports Are Exposed
-
-1. **Docker Port Mapping**: Suthep automatically creates the port mapping when the container is created
-2. **Nginx Configuration**: Nginx is configured to connect to the **host port**
-3. **Access**: Services are accessible via:
-   - Direct: `localhost:hostPort`
-   - Via Nginx: `https://your-domain.com`
-
-### Port Visibility
-
-- **Host Port** (`service.port`):
-  - Exposed on your host machine
-  - Accessible from outside the container
-  - Used by Nginx to connect to your service
-  - Must be unique across all services
-
-- **Container Port** (`docker.port`):
-  - Internal to the Docker container
-  - What your application listens on inside the container
-  - Can be the same or different from host port
-
-## Important Notes
-
-### Port Conflicts
-
-Suthep automatically detects port conflicts:
-
-```yaml
-# ❌ This will fail - same host port used twice
-services:
-  - name: api
-    port: 3000
-  - name: web
-    port: 3000  # Error: Port conflict!
-```
-
-**Error Message:**
-```
-Port conflict: Service "web" uses port 3000 which is already used by: api.
-Each service must use a unique port.
-```
-
-### Port Validation
-
-- Host ports must be unique across all services
-- Ports must be between 1 and 65535
-- Container ports can be the same (they're isolated inside containers)
-
-### Changing Ports
-
-If you change the port configuration:
-
-1. **Same container name**: Suthep will detect the change and recreate the container
-2. **Different container name**: A new container will be created
-
-**Example: Changing port from 3000 to 3002**
-
-```yaml
-# Old config
-- name: api
-  port: 3000
-  docker:
-    port: 3000
-
-# New config
-- name: api
-  port: 3002  # Changed
-  docker:
-    port: 3000
-```
-
-When you deploy, Suthep will:
-1. Detect the port change
-2. Stop and remove the old container
-3. Create a new container with the new port mapping `3002:3000`
-
-## Troubleshooting
-
-### Port Already in Use
-
-**Error:** `Port 3000 is already in use`
-
-**Solutions:**
-1. Check what's using the port:
-   ```bash
-   sudo lsof -i :3000
-   # or
-   sudo netstat -tulpn | grep 3000
-   ```
-
-2. Use a different port in your configuration
-3. Stop the conflicting service/container
-
-### Container Port Mismatch
-
-**Problem:** Service not accessible
-
-**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 descriptive port numbers**:
-   - Development: 3000-3999
-   - Production: 8000-8999
-
-2. **Document port usage**: Keep track of which ports are used
-
-3. **Match container ports**: Set `docker.port` to what your app actually listens on
-
-4. **Use unique host ports**: Each service must have a unique host port
-
-5. **Test port mappings**: Verify ports work before deploying to production
-
-## Quick Reference
-
-```yaml
-# Basic structure
-services:
-  - name: service-name
-    port: HOST_PORT          # Port on your machine
-    docker:
-      image: image:tag
-      container: container-name
-      port: CONTAINER_PORT   # Port inside container
-```
-
-**Port Mapping Formula:** `HOST_PORT:CONTAINER_PORT`
-
-**Nginx Connection:** `localhost:HOST_PORT`