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:

```bash
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:

```bash
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:

```bash
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:**

The script supports flexible domain setup with automatic proxy mode detection:

1. **With `.env-<domain>` file (recommended):**
   - Create `.env-<domain>` file with domain configuration
   - Ensure reverse proxy is running (Traefik or FRP)
   - Ensure your application service is running
   - Run: `curl -s "https://www.ivantito.com/app-pub/demos/test/deploy-rvs-prxy.sh" | bash`

2. **Without `.env` file (auto-detection):**
   - Create `.env-<domain>` file with domain configuration
   - Ensure reverse proxy is running (script will auto-detect mode)
   - Ensure your application service is running
   - Run: `curl -s "https://www.ivantito.com/app-pub/demos/test/deploy-rvs-prxy.sh" | bash`
   - Script automatically detects running proxy (Traefik or FRP) and configures accordingly

3. **Without any config files (interactive wizard):**
   - Ensure reverse proxy is running
   - Run: `curl -s "https://www.ivantito.com/app-pub/demos/test/deploy-rvs-prxy.sh" | bash`
   - Script detects running proxy and starts wizard for domain settings

4. **Batch processing (multiple domains):**
   - Create multiple `.env-<domain>` files in the same directory
   - Ensure reverse proxy is running
   - Ensure all application services are running
   - Run: `curl -s "https://www.ivantito.com/app-pub/demos/test/deploy-rvs-prxy.sh" | bash`
   - Script automatically processes all `.env-<domain>` files in batch mode
   - Example output:
     ```
     [INFO] Found 3 domain config files, will process all in batch mode
     [INFO] =========================================
     [INFO] Processing domain 1 of 3: .env-domain1-com
     [INFO] =========================================
     [INFO] Setting up new domain: domain1.com
     ...
     [INFO] =========================================
     [INFO] Processing domain 2 of 3: .env-domain2-com
     [INFO] =========================================
     ...
     [INFO] Batch processing completed: 3 domain(s) processed
     ```

## Run this System

### Using with curl (Remote Execution)

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

```bash
# 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 detects the running proxy mode (Traefik or FRP) automatically
2. **Warning**: Displays a warning message that configuration will be overwritten
3. **Update**: The existing configuration is updated 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
- **No .env required**: Script auto-detects running proxy mode (Traefik or FRP)
- **Configuration is updated, not duplicated**: Each domain+service combination has a unique configuration
- **No service interruption**: 
  - Traefik: Dynamically loads updated configuration (no restart needed by default)
  - FRP: Restarts FRP client container to apply new configuration
- **Use case**: Useful for updating application port changes or domain routing modifications

**Example Scenario (Traefik Mode):**
```bash
# 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
# [INFO] Detected running Traefik reverse proxy
# [INFO] Setting up new domain: my.domain.com
# [INFO] New domain my.domain.com has been configured in Traefik
```

**Example Scenario (FRP Mode):**
```bash
# 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
# [INFO] Detected running FRP client container: my-instance-frpc
# [INFO] Setting up new domain: my.domain.com
# [INFO] Generated remote port 12001 for domain my.domain.com
# [INFO] New domain my.domain.com has been configured in FRP tunnel
```

### Script Behavior

### Mode Selection

The script automatically detects the proxy mode from running containers:

```bash
# Auto-detects running proxy (Traefik or FRP)
curl -s "https://www.ivantito.com/app-pub/demos/test/deploy-rvs-prxy.sh" | bash
```

**Manual override (optional):** Set the `FRP` environment variable to force a specific mode:

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

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

**Auto-detection behavior:**
- If `traefik` container is running → Traefik mode (`FRP=false`)
- If `*-frpc` container is running → FRP mode (`FRP=true`)
- If both are running → Traefik mode takes precedence
- If neither is running → Interactive wizard

### 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

#### Setup New Domain (FRP Mode)
When the FRP reverse proxy is already running, you can add new domains:

- **Prerequisites:**
  - FRP client container must be running (`${INSTANCE_NAME}-frpc`)
  - Application service must be running locally
  - `.env` file with reverse proxy configuration must exist
  - `.env-<domain>` file with domain configuration (or use interactive wizard)

- **Process:**
  1. Run the script: `curl -s "<url>/deploy-rvs-prxy.sh" | bash`
  2. Script detects existing FRP proxy and domain config
  3. Validates FRP client container is running
  4. Validates application service is running
  5. Generates a new remote port for the domain
  6. Updates frpc.toml with new proxy configuration
  7. Restarts FRP client container to apply changes
  8. Updates proxy server configuration with domain routing
  9. Domain is now accessible via HTTPS

- **Configuration Files:**
  - `.env` - Reverse proxy instance configuration (contains `INSTANCE_NAME`, `FRP_SERVER_ADDR`, etc.)
  - `.env-<domain>` - Domain-specific configuration (contains `DOMAIN_NAME`, `LOCAL_SERVICE_NAME`, `LOCAL_SERVICE_PORT`)

- **What Happens:**
  - A new TCP proxy is added to frpc.toml for the domain's service
  - A unique remote port is allocated for this domain
  - Proxy server (FRPS) is updated to route the domain to the new tunnel port
  - FRP client container is restarted to apply the new configuration

### 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)

```bash
# 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)

```bash
# 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.