174 lines
6.7 KiB
Markdown
174 lines
6.7 KiB
Markdown
# 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 |