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

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:

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

# 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