233 lines
15 KiB
Markdown
233 lines
15 KiB
Markdown
# 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
|