Torrust Tracker Deploy - Perl PoC (Historical)

⚠️ PROOF OF CONCEPT - HISTORICAL REFERENCE ONLY

This repository contains the second proof of concept for Torrust Tracker deployment infrastructure. It is no longer actively developed and exists only as a historical reference.

👉 For production use, see Torrust Tracker Deployer

---

Purpose

This was the second proof of concept in a series exploring deployment automation for the Torrust Tracker:

1. Bash/OpenTofu/cloud-init PoC

   • Technologies: Bash scripts, OpenTofu, cloud-init, Docker Compose
   • Focus: Infrastructure as Code with libvirt/KVM and cloud deployment
   • Status: ✅ Historical reference - Completed its research goals

2. Perl/Ansible PoC (this repository)

   • Technologies: Perl, OpenTofu, Ansible, libvirt/KVM, cloud-init, Docker Compose
   • Focus: Declarative configuration management with mature automation tools
   • Status: ✅ Historical reference - Completed its research goals

3. Torrust Tracker Deployer (production)

   • Technologies: Rust, OpenTofu, Ansible, LXD, cloud-init, Docker Compose
   • Focus: Type-safe, performance-oriented deployment tooling
   • Status: 🚀 Production-ready - Active development

What We Learned

This proof of concept successfully validated:

• ✅ Ansible for declarative configuration management
• ✅ Perl as a viable deployment scripting language
• ✅ Integration of OpenTofu with configuration management tools
• ✅ Structured approach to deployment orchestration
• ✅ Importance of type safety and testing infrastructure

These learnings directly influenced the production Torrust Tracker Deployer's architecture.

Migration Path

If you're using this PoC, migrate to the production Torrust Tracker Deployer:

1. Review the Torrust Tracker Deployer README
2. Check the migration guide (if available)
3. Open an issue if you need assistance

---

Original PoC Documentation

Torrust Tracker Deployment Tool

A modern Perl console application for deploying Torrust Tracker to cloud providers using OpenTofu/Terraform and cloud-init for VM configuration.

Architecture Decision: Cloud-Init vs Golden Images

This project uses cloud-init for VM configuration instead of building golden images with tools like Packer. While golden images could speed up provisioning by pre-installing the torrust user, Docker, and other basic setup, we chose cloud-init because:

• Cross-cloud compatibility: No way to generate a single base image that works across multiple
  cloud providers
• Deployment frequency: Since deployment is typically done once, the extra time for cloud-init
  configuration is acceptable
• Simplicity: Eliminates the complexity of managing and maintaining custom images across
  different providers
• Transparency: All VM configuration is visible in the cloud-init templates

Perl Version Requirement

This project requires Perl v5.38 or higher. We chose v5.38 specifically because:

• Modern Perl features: Enables strict and warnings by default without explicit use statements
• GitHub Actions compatibility: v5.38 is the default Perl version in Ubuntu 24.04 LTS
  (GitHub Actions runners)
• No additional CI setup: Avoids the overhead of installing newer Perl versions in CI, which
  can be slow
• Modern enough: Provides all the modern Perl features we need for this application

You can check your Perl version with:

perl -v

If you need to install a newer Perl version, consider using perlbrew for
local development.

Installation

First, install system dependencies:

# On Ubuntu/Debian:
sudo apt install libssh2-1-dev ansible

Install cpanminus:

curl -L https://cpanmin.us | perl - --sudo App::cpanminus

Install local::lib:

cpanm --local-lib=~/perl5 local::lib && eval $(perl -I ~/perl5/lib/perl5/ -Mlocal::lib)

Install Carmel dependency manager:

cpanm Carmel

Set up the environment (add carmel to PATH and set PERL5LIB):

eval $(perl -I ~/perl5/lib/perl5/ -Mlocal::lib)
export PATH="$HOME/perl5/bin:$PATH"

Note: You need to run the eval $(perl -I ~/perl5/lib/perl5/ -Mlocal::lib) command in each new terminal session, or add it to your shell profile (.bashrc, .zshrc, etc.).

Then install project dependencies:

carmel install

Usage

Run the application:

carmel exec -- ./bin/torrust-deploy help

Commands

provision

Provision a Torrust Tracker virtual machine using OpenTofu with libvirt provider:

carmel exec -- ./bin/torrust-deploy provision

This command will:

1. Copy OpenTofu configuration templates from templates/tofu/ directory
2. Initialize OpenTofu if needed
3. Create a minimal Ubuntu 22.04 LTS VM with hardcoded configuration
4. Wait for cloud-init completion via SSH monitoring
5. Verify SSH key authentication and system readiness
6. Run post-provision verification using Ansible (experimental)
7. Display final system summary

Requirements

Before using the provision command, ensure you have:

• OpenTofu installed (Download from opentofu.org)

• Ansible installed for post-provision verification and configuration:

  # On Ubuntu/Debian:
  sudo apt install ansible
  
  # Verify installation:
  ansible --version

• libvirt/KVM installed and running:

  sudo apt install qemu-kvm libvirt-daemon-system libvirt-clients bridge-utils
  sudo systemctl enable libvirtd
  sudo systemctl start libvirtd
  sudo usermod -aG libvirt $USER

• SSH development libraries for Net::SSH2 Perl module:

  sudo apt install libssh2-1-dev

• Default libvirt storage pool configured:

  virsh pool-list --all
  # If 'default' pool doesn't exist, create it:
  sudo virsh pool-define-as default dir - - - - "/var/lib/libvirt/images"
  sudo virsh pool-build default
  sudo virsh pool-start default
  sudo virsh pool-autostart default

VM Configuration

The VM is created with:

• OS: Ubuntu 22.04 LTS (Cloud Image)
• CPU: 2 vCPUs
• Memory: 2GB RAM
• Disk: 10GB
• Network: NAT with DHCP (192.168.122.0/24)
• User: torrust (with sudo access)
• SSH: Enabled (requires SSH key configuration in cloud-init.yml)

After provisioning, you can find the VM IP with:

cd build/tofu && tofu output

Testing

The project includes two types of tests:

Unit Tests

Run unit tests that don't require virtualization:

./script/test unit

These tests can run in CI environments and test individual components in isolation.

Integration Tests

Run integration tests that require multiple components to work together:

./script/test integration

It does not require any special setup and can be run on any machine with the necessary dependencies installed.

Container Tests

Run tests that require Docker:

./script/test container

E2E Tests

Run end-to-end tests that require local virtualization support:

./script/test e2e

Requirements for E2E tests:

• Local machine with KVM/libvirt support
• OpenTofu installed
• Ansible installed
• Required system tools: qemu-system-x86_64, sshpass
• SSH development libraries: libssh2-1-dev
• Cannot run in CI environments

All Tests

Run both unit and E2E tests:

./script/test-all

E2E tests will be automatically skipped in CI environments or when virtualization tools are not available.