rvs-prxy/Design_Doc/Tech_Desc.md

# Technical Architecture and Implementation Details

## Script Architecture

The `deploy-rvs-prxy.sh` script is an automated deployment tool supporting both FRP and Traefik modes.

**Key Architecture:** The script runs directly on the same server where the application is hosted (local deployment), eliminating the need for SSH-based remote operations in Traefik mode.

**Deployment Modes:**
1. **Setup Reverse Proxy**: Deploys new Traefik or FRP Tunnel with Traefik
2. **Setup New Domain**: Adds new domain configuration to existing reverse proxy
3. **Setup Port Exposure**: Exposes a host port to a container port
4. **Setup External Service Domain**: Adds a domain routed to an external web service URL

**Configuration File Structure:**
- `.env.rvs-prxy` - Reverse proxy instance configuration (FRP mode, Traefik version, etc.)
- `.env-<domain>` - Domain-specific configuration (DOMAIN_NAME, LOCAL_SERVICE_NAME, LOCAL_SERVICE_PORT)
  - Domain format: Any domain format supported (`.com`, `.net`, `.org`, `.org.hk`, `.com.hk`, subdomains, etc.)
  - Filename pattern: Dots replaced with dashes (e.g., `app.example.com` → `.env-app-example-com`)
- `.env-port-<port>` - Port-based routing configuration (HOST_PORT, CONTAINER_NAME, CONTAINER_PORT)
- `.env-ext-<domain>` - External service routing configuration (DOMAIN_NAME, EXTERNAL_URL)
  - Filename pattern: Dots replaced with dashes (e.g., `box.example.com/api` → `.env-ext-box-example-com-api`)
- Multiple domain, port and external service files can coexist

**Automatic Mode Detection:**
- No config files → Interactive wizard for proxy setup
- `.env.rvs-prxy` exists, proxy not running → Setup Reverse Proxy
- `.env.rvs-prxy` exists, proxy running, no domain/port/ext file → Interactive wizard for domain/port/external service setup
- `.env.rvs-prxy` + `.env-<domain>` exists → Setup New Domain
- `.env.rvs-prxy` + `.env-port-<port>` exists → Setup Port Exposure
- `.env.rvs-prxy` + `.env-ext-<domain>` exists → Setup External Service Domain
- Batch precedence when several types coexist: port files first, then external service files, then domain files

**Validation:**
- **Proxy Setup Mode**: Validates proxy-specific settings (TRAEFIK_VER, LETSENCRYPT_EMAIL for Traefik; FRP_SERVER_ADDR for FRP)
- **Domain Setup Mode**: Validates domain-specific settings (DOMAIN_NAME, LOCAL_SERVICE_NAME, LOCAL_SERVICE_PORT)
- **External Service Mode**: Validates DOMAIN_NAME and EXTERNAL_URL; requires Traefik mode (`FRP=false`), since FRP tunnels TCP ports rather than performing HTTP routing

**Workflow:**

First Run (No .env.rvs-prxy):
  1. Interactive wizard asks for proxy instance settings
  2. Creates .env.rvs-prxy with Traefik/FRP settings
  3. Validation checks proxy settings (TRAEFIK_VER, LETSENCRYPT_EMAIL)
  4. Deploys reverse proxy
  5. Shows message: "Next: Run the script again to setup your first domain or port"

Second Run (.env.rvs-prxy exists, proxy running):
  1. Detects running proxy
  2. Interactive wizard asks for domain, port or external service settings
  3. Creates .env-<domain>, .env-port-<port> or .env-ext-<domain> with settings
  4. Validation checks domain/port/external service settings
  5. Checks if application service/container is running (skipped for external service routing)
  6. Configures domain/port/external service in existing reverse proxy
  7. Shows: "Service will be accessible at: https://domain.name or http://host-ip:port"

Four Deployment Modes:
  1. Setup Reverse Proxy - Deploys Traefik or FRP Tunnel
  2. Setup New Domain - Adds domain-based routing to a local container
  3. Setup Port Exposure - Adds port-based routing
  4. Setup External Service Domain - Adds domain-based routing to an external URL (Traefik only)

### Core Components

**1. Environment Loading (`load_env`)**
- Loads configuration from `.env.rvs-prxy.development`, `.env.rvs-prxy.production`, or `.env.rvs-prxy`
- Supports files in current directory or script directory
- **Interactive Setup Wizard**: If no `.env.rvs-prxy` file is found, automatically launches a guided setup wizard
- Normalizes boolean values (FRP variable)
- Validates required parameters for each mode
- Supports four modes: proxy setup, domain setup, port exposure, and external service routing
- Classifies config files into `DOMAIN_ENV_FILES`, `PORT_ENV_FILES`, and `EXT_ENV_FILES`; the first file of each type determines the detected mode (port > external > domain)

**Interactive Setup Wizard Features:**
- Step-by-step guided configuration
- Mode selection (Traefik or FRP) for proxy setup
- Choice between domain setup, port exposure, or external service routing when proxy exists
- Mode-specific configuration prompts
- Sensible defaults for all settings
- Automatic saving to `.env.rvs-prxy`, `.env-<domain>`, `.env-port-<port>`, or `.env-ext-<domain>` files

**2. Instance Management (`prompt_instance_name`)**
- Auto-detects existing instances from Docker volumes (FRP mode)
- Supports instance name override via `INSTANCE_NAME` environment variable
- Generates timestamped default names
- Saves selections to `.env` for future runs

**3. Docker Network Selection (`select_docker_network`)**
- Lists available Docker networks
- Supports custom network names
- Remembers previous selections via `.para` file in volume (FRP mode)

**4. Configuration Generation**
- **FRP Mode**: Generates `frpc.toml` with dynamic proxy configurations
- **Traefik Mode**: Generates YAML configuration files for routing rules (local deployment)

**5. Container Management**
- Creates and manages Docker containers with persistent volumes
- Supports container restart and lifecycle operations
- Displays operation commands for user reference

## Traefik Mode Implementation (Local Deployment)

### Setup Flow (`setup_traefik_only`)

1. **Pre-request Checks**
   - Verify Docker command permissions

2. **Application Service Verification** (`check_app_service_local`)
   - Confirms target service is running locally
   - Verifies connection to `traefik-public` network

3. **Traefik Container Creation** (`create_traefik_container_local`)
   - Creates `traefik_data` volume for persistence
   - Generates dynamic configuration with:
     - Dashboard routing
     - HTTP to HTTPS redirect
     - Security headers
   - Creates `traefik-public` Docker network
   - Uses Docker Compose for container orchestration
   - Detects Docker version for command compatibility (`docker compose` vs `docker-compose`)

4. **Service Configuration** (`configure_traefik_local`)
   - Generates service-specific routing rules
   - Supports sub-path routing (e.g., `example.com/api`)
   - Creates unique configuration filenames to avoid conflicts
   - Supports dynamic configuration loading (no restart required by default)

5. **External Service Configuration** (`configure_traefik_external`, called by `setup_external_domain`)
   - Generates routing rules for a public domain whose upstream is an external URL
   - Requires Traefik mode (`FRP=false`) - rejects `.env-ext-*` files when FRP is enabled
   - No local container lookup and no Docker network requirement for the upstream
   - Persists settings as `.env-ext-<domain>` via `save_ext_env()` for later re-runs

### Local Docker Operations

- `local_docker_exec()`: Executes Docker commands directly on the local server
- `local_volume_copy()`: Copies files to Docker volumes using temporary containers

### Configuration File Structure

**Traefik Main Config** (`traefik.yml`):
```yaml
http:
  routers:
    api:
      rule: "PathPrefix(`/api`)"
      service: api@internal
    dashboard:
      rule: "PathPrefix(`/dashboard`)"
      service: api@internal
    http-catchall:
      rule: "PathRegexp(`{any:.*}`)"
      entryPoints:
        - "web"
      service: "noop@internal"
      middlewares:
        - "redirect-to-https"
  middlewares:
    api-headers:
      headers:
        customFrameOptionsValue: SAMEORIGIN
        contentTypeNosniff: true
        browserXssFilter: true
        stsIncludeSubdomains: true
        stsPreload: true
        stsSeconds: 15552000
    redirect-to-https:
      redirectScheme:
        scheme: "https"
        permanent: true
```

**Service Config** (dynamic, per-service):
```yaml
http:
  routers:
    <domain>-https:
      rule: 'Host(`<domain>`)'
      service: <domain>-service
      tls:
        certResolver: letsencrypt
      entryPoints:
        - websecure
    <domain>-http:
      rule: 'Host(`<domain>`)'
      service: <domain>-service
      entryPoints:
        - web
      middlewares:
        - redirect-to-https
  services:
    <domain>-service:
      loadBalancer:
        servers:
          - url: 'http://<container-name>:<port>'
        passHostHeader: true
```

Router, service, and middleware names use the domain (or domain-without-sub-path) as the prefix instead of the container name. This ensures unique resource names when multiple domains share the same backend container. The backend URL still references the container hostname for Docker networking.

**External Service Config** (dynamic, per-domain, written by `configure_traefik_external`):
```yaml
http:
  routers:
    <domain>-https:
      rule: 'Host(`<domain>`)'
      service: <domain>-service
      tls:
        certResolver: letsencrypt
      entryPoints:
        - websecure
    <domain>-http:
      rule: 'Host(`<domain>`)'
      service: <domain>-service
      entryPoints:
        - web
      middlewares:
        - redirect-to-https
  middlewares:
    <domain>-strip:
      stripPrefix:
        paths:
          - '<public-sub-path>'
    <domain>-add:
      addPrefix:
        path: '<origin-base-path>'
  services:
    <domain>-service:
      loadBalancer:
        servers:
          - url: '<scheme>://<external-host>[:<port>]'
        passHostHeader: false
```

Implementation notes:
- Config file name: `app-ext-<domain-without-sub-path>.yml` inside the `traefik_data` volume, written via a temporary `alpine` container (`local_volume_copy`)
- `parse_external_url()` splits `EXTERNAL_URL` into scheme, host, port (default `443` for `https`, `80` for `http`) and base path; a non-numeric or out-of-range port is rejected
- The origin path is never part of the server URL; it is added back with `addPrefix` so a public sub-path and an origin base path compose correctly
- `passHostHeader: false` makes the origin receive its own hostname instead of the public domain, so upstream vhost routing and origin certificates keep working
- Origin TLS uses the container trust store (no `insecureSkipVerify`); only the public domain gets a Let's Encrypt certificate
- DNS for the external host is resolved inside the Traefik container, so `check_external_service_reachable()` only performs a local `nslookup`/`host` check and warns without aborting

**Entrypoints Configuration:**
Default entrypoints (`web` on :80, `websecure` on :443) are defined in the docker-compose.yml command args. Additional entrypoints can be configured via the `EXTRA_ENTRYPOINTS` environment variable in `.env.rvs-prxy`:
- Format: `name=:port/protocol,name2=:port` (comma-separated)
- Example: `quic=:443/udp` enables HTTP/3 QUIC on UDP port 443
- These are injected into both the docker-compose.yml `command:` section and the `docker run` command
- Port mappings (TCP/UDP) are automatically added to the `ports:` section
- The `parse_extra_entrypoints()` function parses the variable and builds:
  - `EXTRA_ENTRYPOINT_ARGS`: array of `--entrypoints.<name>.address=<address>` args
  - `EXTRA_PORT_MAPPINGS`: array of port mappings in `host:container/protocol` format
  - `EXTRA_COMPOSE_ENTRYPOINTS`: YAML lines for docker-compose.yml command section
  - `EXTRA_COMPOSE_PORTS`: YAML lines for docker-compose.yml ports section

## FRP Mode Implementation

### Setup Flow

1. **Instance Setup**: Prompt for instance name
2. **Port Configuration**: Prompt for internal service port
3. **FRP Config Generation** (`generate_frpc_config`)
   - Extracts existing configuration from volume
   - Supports dynamic proxy configurations via `PROXY_*_PORT` variables
   - Generates `frpc.toml` with TCP proxy rules
4. **Container Start** (`start_docker_container`)
   - Creates volume if not exists
   - Starts frpc container with configuration mounted
5. **Proxy Server Update** (`update_proxy_server_config`)
   - Uploads dynamic configuration script to proxy server
   - Updates `docker-compose.app.yml` with port mappings and labels
   - Supports domain-based routing configuration

### Dynamic Proxy Configuration

The script supports dynamic proxy configurations through environment variables:
- `PROXY_<NAME>_PORT`: Defines remote port for proxy
- `PROXY_<NAME>_LOCAL_PORT`: Defines local port (defaults to `INTERNAL_SERVICE_PORT`)

Example:
```bash
PROXY_WEB_PORT=12077
PROXY_WEB_LOCAL_PORT=3000
PROXY_SSH_PORT=2222
PROXY_SSH_LOCAL_PORT=22
```

### Proxy Server Configuration Update

The script generates and executes a remote script on the proxy server that:
- Checks existing configuration status (not_found, up_to_date, outdated)
- Updates port mappings section in `docker-compose.app.yml`
- Updates labels section for Traefik routing
- Optionally restarts Docker Compose service

## File Deployment (Traefik Mode)

The `deploy` command syncs files from local folder to target server:
- Source: `LOCAL_FOLDER` (default: `../out/`)
- Destination: `DEST_PATH` on target server
- Uses rsync for efficient synchronization with `--delete` option

## Logging and Debugging

**Logging Functions:**
- `log_info()`: Green [INFO] messages
- `log_error()`: Red [ERROR] messages
- `log_warn()`: Yellow [WARN] messages
- `log_debug()`: Blue [DEBUG] messages (only when `DEBUG=true`)

**Status Commands:**
- `check_status_on_target()`: Shows Traefik and Application service status
- `view_traefik_logs()`: Displays last 50 lines of Traefik logs

## Error Handling

- Uses `set -e` for immediate exit on errors
- Validates required parameters before execution
- Provides detailed error messages with suggested fixes
- Graceful handling of missing configurations

## Version Compatibility

**Docker Version Detection:**
- Detects Docker version to determine command syntax
- Uses `docker compose` for Docker 20.10.0+
- Falls back to `docker-compose` for older versions
- Handles Compose file version field (deprecated in v2.0+)

**Traefik Version:**
- Default: `v3.6.9`
- Configurable via `TRAEFIK_VER` environment variable