rvs-prxy/Design_Doc/Spec.md

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:

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