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.rvs-prxy` with reverse proxy settings
- Deploys Traefik or FRP container
- **No application service check** (your app is not needed yet)

**Configuration File Created:**
- `.env.rvs-prxy` - 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

(Select `1) Setup New Domain` from the setup menu. Options `2) Setup Port Exposure` and `3) Setup External Service Domain` are covered in Step 4 and Step 5.)

**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.

### Step 4: Setup Port Exposure (Alternative to Domain-Based Routing)

Instead of using domain-based routing, you can expose host ports directly to connect to container ports. This is useful when you want to access services via `http://<host-ip>:<port>` without domain name routing:

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

**How It Works:**
- Any access to the host on a specific port (e.g., `18081`) connects directly to a container's port
- No domain name required - works with direct IP/port access
- Example: `http://this-host:18081` → connects to container `ph-web-1003-nginx_cntr` port `80`

**Configuration File Required:**
- Create `.env-port-<port>` file (e.g., `.env-port-18081`)

**Example `.env-port-18081`:**
```bash
HOST_PORT="18081"
CONTAINER_NAME="ph-web-1003-nginx_cntr"
CONTAINER_PORT="80"
```

**What Happens:**
- **Checks if Traefik reverse proxy is running**
- **Checks if target container is running**
- Creates port routing configuration in Traefik
- Exposes host port `18081` to route to container port `80`
- Service accessible at: `http://<host-ip>:18081`

**Use Cases:**
- Internal services that don't need domain-based routing
- Development/testing environments
- Services accessed via IP:port directly
- Multiple containers exposing different ports on the same host

**Batch Processing:**
You can setup multiple port exposures at once by creating multiple `.env-port-*` files:
```
.env-port-18081
.env-port-18082
.env-port-18083
```
The script will process all port configuration files in batch mode.

### Step 5: Setup External Service Domain (Route a Domain to an External Web Service)

Use this mode when the upstream is **not** a local container on this host but an existing web service reached by URL (a hosted app, SaaS, or another server). No local container is required.

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

**The wizard will ask you (External service settings only):**

1. Domain name, sub-path optional (e.g., `box.example.com` or `box.example.com/api`)
2. External service URL (e.g., `https://cornersendbox-impact-vms.lovable.app/`)

**What Happens:**
- **Checks if Traefik reverse proxy is running** (Traefik mode only -- FRP is not supported for HTTP routing)
- Creates `.env-ext-<domain>` with the domain and external URL
- Writes a dynamic Traefik config that terminates TLS for the public domain and forwards to the external URL
- Obtains a Let's Encrypt certificate for the public domain

**Configuration File Created:**
- `.env-ext-<domain>` - External service configuration (e.g., `.env-ext-box-example-com-api`)

**Example `.env-ext-box-example-com-api`:**
```bash
DOMAIN_NAME="box.example.com/api"
EXTERNAL_URL="https://cornersendbox-impact-vms.lovable.app/"
```

**Example output:**
```
[INFO] Setup External Service Domain
[INFO] New external service domain has been configured: box.example.com/api
[INFO] Public URL: https://box.example.com/api
[INFO] Forwarding to: https://cornersendbox-impact-vms.lovable.app
```

**Routing Semantics:**
- `https://box.example.com/api/x` → `https://cornersendbox-impact-vms.lovable.app/x` (public sub-path stripped, origin base path added)
- The origin receives its own `Host` header (`passHostHeader: false`), so the upstream must accept the request by its own hostname
- Origin TLS is verified with the system trust store; no `insecureSkipVerify` is generated
- Origin default port is `443` for `https` and `80` for `http` unless a port is present in the URL

**Batch Processing:**
Create multiple `.env-ext-*` files to publish several external services in one run:
```
.env-ext-box-example-com-api
.env-ext-demo-example-net
```

**Troubleshooting:**
- The script checks whether the external hostname resolves and only warns if it does not; note that Traefik resolves the name itself, inside its container

### Alternative: Using Configuration Files Directly

**For Reverse Proxy Setup:**
1. Create `.env.rvs-prxy` 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.rvs-prxy` 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
     ```

**For Port Exposure Setup:**

The script supports port-based routing without domain names:

1. **With `.env-port-<port>` file:**
   - Create `.env-port-<port>` file (e.g., `.env-port-18081`)
   - Ensure Traefik reverse proxy is running
   - Ensure target container is running
   - Run: `curl -s "https://www.ivantito.com/app-pub/demos/test/deploy-rvs-prxy.sh" | bash`

2. **Batch processing (multiple ports):**
   - Create multiple `.env-port-*` files in the same directory
   - Ensure Traefik reverse proxy is running
   - Ensure all target containers are running
   - Run: `curl -s "https://www.ivantito.com/app-pub/demos/test/deploy-rvs-prxy.sh" | bash`
   - Script automatically processes all `.env-port-*` files in batch mode
   - Example output:
     ```
     [INFO] Found 2 port config files, will process all in batch mode
     [INFO] =========================================
     [INFO] Processing port 1 of 2: .env-port-18081
     [INFO] =========================================
     [INFO] Setting up port exposure: Host port 18081 -> Container my-nginx:80
     ...
     [INFO] =========================================
     [INFO] Processing port 2 of 2: .env-port-18082
     [INFO] =========================================
     ...
[INFO] Batch processing completed: 2 port(s) processed
      ```

**For External Service Setup:**

The script supports routing a domain to an external web service URL:

1. **With `.env-ext-<domain>` file:**
   - Create `.env-ext-<domain>` file with the domain and external URL
   - Ensure Traefik reverse proxy is running
   - Run: `curl -s "https://www.ivantito.com/app-pub/demos/test/deploy-rvs-prxy.sh" | bash`

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

3. **Mode precedence:** if `.env-port-*` files exist, the script runs port batch processing and skips domain and external service files (same precedence as before: port, then external service, then domain)

### Step 6: Manage Existing Configurations (Optional)

To view and remove existing domain, external service or port configurations:

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

**What Happens:**
- Lists all current domain configurations (`.env-<domain>` files)
- Lists all current external service configurations (`.env-ext-<domain>` files)
- Lists all current port configurations (`.env-port-<port>` files)
- Prompts you to select which configurations to remove (enter numbers separated by space)
- **For domains**: Removes the configuration file AND removes the routing config from Traefik
- **For external services**: Removes the configuration file AND removes the routing config from Traefik
- **For ports**: Removes the configuration file, removes the routing config from Traefik, removes the entry point, and recreates Traefik container without that port

**Example Output:**
```
=============================================
Reverse Proxy Configuration Manager
=============================================

Current Configurations:

Domains:
  1. .env-app-example-com - app.example.com (my-app-container)
  2. .env-api-test-com - api.test.com (api-service)

Ports:
  3. .env-port-18081 - Host port 18081 -> nginx-container
  4. .env-port-18082 - Host port 18082 -> api-container

External Services:
  5. .env-ext-box-example-com-api - box.example.com/api -> https://cornersendbox-impact-vms.lovable.app

Select configurations to remove (enter numbers separated by space, or 'q' to quit): 1 5
[INFO] Removing: .env-app-example-com
[INFO] Removing domain config from Traefik: app.example.com
[INFO] Removed: .env-app-example-com
[INFO] Removing: .env-ext-box-example-com-api
[INFO] Removing external service config from Traefik: box.example.com/api
[INFO] Removed: .env-ext-box-example-com-api
```

**Important Notes:**
- Removing a port configuration will restart the Traefik container (brief downtime ~5 seconds)
- Domain and external service removal does not require Traefik restart (dynamic config removal)
- All changes are permanent and cannot be undone - make sure you want to remove before confirming

### Step 7: Configure Extra Traefik Entrypoints (QUIC, Custom Ports, etc.)

Beyond the default entrypoints (`web` on :80, `websecure` on :443), you can add extra entrypoints such as HTTP/3 QUIC (UDP 443) or other custom protocols. Entrypoints are defined via command-line arguments to the Traefik container, so the container must be recreated to apply them.

**Configuration Variable:**
- `EXTRA_ENTRYPOINTS` in `.env.rvs-prxy` (global proxy config) or per-domain `.env-<domain>` files
- Format: `name=:port/protocol,name2=:port` (comma-separated)
- Protocol defaults to `tcp` if omitted; use `/udp` for UDP entrypoints
- Example: `quic=:443/udp` creates entrypoint `quic` listening on UDP port 443
- Example: `quic=:443/udp, mqtt=:1883` adds both QUIC and a custom TCP entrypoint on port 1883

---

#### Scenario A: First-Time Setup (Traefik Not Yet Created)

The wizard asks for extra entrypoints during the Traefik configuration step. You can also pre-configure them:

1. Create `.env.rvs-prxy` with the entrypoints setting:
   ```bash
   EXTRA_ENTRYPOINTS="quic=:443/udp"
   ```
2. Run the script as usual:
   ```bash
   curl -s "https://www.ivantito.com/app-pub/demos/test/deploy-rvs-prxy.sh" | bash
   ```
3. **What happens:**
   - The docker-compose.yml generated by the script includes the extra entrypoints in the `command:` section and their port mappings in the `ports:` section
   - The Traefik container starts with `--entrypoints.quic.address=:443/udp` and `-p 443:443/udp`
   - Both TCP and UDP on port 443 are now mapped (QUIC shares port 443 with HTTPS)

---

#### Scenario B: Running Traefik — Add New Extra Entrypoints

To add a new entrypoint (e.g., QUIC) to a Traefik container that is already running:

1. Set `EXTRA_ENTRYPOINTS` in `.env.rvs-prxy` (proxy config) or in the per-domain `.env-<domain>` file:
   ```bash
   EXTRA_ENTRYPOINTS="quic=:443/udp"
   ```
   If the variable already has values, add the new one with a comma:
   ```bash
   EXTRA_ENTRYPOINTS="quic=:443/udp, mqtt=:1883"
   ```

2. Run the script:
   ```bash
   curl -s "https://www.ivantito.com/app-pub/demos/test/deploy-rvs-prxy.sh" | bash
   ```
   The script detects the running Traefik container and checks if `EXTRA_ENTRYPOINTS` has changed.

3. **What happens:**
   - The script calls `parse_extra_entrypoints()` which parses the variable
   - It inspects the current Traefik container's command-line args
   - If any extra entrypoints are missing from the running container, the script:
     1. Stops and removes the current Traefik container (data in `traefik_data` volume is preserved)
     2. Recreates the container with all standard entrypoints plus the new extra entrypoints and their port mappings
   - Brief downtime (~5 seconds) while the container is recreated
   - Existing domain routing and port exposure configurations remain intact (they are stored in the volume)

4. **Expected output** (proxy setup mode — `deploy-rvs-prxy.sh`):
   ```
   [INFO] Extra entrypoints changed, recreating Traefik container to apply...
   [INFO] Updating Traefik container...
   [INFO] Traefik container recreated with new entry points
   ```
   **Expected output** (domain setup mode — `.env-p2prly1-ivantito-com`):
   ```
   [INFO] Loading domain config from .env-p2prly1-ivantito-com
   [INFO] Detected running Traefik reverse proxy
   [INFO] Extra entrypoints changed, recreating Traefik container to apply...
   [INFO] Checking if Application Service is running locally...
   ...
   [INFO] Traefik configured to route traffic to Application Service
   ```

5. **Verify the new entrypoint is active:**
   ```bash
   # Check container args for entrypoint definitions
   docker inspect traefik --format '{{range .Config.Cmd}}{{println .}}{{end}}' | grep entrypoints
   # Should show: --entrypoints.quic.address=:443/udp

   # Check port mappings (TCP and UDP on 443)
   docker port traefik
   # Should show: 443/tcp → 0.0.0.0:443 and 443/udp → 0.0.0.0:443
   ```

---

#### Scenario C: Running Traefik — Remove an Extra Entrypoint

1. Edit `.env.rvs-prxy` and remove the entrypoint from `EXTRA_ENTRYPOINTS`
2. Run the script to trigger the recreation with the updated entrypoints (same as Scenario B steps 2-4)

---

#### Scenario D: Running Traefik — Add/Remove During Port Exposure Setup

When you use port exposure (`--manage` or `.env-port-<port>`), the `add_traefik_entry_point()` and `manage_configurations()` functions automatically preserve all `EXTRA_ENTRYPOINTS`. Extra entrypoints are re-injected whenever the Traefik container is recreated for port operations, so they are never lost.

**No additional steps needed** — extra entrypoints configured in `.env.rvs-prxy` are automatically preserved across all port management operations.

---

**Important Notes:**
- Recreating the Traefik container causes ~5 seconds of downtime
- The `traefik_data` volume (config files, SSL certificates, ACME data) is preserved across recreations
- `EXTRA_ENTRYPOINTS` adds entrypoints to the Traefik container's command-line args. When a domain config also has a UDP port in `LOCAL_SERVICE_PORT` (e.g., `80,4443/udp`), the script automatically creates a Traefik UDP router in the domain config, so no manual routing setup is needed for that UDP port
- For port-mapped entrypoints (like port-exposure), existing `--manage` flows already handle adding/removing

## 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.rvs-prxy` configuration if it exists
2. Triggers interactive wizard if `.env.rvs-prxy` 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.rvs-prxy` 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.rvs-prxy` 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.rvs-prxy` 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.rvs-prxy` - 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`)
    - `LOCAL_SERVICE_PORT` supports comma-separated ports with protocol: `80` or `80,4443/udp`
    - First TCP port is used for HTTPS routing; additional UDP ports get automatic Traefik UDP router config

- **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.rvs-prxy` (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

When the wizard runs for an existing proxy, the setup menu offers three options:
- `1) Setup New Domain` - routes the domain to a local Docker container
- `2) Setup Port Exposure` - exposes a host port to a container port
- `3) Setup External Service Domain` - routes the domain to an external web service URL (asks for domain and URL only)

### Container Management Commands

#### Traefik Container (Traefik Mode)

**Entrypoints:**
Default entrypoints are `web` (:80) and `websecure` (:443). See **[Step 7: Configure Extra Traefik Entrypoints](#step-7-configure-extra-traefik-entrypoints-quic-custom-ports-etc)** for a complete guide on adding/removing extra entrypoints (QUIC, custom ports, etc.) during both first-time setup and on a running Traefik container.

```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 (port from DASHBOARD_PORT, default 18080)
http://localhost:${DASHBOARD_PORT:-18080}/dashboard/

# Check docker-compose.yml used to create the container (preserved after each run)
cat /tmp/docker-compose.yml

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