rvs-prxy/Design_Doc/tech/traefik/imple.md

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:

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

./auto-sys-deploy.sh setup-rvs-prxy

Using the New Script:

# 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