Module environment 

Environment Domain Module

This module contains all environment-related domain entities and types.

Architecture: Context + State Design

The Environment entity uses a two-part design to separate immutable identity from mutable lifecycle state:

EnvironmentContext - Three Semantic Categories

The context is organized into three distinct semantic types, each with a clear purpose:

1. User Inputs (UserInputs)

• Purpose: Configuration provided when creating an environment
• Characteristics: Immutable throughout environment lifecycle
• Fields: name, instance_name, profile_name, ssh_credentials, ssh_port
• When to add: User needs to configure something at creation time

2. Internal Config (InternalConfig)

• Purpose: Derived configuration for internal use
• Characteristics: Calculated from user inputs
• Fields: build_dir, data_dir
• When to add: Need internal paths or derived configuration

3. Runtime Outputs (RuntimeOutputs)

• Purpose: Data generated during deployment operations
• Characteristics: Mutable as operations progress
• Fields: instance_ip (more fields expected as deployment evolves)
• When to add: Operations produce new data about deployed infrastructure

state: S - Mutable Lifecycle State

Tracks the current phase in the deployment lifecycle using the type-state pattern:

• Success states: Created, Provisioning, Provisioned, Configuring, etc.
• Error states: ProvisionFailed, ConfigureFailed, etc.

Benefits of This Design

• Compile-time safety: Invalid state transitions caught at compile time
• Reduced pattern matching: Access common fields without matching on state (83% reduction)
• Clear separation: Identity vs. lifecycle are distinct concerns
• Semantic clarity: Types document the purpose of each field
• Developer guidance: Clear where to add new fields based on their purpose
• Easy extension: Adding fields or states is straightforward

Submodules

• context - Environment context composing the three semantic types
• user_inputs - User-provided configuration
• internal_config - Derived paths and internal settings
• runtime_outputs - Data generated during deployment
• name - Environment name validation and management
• state - State marker types and type erasure for environment state machine

Main Entity

The Environment entity encapsulates all environment-specific configuration for deployments. Each environment represents an isolated deployment context with its own directories, SSH keys, and instance naming.

Purpose

The Environment entity provides:

• Environment-specific directory structure (data/{env_name}/, build/{env_name}/)
• Instance naming with conflict avoidance (torrust-tracker-vm-{env_name})
• SSH key pair management per environment
• JSON serialization for future state persistence

Usage Example

use torrust_tracker_deployer_lib::domain::environment::{Environment, name::EnvironmentName};
use torrust_tracker_deployer_lib::domain::provider::{LxdConfig, ProviderConfig};
use torrust_tracker_deployer_lib::domain::ProfileName;
use torrust_tracker_deployer_lib::shared::Username;
use torrust_tracker_deployer_lib::adapters::ssh::SshCredentials;
use std::path::PathBuf;
use chrono::{TimeZone, Utc};

let env_name = EnvironmentName::new("e2e-config".to_string())?;
let ssh_username = Username::new("torrust".to_string())?;
let ssh_credentials = SshCredentials::new(
    PathBuf::from("fixtures/testing_rsa"),
    PathBuf::from("fixtures/testing_rsa.pub"),
    ssh_username,
);
let provider_config = ProviderConfig::Lxd(LxdConfig {
    profile_name: ProfileName::new(format!("lxd-{}", env_name.as_str())).unwrap(),
});
let created_at = Utc.with_ymd_and_hms(2025, 1, 1, 0, 0, 0).unwrap();
let environment = Environment::new(env_name, provider_config, ssh_credentials, 22, created_at);

// Environment automatically generates paths
assert_eq!(*environment.data_dir(), PathBuf::from("./data/e2e-config"));
assert_eq!(*environment.build_dir(), PathBuf::from("./build/e2e-config"));
assert_eq!(environment.templates_dir(), PathBuf::from("./data/e2e-config/templates"));

Re-exports

pub use context::EnvironmentContext;

pub use internal_config::InternalConfig;

pub use params::EnvironmentParams;

pub use runtime_outputs::ProvisionMethod;

pub use runtime_outputs::RuntimeOutputs;

pub use state::AnyEnvironmentState;

pub use state::ConfigureFailed;

pub use state::Configured;

pub use state::Configuring;

pub use state::Created;

pub use state::DestroyFailed;

pub use state::Destroyed;

pub use state::Destroying;

pub use state::ProvisionFailed;

pub use state::Provisioned;

pub use state::Provisioning;

pub use state::ReleaseFailed;

pub use state::Released;

pub use state::Releasing;

pub use state::RunFailed;

pub use state::Running;

pub use user_inputs::UserInputs;

pub use user_inputs::UserInputsError;

pub use crate::domain::tracker::DatabaseConfig;

pub use crate::domain::tracker::HealthCheckApiConfig;

pub use crate::domain::tracker::HttpApiConfig;

pub use crate::domain::tracker::HttpTrackerConfig;

pub use crate::domain::tracker::MysqlConfig;

pub use crate::domain::tracker::SqliteConfig;

pub use crate::domain::tracker::TrackerConfig;

pub use crate::domain::tracker::TrackerCoreConfig;

pub use crate::domain::tracker::UdpTrackerConfig;

pub use crate::domain::prometheus::PrometheusConfig;

pub use crate::domain::grafana::GrafanaConfig;

pub use crate::domain::backup::BackupConfig;

Modules

context

Environment Context Module

internal_config

Internal Config Module

name

params

Environment Creation Parameters

repository

Repository module for environment persistence

runtime_outputs

Runtime Outputs Module

state

Environment State Marker Types

user_inputs

User Inputs Module

Structs

Environment

Environment configuration encapsulating all environment-specific settings

EnvironmentName

Validated environment name following restricted format rules

TraceId

Unique identifier for error traces

Enums

EnvironmentNameError

Errors that can occur when creating or validating environment names

Constants

ANSIBLE_DIR_NAME

Directory name for Ansible-related files

LXD_PROVIDER_NAME

Provider name for LXD infrastructure

TEMPLATES_DIR_NAME

Directory name for template files within an environment’s data directory

TOFU_DIR_NAME

Directory name for OpenTofu-related files

TRACES_DIR_NAME

Directory name for trace files within an environment’s data directory