# Traefik Implementation Documentation

## Overview

This document outlines the implementation of the new proxy architecture that connects to a "Target Proxy Server" and configures Traefik to route traffic to an existing "Application Service". This implementation follows the instructions in `Design_Doc/instructions.md` and aims to handle the target as a "Proxy Server" that directly runs Traefik instead of using FRP (Fast Reverse Proxy).

## Architecture Flow

### New Architecture vs Old Architecture

**Old Architecture (FRP-based):**
```
Application Service -> FRPC (Client) -> FRP Server -> Public Access
```

**New Architecture (Traefik-based):**
```
Application Service -> Target Proxy Server (with Traefik) -> Public Access
```

### Key Components

1. **Target Proxy Server**: A server running Traefik as a reverse proxy
2. **Application Service**: The service running on the target server that needs to be exposed
3. **Traefik**: Docker container that handles routing and SSL certificates
4. **Docker Volumes**: For persistent configuration storage
5. **Environment Configuration**: Using .env files to store parameters

## Implementation Details

### 1. New Proxy Script: `proxy-to-target.sh`

Created `proxy-to-target.sh` to connect to the Target Proxy Server using the configuration pattern from `.env.deploy.eg` and `.envDeploySample`:

- Uses SSH to connect to target server
- Checks if Traefik container exists on target server
- Creates Traefik container if non-existing
- Configures Traefik to connect to Application Service using environment parameters
- Includes commands for setup, deployment, status checks, and logging

### 2. Environment Configuration

Updated `.env.example` and `.env.development` files to include both old FRP parameters and new Target Proxy Server parameters:

- **Old FRP Parameters** (preserved):
  - `FRP_SERVER_ADDR`: FRP server address
  - `FRP_SERVER_PORT`: FRP server port
  - `PROXY_WEB_PORT`: Remote port for web proxy, etc.

- **New Target Proxy Server Parameters**:
  - `TARGET_SERVER`: Target Proxy Server IP/hostname
  - `TARGET_USER`: Username for SSH access to target server
  - `SSH_KEY_FILE_NAME`: SSH key file name for authentication
  - `SSH_PORT`: SSH port (default 22)
  - `TARGET_SERVICE_NAME`: Name of the Application Service Docker container
  - `TARGET_SERVICE_PORT`: Port the Application Service is listening on
  - `DOCKER_NETWORK`: Docker network for connecting Traefik to the Application Service
  - `DOMAIN_NAME`: Domain for Traefik routing and SSL certificates
  - `SKIP_FRP`: Flag to skip FRP setup and use Traefik-only mode

### 3. Enhanced `auto-sys-deploy.sh` Script

Modified the existing `auto-sys-deploy.sh` script to support both old FRP and new Traefik-only modes:

- **Backward Compatibility**: Old FRP functionality preserved and works as before
- **SKIP_FRP Flag**: When set to `true`, the script skips all FRP-related setup and only configures Traefik
- **Traefik Functions**: Added new functions to connect to target server, create Traefik containers, and configure routing
- **Parameter Support**: Supports both old and new environment parameters

### 4. Traefik Container Management

#### Creation Process:
1. Check if Traefik container already exists on target server
2. Create necessary directories (`/etc/traefik/acme`, `/etc/traefik/config`)
3. Generate basic Traefik configuration (`traefik.yml`) with:
   - API dashboard (insecure for development)
   - Web and websecure entry points
   - Let's Encrypt certificate resolver
   - Docker provider configuration
   - File provider for dynamic config
4. Create docker-compose.yml for Traefik with appropriate volumes and ports
5. Create external network if needed (`traefik-public`)
6. Start the Traefik container

#### Configuration Process:
1. Create dynamic configuration file (`app-service.yml`) with routing rules
2. Connect Traefik to specified Docker network if required
3. Restart Traefik to apply new configuration
4. Configure routing to Application Service with:
   - HTTP and HTTPS routers for the specified domain
   - TLS with Let's Encrypt certificate resolver
   - Load balancer pointing to Application Service

## Application(s) Connection Approach
- Traefik contianer creates a **docker network as traefik-public**
- All Application(s) must connect to docker network name **traefik-public** for container connection by expose port(s).
- Traefik contianer talking to any application(s) is using this **traefik-public** with **TARGET_SERVICE_NAME** and **TARGET_SERVICE_PORT**.

## Technical Implementation

### SSH Connection Management
- Uses SSH keys for authentication to target server
- Executes commands remotely using `ssh_exec` function
- Supports custom SSH ports via `SSH_PORT` environment variable

### Docker Integration
- Checks for existing containers and volumes
- Creates necessary Docker networks if they don't exist
- Connects containers to networks for internal communication
- Handles volume persistence for configuration files

### Traefik Configuration
- Uses both static (`traefik.yml`) and dynamic (file provider) configurations
- Implements automatic SSL certificate management with Let's Encrypt
- Supports multiple entry points and routing rules
- Configures load balancing to Application Service

## Usage Instructions

### Traefik-Only Mode:
```bash
# Use environment variables
SKIP_FRP=true TARGET_SERVER=your-server.com TARGET_USER=your-user \
TARGET_SERVICE_NAME=your-app TARGET_SERVICE_PORT=3000 \
DOMAIN_NAME=your-domain.com ./auto-sys-deploy.sh setup-rvs-prxy

# Or set parameters in .env file and run:
SKIP_FRP=true ./auto-sys-deploy.sh setup-rvs-prxy
```

### Traditional FRP Mode (unchanged):
```bash
./auto-sys-deploy.sh setup-rvs-prxy
```

### Using the New Script:
```bash
# Setup proxy configuration
./proxy-to-target.sh setup-proxy

# Deploy files to target server
./proxy-to-target.sh deploy

# Check status of services
./proxy-to-target.sh status

# View Traefik logs
./proxy-to-target.sh logs
```

## Security Considerations

- SSH key authentication required for target server access
- Traefik dashboard protected with basic authentication
- Automatic SSL certificates for secure communication
- Isolated Docker networks for container communication
- Configuration files stored in protected directories

## Maintenance and Operations

### Backup and Recovery
- Configuration files stored in Docker volumes
- Automatic backups created when updating configurations
- Version control for configuration changes

### Monitoring and Logging
- Traefik logs available via Docker commands
- Dashboard access for real-time monitoring
- Health checks for both Application Service and Traefik

### Updates and Scaling
- Dynamic configuration allows runtime updates
- Supports multiple services on single Traefik instance
- Easy to add new domains and routing rules