# 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