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

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

### Script Behavior

### Mode Selection

Set the `FRP` environment variable to control the deployment mode:

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

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