rvs-prxy/Design_Doc/Operations.md

Quick Start

Step 1: First Time Setup (Reverse Proxy Instance)

When no configuration files exist, the script will setup the reverse proxy instance:

curl -s "https://www.ivantito.com/app-pub/demos/test/deploy-rvs-prxy.sh" | bash

The wizard will ask you (Reverse Proxy Instance settings only):

1. Deployment Mode:

   • Traefik Mode (local reverse proxy)
   • FRP Mode (remote proxy via tunnel)

2. For Traefik Mode:

   • Traefik version (default: v3.6.9)
   • Let's Encrypt email for SSL certificates
   • Debug mode (optional)

3. For FRP Mode:

   • FRP server address
   • FRP server port (default: 16999)
   • Instance name (optional)

What Happens:

• Creates .env with reverse proxy settings
• Deploys Traefik or FRP container
• No application service check (your app is not needed yet)

Configuration File Created:

• .env - Reverse proxy instance configuration

Note: At this stage, only the reverse proxy instance is configured. No domain or application settings are needed yet.

Step 2: Setup Your First Domain

After the reverse proxy is running, run the script again to add your first domain:

curl -s "https://www.ivantito.com/app-pub/demos/test/deploy-rvs-prxy.sh" | bash

The wizard will ask you (Domain settings only):

1. Domain name (e.g., app.example.com, sub.domain.org.hk)
2. Application service name (Docker container name)
3. Application service port

What Happens:

• Checks if your application service is running
• Creates .env-<domain> with domain settings
• Configures domain in existing reverse proxy

Configuration File Created:

• .env-<domain> - Domain-specific configuration (e.g., .env-app-example-com)

Step 3: Add More Domains (Optional)

To add additional domains, create additional domain configuration files or run the wizard again:

curl -s "https://www.ivantito.com/app-pub/demos/test/deploy-rvs-prxy.sh" | bash

Each domain gets its own .env-<domain> file.

Alternative: Using Configuration Files Directly

For Reverse Proxy Setup:

1. Create .env file with reverse proxy configuration
2. Run: curl -s "https://www.ivantito.com/app-pub/demos/test/deploy-rvs-prxy.sh" | bash

For New Domain Setup:

1. Create .env-<domain> file with domain configuration
2. Ensure .env exists and reverse proxy is running
3. Ensure your application service is running
4. Run: curl -s "https://www.ivantito.com/app-pub/demos/test/deploy-rvs-prxy.sh" | bash

Run this System

Using with curl (Remote Execution)

The script is designed to run directly via curl without any parameters:

# Basic usage - auto-detects mode
curl -s "https://www.ivantito.com/app-pub/demos/test/deploy-rvs-prxy.sh" | bash

# Show help
curl -s "https://www.ivantito.com/app-pub/demos/test/deploy-rvs-prxy.sh" | bash -s -- --help

Note: The script automatically:

1. Loads .env configuration if it exists
2. Triggers interactive wizard if .env is missing
3. Detects deployment mode (setup proxy or setup domain)

Re-running for Existing Domain

What happens if you run the script again for a domain that's already configured?

If you run the script for a domain that has already been added to the reverse proxy:

1. Detection: The script checks if a configuration file already exists for the domain and service combination
2. Warning: Displays a warning message:

   [WARN] Configuration file app-service-domain-service.yml already exists, it will be overwritten
   [INFO] This will update the existing domain configuration for my.domain.com
   

   • Configuration File Naming:
   • Format: app-service-{domain}-{service}.yml
   • Example: app-service-my-domain-com-myapp.yml
   • Unique per domain+service combination
3. Update: The existing configuration is overwritten with the new settings
4. Result: The domain configuration is updated (not duplicated)

Key Points:

• Safe to re-run: Running the script multiple times for the same domain is safe
• Configuration is updated, not duplicated: Each domain+service combination has a unique configuration file
• No service interruption: Traefik dynamically loads the updated configuration (no restart needed by default)
• Use case: Useful for updating application port changes or domain routing modifications

Example Scenario:

# First run - adds my.domain.com
curl -s "https://www.ivantito.com/app-pub/demos/test/deploy-rvs-prxy.sh" | bash
# [INFO] Creating new configuration for domain my.domain.com

# Second run - updates my.domain.com (e.g., after port change)
curl -s "https://www.ivantito.com/app-pub/demos/test/deploy-rvs-prxy.sh" | bash
# [WARN] Configuration file ... already exists, it will be overwritten
# [INFO] This will update the existing domain configuration for my.domain.com

Script Behavior

Mode Selection

Set the FRP environment variable to control the deployment mode:

# Traefik Mode (local reverse proxy on same server)
FRP=false ./deploy-traefik.sh setup-rvs-prxy

# FRP Mode (remote proxy via FRP tunnel)
FRP=true ./deploy-traefik.sh setup-rvs-prxy

Traefik Mode Operations (FRP=false)

Setup

• ./deploy-traefik.sh setup-rvs-prxy
  • Will apply the new .env setting to Traefik
    • If no Traefik exists: create new and apply settings
    • If Traefik already exists: keep all old settings, then apply new settings
  • Pre-request checks:
    • Ensure current user has permission to execute Docker commands
  • Automatic deployment steps:
    1. Check if Application Service exists locally
    2. Create Traefik container locally (if not exists)
    3. Configure Traefik routing for the Application Service
    4. Display operation commands for future reference

Check Status

• ./deploy-traefik.sh status
  • Displays running status of Traefik container locally
  • Displays running status of Application Service locally

View Logs

• ./deploy-traefik.sh logs
  • Shows last 50 lines of Traefik logs locally

FRP Mode Operations (FRP=true)

Setup

• ./deploy-traefik.sh setup-rvs-prxy
  • Will apply the new .env setting to FRP client
    • If no FRPC exists: create new and apply settings
    • If FRPC already exists: keep all old settings, then apply new settings
  • Pre-request checks:
    • Ensure current user has permission to execute Docker commands
    • Ensure SSH key pairs exist for proxy server access
  • Automatic deployment steps:
    1. Prompt for instance name (auto-detected from existing volumes)
    2. Prompt for internal service port
    3. Prompt for domain name
    4. Generate FRP client configuration (frpc.toml)
    5. Start Docker container with FRP client
    6. Update proxy server configuration
    7. Display container operation commands

Environment Variable Priority

Configuration files are loaded in the following priority order:

1. .env.development (highest priority)
2. .env.production
3. .env (default)

Files can be located in either the current working directory or the script directory.

Interactive Prompts

If environment variables are not set, the script will prompt for:

• Instance name (auto-suggests from existing instances)
• Internal service port (default: 3000)
• Domain name for routing
• Docker network selection

Container Management Commands

Traefik Container (Traefik Mode)

# Start/run container
docker run -d --name traefik --restart=unless-stopped \
  -p 80:80 -p 443:443 -p 127.0.0.1:8080:8080 \
  -v /var/run/docker.sock:/var/run/docker.sock:ro \
  -v traefik_data:/etc/traefik traefik:latest

# Restart container
docker restart traefik

# Access container (as ubuntu user)
docker exec -it traefik /bin/sh

# Access container (as root)
docker exec -it -u root traefik /bin/sh

# View logs
docker logs --tail 50 traefik

# Inspect container
docker inspect traefik

# Remove container
docker rm -f traefik

# Access Traefik Dashboard
http://localhost:8080

# Complete removal (including data)
docker rm -f traefik
docker volume rm traefik_data

FRP Container (FRP Mode)

# Run container
docker run --restart=always -d \
  [--network <NETWORK_NAME>] \
  -v ${INSTANCE_NAME}-frpc:/etc/frp \
  --name ${INSTANCE_NAME}-frpc \
  snowdreamtech/frpc:0.62.0-alpine3.21

# Access container
docker exec -it ${INSTANCE_NAME}-frpc sh

# View logs
docker logs --tail 50 ${INSTANCE_NAME}-frpc

# Inspect container
docker inspect ${INSTANCE_NAME}-frpc

# Remove container
docker rm -f ${INSTANCE_NAME}-frpc

Configuration Notes

• Traefik Dynamic Loading: By default, Traefik does not restart after configuration updates (RESTART_TRAEFIK=false). Traefik will dynamically load new configurations automatically.
• Network Configuration: Application containers must be connected to the traefik-public network for Traefik routing to work.
• Sub-path Support: Domain names can include sub-paths (e.g., example.com/api) for path-based routing.