Create Docker image for the deployer to use it without needing to install the dependencies (OpenTofu, Ansible, etc)

[josecelano]

Description

Create an official Docker image for the Torrust Tracker Deployer that bundles all required dependencies (OpenTofu, Ansible, etc.) so users can run the deployer without installing these tools locally. The image should support mounting user data and build directories for persistence and flexibility.

⚠️ Important Limitation: The Docker image only supports cloud providers (Hetzner). The LXD provider is not supported when running the deployer from within a container, because LXD requires system-level access to local virtualization that cannot be provided inside a container. LXD users should run the deployer directly on the host.

Goals

• Provide a containerized version of the deployer with all dependencies pre-installed
• Enable users to run deployments without local dependency installation
• Support volume mounts for data/, build/, and envs/ directories
• Publish the image to Docker Hub or GitHub Container Registry (GHCR)
• Document usage with clear examples

Dependencies to Include

Based on packages/dependency-installer/README.md:

1. OpenTofu - Infrastructure provisioning tool (v1.8.x or later)
2. Ansible - Configuration management tool (v2.15.x or later)
3. SSH Client - For remote connections to provisioned VMs
4. Git - For version control operations

Docker Image Structure

docker/deployer/
├── Dockerfile          # Multi-stage build for deployer image
├── entry_script_sh     # Container initialization script
└── README.md           # Usage documentation

Volume Mount Structure

Host Path	Container Path	Purpose
./data/	/var/lib/torrust/deployer/data	Environment state and persistence
./build/	/var/lib/torrust/deployer/build	Generated configuration files
./envs/	/var/lib/torrust/deployer/envs	User environment configuration files
~/.ssh/	/root/.ssh	SSH keys for remote access

Usage Example

# Pull the image
docker pull torrust/tracker-deployer:latest

# Run a command
docker run --rm \
  -v $(pwd)/data:/var/lib/torrust/deployer/data \
  -v $(pwd)/build:/var/lib/torrust/deployer/build \
  -v $(pwd)/envs:/var/lib/torrust/deployer/envs \
  -v ~/.ssh:/root/.ssh:ro \
  torrust/tracker-deployer:latest \
  create --env-file /var/lib/torrust/deployer/envs/my-env.json

Context

• Parent Epic: Roadmap #1 - Project Roadmap (Section 4.1)
• Specification: docs/issues/{issue-number}-create-docker-image-for-deployer.md
• Related Docs:
  • Dependency installer documentation: packages/dependency-installer/README.md
  • Existing Docker configs: docker/provisioned-instance/, docker/ssh-server/
  • User guide: docs/user-guide/README.md

Provider-Specific Considerations

✅ Supported: Hetzner (Cloud Provider)

Hetzner deployments work fully in the Docker container because:

• Uses API calls to provision remote cloud servers
• SSH connections are made to remote machines
• No local virtualization required

❌ Not Supported: LXD (Local Provider)

LXD cannot work inside Docker because:

• LXD manages local virtual machines through system-level APIs
• Requires access to host virtualization features (KVM, QEMU)
• Running LXD inside Docker requires privileged containers with full device access
• This defeats the purpose of containerization and introduces security risks

For LXD users: Install the deployer directly on the host using the native installation method.