Torrust Tracker Deployer - Packages

This directory contains reusable Rust workspace packages that support the Torrust Tracker Deployer project. These packages are designed to be modular, maintainable, and potentially reusable across other Torrust projects.

📦 Available Packages

dependency-installer/

Purpose: Dependency detection and installation utilities for development environments

Key Features:

• Detects if required development tools are installed (OpenTofu, Ansible, LXD, cargo-machete)
• Installs missing dependencies automatically
• Provides CLI for manual and automated use
• Designed for CI/CD pipelines and automated workflows
• Uses structured logging (tracing) for observability
• Exit-code based success/failure indication for automation

Use Cases:

• Setting up development environments for humans and AI agents
• Pre-flight checks in E2E test suites
• CI/CD pipeline dependency validation
• Automated development environment provisioning

Documentation: See packages/dependency-installer/README.md

deployer-types/

Purpose: Shared value objects and traits for the Torrust Tracker Deployer ecosystem

Key Features:

• Validated value objects: DomainName, Email, Username, EnvironmentName, ServiceEndpoint
• Secret wrappers: ApiToken / PlainApiToken, Password / PlainPassword (via secrecy)
• Time abstraction: Clock trait + SystemClock implementation for testability
• Error infrastructure: ErrorKind enum + Traceable trait
• Minimal dependencies (no tokio, no infrastructure)
• Both the root crate and the SDK crate depend on this package

Use Cases:

• Canonical source of cross-cutting value objects shared across workspace packages
• Enables SDK consumers to import foundational types without depending on the full root crate
• Supports independent versioning and future publishing

Documentation: See packages/deployer-types/README.md

sdk/

Purpose: Programmatic Rust SDK for deploying and managing Torrust Tracker instances

Key Features:

• Typed Deployer facade with builder pattern for configuration
• Full lifecycle support: create, provision, configure, release, run, test, destroy, purge
• Config validation and environment inspection (list, show, exists)
• Load environment config from JSON files
• Re-exports all domain types consumers need (EnvironmentCreationConfig, EnvironmentName, etc.)
• Structured error types for programmatic error handling
• Extension point: CommandProgressListener for progress callbacks

Use Cases:

• Programmatic deployer access without the CLI
• Integration testing of deployment workflows
• Building higher-level tools on top of the deployer
• External consumers that want to depend only on the SDK without CLI modules

Documentation: See packages/sdk/README.md

🏗️ Package Architecture

All packages in this directory:

• Are part of a Cargo workspace (defined in root Cargo.toml)
• Can be used independently or as library crates
• Follow the project's development principles (observability, testability, user-friendliness)
• Provide both CLI binaries and programmatic APIs
• Use structured logging via the tracing crate
• Follow consistent error handling patterns

🚀 Using Packages

As Library Crates

// Add to your Cargo.toml
[dependencies]
torrust-linting = "0.1.0"  # external crate: https://crates.io/crates/torrust-linting
torrust-dependency-installer = { path = "packages/dependency-installer" }
torrust-tracker-deployer-sdk = { path = "packages/sdk" }

As CLI Binaries

# Run the linter
cargo run --bin linter all

# Run the dependency installer
cargo run --bin dependency-installer check
cargo run --bin dependency-installer install

SDK Examples

cargo run --example sdk_basic_usage -p torrust-tracker-deployer-sdk
cargo run --example sdk_full_deployment -p torrust-tracker-deployer-sdk
cargo run --example sdk_error_handling -p torrust-tracker-deployer-sdk
cargo run --example sdk_create_from_json_file -p torrust-tracker-deployer-sdk
cargo run --example sdk_validate_config -p torrust-tracker-deployer-sdk

🎯 Package Design Principles

Automation-First Design

Packages prioritize automation and CI/CD workflows:

• Exit codes indicate success/failure (0 = success, non-zero = failure)
• Structured logging provides rich context without parsing output
• Flags for verbosity (--verbose, --log-level) control output detail
• Minimal output by default, detailed only when needed

Type Safety

• Use strongly-typed enums and structs
• Leverage Rust's type system for compile-time guarantees
• Avoid stringly-typed APIs

Error Handling

• Clear, actionable error messages
• Preserve error context with source chains
• Use thiserror for structured error types

Extensibility

• Easy to add new functionality (linters, dependencies)
• Plugin-like architecture where appropriate
• Trait-based abstractions for flexibility

📋 Adding New Packages

When creating new packages:

1. Create package directory under packages/

2. Add to workspace in root Cargo.toml:

   [workspace]
   members = [
       "packages/your-new-package",
       # ...
   ]

3. Create package README documenting purpose and usage

4. Update this file to include the new package in the list above

5. Follow conventions:

   • Use tracing for logging
   • Provide both CLI and library interfaces
   • Follow project development principles
   • Add comprehensive tests

🔗 Related Documentation

• Development Principles - Core principles guiding all packages
• Error Handling Guide - Error handling patterns
• Testing Conventions - Testing standards
• E2E Testing Guide - How packages integrate with E2E tests

💡 Future Packages

Potential future packages that could be added:

• Configuration Management: Reusable config loading and validation
• Template Engine: Tera template rendering utilities
• SSH Client: SSH operations and connectivity checking
• Infrastructure Clients: OpenTofu, Ansible, LXD client abstractions
• Test Utilities: Common test helpers and fixtures

These packages would further modularize the codebase and improve reusability across the Torrust ecosystem.