yan/rvs-prxy
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
20c55e0c4b
rvs-prxy/Design_Doc/Spec.md

16 KiB
Raw Blame History

Reverse Proxy Deployment Automation - Specifications

Key Features

  • Purpose: Setup Reverse Proxy for your Application
  • .env.rvs-prxy -- 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
  • .env-port-<port> -- parameters for port-based routing (e.g., .env-port-18081)
  • Assume your "Application" is already existing.

Key Capabilities

  • Separate Configuration Files: .env.rvs-prxy for reverse proxy instance, .env-your-domain-com (or any domain format) for each domain, .env-port-<port> for port-based routing
  • Interactive Setup Wizard: Guided configuration when no configuration files exist
  • Automatic Mode Detection: Automatically detects whether to setup reverse proxy, add new domain, or setup port exposure
  • Three 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)
    • Setup Port Exposure: Exposes host port to connect directly to container port (Traefik mode only)
  • Batch Processing: Automatically processes multiple .env-<domain> and .env-port-* 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.rvs-prxy files
  • Docker Integration: Seamless integration with Docker containers and networks
  • HTTPS/TLS Support: Automatic SSL certificate management via Let's Encrypt
  • Port-Based Routing: Direct host port to container port routing without domain names

Workflow

Two-Step Process:

  1. First Run (No .env exists): Setup Reverse Proxy Instance

    • Interactive wizard asks for reverse proxy configuration only
    • Creates .env.rvs-prxy 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.rvs-prxy 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.rvs-prxy -- the configuration of reverse proxy instance, create a reverse proxy instance only.
      • if missing .env.rvs-prxy, 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.rvs-prxy):

  • 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(s) of the local application service, comma-separated with optional protocol suffix (e.g., 80 or 80,4443/udp)

Example .env-app-example-com:

DOMAIN_NAME="app.example.com"
LOCAL_SERVICE_NAME="my-app-container"
LOCAL_SERVICE_PORT="3000"           # Single port (TCP)
# LOCAL_SERVICE_PORT="80,4443/udp"  # Multiple ports (TCP + UDP)

Reverse Proxy Instance Configuration (.env.rvs-prxy):

Mode Selection:

  • FRP - Set to false for Traefik mode (local reverse proxy), true for FRP mode (default: true)

Traefik Mode (FRP=false):

  • INSTANCE_NAME - Container name for Traefik instance (default: traefik)
  • DOCKER_NETWORK - Docker network name for container connectivity (default: traefik-public)
  • DASHBOARD_PORT - Traefik dashboard port exposed on localhost (default: 18080)
  • EXTRA_ENTRYPOINTS - Additional Traefik entrypoints beyond defaults (web/websecure), format: name=:port/protocol,name2=:port, e.g., quic=:443/udp for HTTP/3 QUIC support (default: empty). Can be set in .env.rvs-prxy or per-domain .env-<domain> files
  • 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(s) of the local application service, comma-separated with optional protocol suffix (e.g., 80 or 80,4443/udp)

Port-Based Routing Configuration (.env-port-<port>):

Required Variables (only 3):

  • HOST_PORT - Port number to expose on the host (e.g., 18081)
  • CONTAINER_NAME - Name of the target Docker container
  • CONTAINER_PORT - Port number inside the container to connect to

Example .env-port-18081:

HOST_PORT="18081"
CONTAINER_NAME="ph-web-1003-nginx_cntr"
CONTAINER_PORT="80"

Use Case:

  • Access services via http://<host-ip>:<port> without domain name routing
  • Example: http://this-host:18081 → connects to container port 80

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