torrust_tracker_deployer_lib/bootstrap/
help.rs

1//! Help and Usage Information Module
2//!
3//! This module provides help and usage information for the Torrust Tracker Deployer
4//! application. It contains functions to display helpful information to users
5//! when they need guidance on how to use the application.
6//!
7//! ## Design Principles
8//!
9//! - **Independent**: No dependencies on presentation layer or CLI structures
10//! - **User-Focused**: Clear, actionable guidance for users
11//! - **Comprehensive**: Covers getting started, examples, and next steps
12
13/// Display helpful information to the user when no command is provided
14///
15/// This function shows getting started information, usage examples, and
16/// helpful links when the user runs the application without any subcommands.
17/// It provides a friendly introduction to the application and guides users
18/// toward productive next steps.
19///
20/// # Output
21///
22/// Prints directly to stdout with formatted, user-friendly content including:
23/// - Application overview and purpose
24/// - Getting started instructions
25/// - Testing guidance
26/// - Documentation references
27/// - Next steps for users
28///
29/// # Example
30///
31/// ```rust
32/// use torrust_tracker_deployer_lib::bootstrap::help;
33///
34/// // Display help when user runs app without arguments
35/// help::display_getting_started();
36/// ```
37pub fn display_getting_started() {
38    println!("🏗️  Torrust Tracker Deployer");
39    println!("===========================");
40    println!();
41    println!("Automated deployment tool for the Torrust Tracker application.");
42    println!("Manage complete deployment lifecycles from environment creation to verification.");
43    println!();
44    println!("📋 Quick Start:");
45    println!("   1. Check dependencies:");
46    println!(
47        "      cargo run --package torrust-tracker-deployer-dependency-installer --bin dependency-installer check"
48    );
49    println!();
50    println!("   2. Create and deploy an environment:");
51    println!("      torrust-tracker-deployer create template my-env.json");
52    println!("      # Edit my-env.json with your SSH keys and settings");
53    println!("      torrust-tracker-deployer create environment --env-file my-env.json");
54    println!("      torrust-tracker-deployer provision my-environment");
55    println!("      torrust-tracker-deployer configure my-environment");
56    println!("      torrust-tracker-deployer release my-environment");
57    println!("      torrust-tracker-deployer run my-environment");
58    println!();
59    println!("   3. Verify deployment (optional):");
60    println!("      torrust-tracker-deployer test my-environment");
61    println!();
62    println!("   4. Clean up when done:");
63    println!("      torrust-tracker-deployer destroy my-environment");
64    println!();
65    println!("📖 Documentation:");
66    println!("   - Quick Start Guides: docs/user-guide/quick-start/");
67    println!("   - Command Reference: docs/user-guide/commands/README.md");
68    println!("   - Main README: README.md");
69    println!();
70    println!("💡 To see all available commands: torrust-tracker-deployer --help");
71}
72
73/// Display troubleshooting information for common issues
74///
75/// This function provides guidance for common problems users might encounter
76/// when setting up or using the Torrust Tracker Deployer.
77///
78/// # Output
79///
80/// Prints troubleshooting guidance to stdout including:
81/// - Common setup issues and solutions
82/// - Dependency verification steps
83/// - Configuration validation tips
84/// - Where to get additional help
85///
86/// # Example
87///
88/// ```rust
89/// use torrust_tracker_deployer_lib::bootstrap::help;
90///
91/// // Display troubleshooting info when user encounters issues
92/// help::display_troubleshooting();
93/// ```
94pub fn display_troubleshooting() {
95    println!("🔧 Troubleshooting Guide");
96    println!("=======================");
97    println!();
98    println!("Common issues and solutions:");
99    println!();
100    println!("1. Dependencies not found:");
101    println!("   - Ensure OpenTofu is installed and in PATH");
102    println!("   - Verify Ansible is installed and accessible");
103    println!("   - Check that your infrastructure provider is properly configured");
104    println!();
105    println!("2. Permission errors:");
106    println!("   - Ensure you have the necessary permissions for your provider");
107    println!("   - For LXD: Add your user to the lxd group");
108    println!("   - For Hetzner: Verify your API token has correct permissions");
109    println!();
110    println!("3. Network connectivity issues:");
111    println!("   - Check internet connectivity for image downloads");
112    println!("   - Verify your provider is accessible");
113    println!("   - Test provider-specific connectivity");
114    println!();
115    println!("4. Configuration problems:");
116    println!("   - Validate YAML/JSON syntax in configuration files");
117    println!("   - Check that environment names follow naming conventions");
118    println!("   - Ensure SSH keys are properly configured");
119    println!();
120    println!("📖 For more help:");
121    println!("   - Check the docs/ directory for detailed guides");
122    println!("   - Review the README.md for setup instructions");
123    println!("   - Open an issue on GitHub for additional support");
124}
125
126#[cfg(test)]
127mod tests {
128    use super::*;
129
130    #[test]
131    fn it_should_display_getting_started_without_panicking() {
132        // Test that the function runs without panicking
133        // We can't easily test stdout content in unit tests,
134        // but we can ensure the function doesn't crash
135        display_getting_started();
136    }
137
138    #[test]
139    fn it_should_display_troubleshooting_without_panicking() {
140        // Test that the function runs without panicking
141        display_troubleshooting();
142    }
143}
torrust_tracker_deployer_lib/bootstrap/help.rs

torrust_tracker_deployer_lib/bootstrap/
help.rs
