# Reverse Proxy Deployment Automation - Specifications

## Key Features
- Purpose: Setup Reverse Proxy for your Application
- `.env` -- **parameters for Reverse Proxy instance**
- `.env-your-domain-com` -- **parameters for the domain your.domain.com of your Application**
- `.env-your-domain2-com` -- **parameters for the domain your.domain2.com of your Application**
- `.env-your-domainN-com` -- **parameters for the domain your.domainN.com of your Application**
- Assume your "Application" is already existing.

### Key Capabilities

- **Separate Configuration Files**: `.env` for reverse proxy instance, `.env-your-domain-com` (or any domain format) for each domain
- **Interactive Setup Wizard**: Guided configuration when no configuration files exist
- **Automatic Mode Detection**: Automatically detects whether to setup reverse proxy or add new domain
- **Two Deployment Modes**:
  - **Setup Reverse Proxy**: Deploys Traefik or FRP Tunnel with Traefik
  - **Setup New Domain**: Adds new domain to existing reverse proxy (supports both Traefik and FRP modes)
- **Batch Processing**: Automatically processes multiple `.env-<domain>` files in a single run
- **Traefik Mode**: Deploy and configure Traefik reverse proxy on the same server as your application
- **FRP Mode**: Optional Fast Reverse Proxy support for tunneling connections to a remote proxy server
  - **FRP Domain Setup**: Add new domains to existing FRP tunnel by allocating new remote ports and updating proxy server configuration
- **Automated Configuration**: Dynamic generation of reverse proxy configurations based on `.env` files
- **Docker Integration**: Seamless integration with Docker containers and networks
- **HTTPS/TLS Support**: Automatic SSL certificate management via Let's Encrypt

### Workflow

**Two-Step Process:**
1. **First Run (No .env exists)**: Setup Reverse Proxy Instance
   - Interactive wizard asks for reverse proxy configuration only
   - Creates `.env` with Traefik/FRP instance settings
   - Deploys Traefik or FRP reverse proxy container
   - **No application service check** (application not needed at this stage)
   - No domain configuration at this stage

2. **Add domain (proxy running)**: Setup New Domain
   - Script auto-detects running proxy mode (Traefik or FRP)
   - Interactive wizard asks for domain configuration (if no `.env-<domain>` exists)
   - Creates `.env-<domain>` with application settings
   - **Checks if application service is running**
   - Configures domain in existing reverse proxy

**Proxy Mode Detection:**
- Script automatically detects running proxy from Docker containers
- Traefik mode: detects `traefik` container
- FRP mode: detects `*-frpc` containers
- Works with or without `.env` file

  ```
  ┌────────────┬─────────────────────────────────────┬────────────────────────────────────────────────────────┬────────────────┐
  │ Scenario   │ Configuration                       │ Wizard Asks For                                        │ Creates        │
  ├────────────┼─────────────────────────────────────┼────────────────────────────────────────────────────────┼────────────────┤
  │ First run  │ No files                            │ Proxy instance settings (Traefik version, email, etc.) │ .env           │
  │ First run  │ .env exists                         │ Proxy instance settings (Traefik version, email, etc.) │ Null           │
  │ Add domain │ proxy running, no .env-<domain>     │ Domain settings (domain name, service, port)           │ .env-<domain>  │
  │ Add domain │ proxy running, .env-<domain> exists │ Domain settings (domain name, service, port)           │ Null           │
  └────────────┴─────────────────────────────────────┴────────────────────────────────────────────────────────┴────────────────┘
  ```

- Detect the existing of reverse proxy instance -- this script and reverse proxy instance at same computer.
  - if non-existing of reverse proxy instance: look for the existing of `.env` -- the configuration of reverse proxy instance, create a reverse proxy instance only.
    - if missing `.env`, start interactive wizard to take all configuration for reverse proxy instance only.
  - if existing of reverse proxy instance: look for the existing of `.env-<domain>` -- not touch the reverse proxy instance, just insert this domain configuration into the existing reverse proxy instance.
    - if missing `.env-<domain>`, start interactive wizard to take all configuration for the domain, then insert into existing reverse proxy instance.
    - one of example of domain configuration: application's internal service port

- Summary by Diagram:
  ```
  ┌────────────────────────────────────────┬─────────────────────┬─────────────────────────────────┐
  │ Condition                              │ Mode                │ Action                          │
  ├────────────────────────────────────────┼─────────────────────┼─────────────────────────────────┤
  │ No .env exists                         │ Setup Reverse Proxy │ Interactive wizard → Create .env│
  │                                        │                     │ Deploy proxy (no app check)     │
  │ .env exists + No proxy running         │ Setup Reverse Proxy │ Deploy proxy from .env config   │
  │ .env exists + Proxy running            │ Setup New Domain    │ Look for .env-<domain> file     │
  │ .env-<domain> exists                   │ Setup New Domain    │ Add domain to existing proxy    │
  │ No .env-<domain> + Proxy running       │ Setup New Domain    │ Interactive wizard → Create     │
  │                                        │                     │ Check app service → Configure   │
  │ No .env + Proxy running                │ Setup New Domain    │ Auto-detect mode → Wizard/Config│
  └────────────────────────────────────────┴─────────────────────┴─────────────────────────────────┘
  ```

### Configuration

#### Configuration Files

**Reverse Proxy Instance Configuration (`.env`):**
- Contains reverse proxy instance settings (FRP mode, Traefik version, etc.)
- Created during first-time setup
- One file per reverse proxy instance
- **Note:** This file is optional for domain setup if proxy is already running (mode auto-detected)

**Domain-Specific Configuration (`.env-<domain>`):**
- Pattern: `.env-<domain-with-dashes>` (e.g., `.env-example-com`, `.env-sub-domain-net`, `.env-app-org-hk`)
- Contains domain-specific settings (DOMAIN_NAME, LOCAL_SERVICE_NAME, LOCAL_SERVICE_PORT)
- One file per domain
- Multiple domain files can coexist
- Accepts any domain format: `.com`, `.net`, `.org`, `.org.hk`, `.com.hk`, subdomains, etc.
- **Simplified format:** Only requires 3 variables (see below)

#### Key Environment Variables

**Domain-Specific Configuration (`.env-<domain>`):**

**Required Variables (only 3):**
- `DOMAIN_NAME` - Domain name for reverse proxy routing (e.g., `app.example.com`)
- `LOCAL_SERVICE_NAME` - Name of the local Docker application container
- `LOCAL_SERVICE_PORT` - Port number of the local application service

**Example `.env-app-example-com`:**
```bash
DOMAIN_NAME="app.example.com"
LOCAL_SERVICE_NAME="my-app-container"
LOCAL_SERVICE_PORT="3000"
```

**Reverse Proxy Instance Configuration (`.env`):**

**Mode Selection:**
- `FRP` - Set to `false` for Traefik mode (local reverse proxy), `true` for FRP mode (default: `true`)

**Traefik Mode (FRP=false):**
- `TRAEFIK_VER` - Traefik version (default: `v3.6.9`)
- `LETSENCRYPT_EMAIL` - Email for Let's Encrypt certificates
- `RESTART_TRAEFIK` - Whether to restart Traefik after config update (`true`/`false`, default: `false`)
- `DEBUG` - Enable debug logging (`true`/`false`, default: `false`)

**FRP Mode (FRP=true):**
- `FRP_SERVER_ADDR` - FRP server address (IP or hostname)
- `FRP_SERVER_PORT` - FRP server port (default: `16999`)
- `FRP_SERVER_USER` - FRP server SSH username (default: `teenfuture`)
- `INSTANCE_NAME` - Unique instance identifier (auto-generated if not provided)
- `INTERNAL_SERVICE_PORT` - Internal service port exposed by Docker container (default: `3000`)
- `DOCKER_NETWORK` - Docker network name for container connectivity
- `PROXY_*_PORT` - Dynamic proxy port configurations

**Domain-Specific Configuration (`.env-<domain>`):**

**Required Variables:**
- `DOMAIN_NAME` - Domain name for reverse proxy routing (e.g., `app.example.com`, `sub.domain.org.hk`)
- `LOCAL_SERVICE_NAME` - Name of the local Docker application container
- `LOCAL_SERVICE_PORT` - Port number of the local application service

### Approaches

#### Traefik Only
- At a Proxy Server 
- Setup a Traefik docker container 
- If Traefik does not exist, will create it dynmaically, Otherwise, use exsiting one.
  - Remark: one Target Server has one unique Traefik instance running -- container name as traefik.
- Architecture
```
+--------------------------------------------------------------------------+ 
|                                               Target Server              | 
|                                                                          | 
|                                                  +---------+             | 
|                                                  |         |             | 
|                                                  | Traefik |             | 
|                                                  |         |             | 
|                                                  +---------+             | 
|                                                     ^                    | 
|  +-------------+                                    |                    | 
|  |             |       Setup Reverse Proxy     +----+------------------+ | 
+  | This        +------------------------------>|                       | | 
|  | Automatical |       for your existing       | Reverse Proxy Setting | | 
|  | System      |<-+    application             | eg. www.domain.com    | | 
|  |             |  |                            |                       | | 
|  +-------------+  |                            +------+----------------+ | 
|                   |                                   |                  | 
|                 .env                                  v                  | 
|                                                   +-------------+        | 
|                                                   |             |        | 
|                                                   | Existing    |        | 
|                                                   | Application |        | 
|                                                   |             |        | 
|                                                   +-------------+        | 
|                                                                          | 
+--------------------------------------------------------------------------+ 
```
- **Features:**
  - Automatic Traefik container creation with persistent volume (`traefik_data`)
  - Dynamic configuration file generation for each service
  - HTTP to HTTPS redirect support
  - Let's Encrypt SSL certificate automation
  - Sub-path routing support (e.g., `example.com/api`)
  - Non-destructive configuration updates (no restart required by default)
  - Docker network integration (`traefik-public` network)

- **Pre-requisites:**
  - Docker installed on the local server (same server where script runs)
  - User has permission to execute Docker commands
  - Local application container must be running and connected to `traefik-public` network

#### Traefik + FRP

- Architecture
```
+-------------------+                     +-------------------+              
|   Local Host      |                     |  Proxy Server     |              
|                   |                     |                   |              
|  +-------------+  |    FRP Tunnel       |  +-------------+  |              
|  | Application |  | <-----------------> |  |   Traefik   |  |<--- Domains  
|  |  Service #1 |  |       Public IPs    |  | (Router)    |  |    HTTPS/TLS 
|  |             |  |       Port: 16999   |  |             |  |              
|  +-------------+  |                     |  +-------------+  |              
|                   |                     |                   |              
|  +-------------+  |                     |  +-------------+  |              
|  |   FRPC      |  |                     |  |   FRPS      |  |              
|  | (Client)    |  |                     |  | (Server)    |  |              
|  |             |  |                     |  |             |  |              
|  +-------------+  |                     |  +-------------+  |              
|                   |                     |                   |              
|                   |                     |  +-------------+  |              
|                   |                     |  | Application |  |              
|                   |                     |  |  Service #2 |  |              
|                   |                     |  |             |  |              
+-------------------+                     |  +-------------+  |              
                                          +-------------------+
```

- **Features:**
  - FRP client (frpc) deployment via Docker
  - Dynamic TCP tunnel configuration
  - Multiple proxy support per instance
  - Automatic proxy server configuration update
  - Persistent volume for FRP configuration

- **Pre-requisites:**
  - Docker installed on local host
  - FRP server accessible at configured address
  - SSH key (`~/.ssh/itl-devs1`) for proxy server access