134 lines
5.9 KiB
Markdown
134 lines
5.9 KiB
Markdown
# Single Traefik Instance Per Target Server - Documentation Architecture
|
|
|
|
## Problem Statement
|
|
|
|
The current reverse proxy system implementation in the rvs-prxy project allows multiple Traefik instances to run on a single Target Server, which violates the architectural requirement for a unique Traefik instance per server. The system should ensure:
|
|
- Container name is always `traefik`
|
|
- Data volume name is always `traefik_data`
|
|
- Only one instance runs per Target Server
|
|
- If Traefik doesn't exist, create it dynamically
|
|
- If Traefik exists, use the existing container and volume
|
|
|
|
## Current Implementation Issue
|
|
|
|
In the current `rvs-prxy/auto-sys-deploy.sh` implementation, when `FRP=false` (Traefik mode), the script creates Traefik containers and volumes using the `INSTANCE_NAME` as a prefix:
|
|
|
|
```bash
|
|
# Current approach creates:
|
|
# - Container: ${INSTANCE_NAME}-traefik (from THIS_INSTANCE variable)
|
|
# - Volume: ${INSTANCE_NAME}-traefik_data (from THIS_INSTANCE-traefik_data)
|
|
```
|
|
|
|
This approach allows multiple Traefik deployments on the same target server, leading to:
|
|
- Port conflicts on standard ports (80, 443, 8080)
|
|
- Resource duplication and inefficient utilization
|
|
- Management complexity with multiple instances
|
|
- Potential routing conflicts
|
|
|
|
## Proposed Solution Architecture
|
|
|
|
### Traefik Instance Management Logic
|
|
|
|
The system must implement a check-and-reuse approach before creating Traefik resources:
|
|
|
|
```bash
|
|
# Pseudo-code implementation
|
|
IF Traefik container exists (named "traefik") THEN
|
|
USE existing container
|
|
ELSE
|
|
CREATE new container with name "traefik"
|
|
ENDIF
|
|
|
|
IF Traefik volume exists (named "traefik_data") THEN
|
|
USE existing volume
|
|
ELSE
|
|
CREATE new volume with name "traefik_data"
|
|
ENDIF
|
|
```
|
|
|
|
### Container Configuration Requirements
|
|
- **Container Name**: Fixed as "traefik" (not using INSTANCE_NAME prefix)
|
|
- **Restart Policy**: `unless-stopped` for high availability
|
|
- **Port Mapping**: Standard ports 80, 443, 8080 (dashboard on localhost only)
|
|
- **Volume Mounts**: `/var/run/docker.sock` for Docker provider, `traefik_data` for persistence
|
|
|
|
### Volume Configuration Requirements
|
|
- **Volume Name**: Fixed as "traefik_data" (not using INSTANCE_NAME prefix)
|
|
- **Purpose**: Store ACME certificates, dynamic configurations, and runtime data
|
|
- **Permissions**: Ensure proper ownership (1000:1000) for certificate files
|
|
- **Persistence**: Maintain across container restarts and updates
|
|
|
|
### Dynamic Configuration Management
|
|
Instead of multiple Traefik instances, each new application should be configured as a dynamic configuration within the single instance:
|
|
|
|
- Store application-specific routing in `/etc/traefik/config/` within the shared volume
|
|
- Use Traefik's file provider to load configurations dynamically
|
|
- Name configuration files uniquely to avoid conflicts
|
|
- Restart Traefik only when necessary to load new configurations
|
|
|
|
## Implementation Integration with Existing Script
|
|
|
|
### Integration with Current Script Logic
|
|
The implementation must extend the existing foundation while ensuring the container and volume names remain fixed:
|
|
|
|
- Modify the `create_traefik_container_on_target` function to use fixed names
|
|
- Update volume creation to use `traefik_data` instead of `${THIS_INSTANCE}-traefik_data`
|
|
- Preserve existing Traefik configuration and docker-compose generation logic
|
|
- Maintain compatibility with existing parameters in `.env*` files
|
|
|
|
### SSH Connection Configuration
|
|
Since the rvs-prxy script operates in Traefik mode by connecting to a target server via SSH, the implementation must:
|
|
- Execute container and volume checks via SSH commands on the target server
|
|
- Use SSH to create or verify existing Traefik resources
|
|
- Maintain existing SSH connection patterns and authentication methods
|
|
- Preserve the existing `ssh_exec` and `scp_upload` functions
|
|
|
|
### Docker Resource Translation Rules Adjustment
|
|
- Modify volume creation to use fixed name `traefik_data` instead of prefixed names
|
|
- Update container creation to use fixed name `traefik`
|
|
- Maintain all other volume, network, and port configuration patterns
|
|
|
|
### Container Auto-Restart Policy Enforcement
|
|
- The `restart: unless-stopped` policy must be applied to the fixed-name container
|
|
- This ensures the unique Traefik instance remains available across host reboots
|
|
|
|
## Verification and Testing Approach
|
|
|
|
### Pre-Deployment Verification
|
|
- Check if container named "traefik" exists on target system via SSH
|
|
- Verify if volume named "traefik_data" exists on target system via SSH
|
|
- Confirm existing Traefik instance is operational (if present)
|
|
- Validate port availability for Traefik (80, 443, 8080)
|
|
|
|
### Post-Deployment Verification
|
|
- Confirm "traefik" container is running with expected configuration
|
|
- Verify application routing is correctly configured within Traefik
|
|
- Test application accessibility via configured domain
|
|
- Validate SSL certificate acquisition if applicable
|
|
|
|
## Security and Access Considerations
|
|
|
|
### SSH Connection Configuration
|
|
- Maintain existing SSH connection patterns to target server
|
|
- Ensure secure file transfer of configuration files to target server
|
|
- Preserve SSH key authentication and fallback mechanisms
|
|
- Use existing `ssh_exec` function for all remote operations
|
|
|
|
### Network Security
|
|
- Restrict Traefik dashboard access to localhost only (127.0.0.1:8080)
|
|
- Maintain existing network integration patterns
|
|
- Ensure secure communication between application and Traefik containers
|
|
|
|
## Error Handling and Recovery
|
|
|
|
### Failure Scenarios
|
|
- Handle cases where fixed-name container already exists but with different configuration
|
|
- Implement proper error messages for port conflicts
|
|
- Provide clear guidance when existing Traefik instance is incompatible
|
|
- Enable graceful fallback when volume creation fails
|
|
|
|
### Recovery Procedures
|
|
- Document manual cleanup procedures for inconsistent states
|
|
- Provide restart commands for the fixed-name Traefik container
|
|
- Include volume inspection and cleanup commands
|
|
- Maintain existing troubleshooting patterns from the script |