Setup logging for production CLI

[josecelano]

Task 1.1 - Setup logging for the main CLI application

Parent Issue: #2 (Scaffolding for main app)

Roadmap: Section 1.1

---

📋 Overview

Implement production-ready logging configuration for the main torrust-tracker-deployer CLI binary. Currently, logging infrastructure exists and is used in E2E test binaries, but the main application entry point lacks logging initialization.

---

🎯 Goals

1. Initialize logging in main CLI when the application starts
2. Add CLI arguments for logging configuration (--log-format, --log-output, --log-dir)
3. Use production-ready defaults (file-only logging, compact format)
4. Create user and contributor documentation

---

📐 Implementation Plan

Phase 1: Basic CLI Structure (1-2 hours)

• Task 1.1: Add clap dependency to Cargo.toml
• Task 1.2: Create new src/app.rs module with Cli struct and run() function
• Task 1.3: Update src/main.rs to call app::run()
• Task 1.4: Initialize logging using LoggingBuilder
• Task 1.5: Add startup logging event
• Task 1.6: Add shutdown logging event
• Task 1.7: Keep existing user-facing output

Phase 2: Argument Validation (1 hour)

• Task 2.1: Add comprehensive help text for logging arguments
• Task 2.2: Document panic behavior if logging fails
• Task 2.3: Test edge cases (invalid paths, permissions, etc.)

Phase 3: Documentation (1-1.5 hours)

• Task 3.1: Update README.md with logging section
• Task 3.2: Create docs/user-guide/logging.md for end users
• Task 3.3: Create/update docs/contributing/logging-guide.md for contributors
• Task 3.4: Verify all links work correctly

Phase 4: Integration Testing (30-45 minutes)

• Task 4.1: Test default configuration
• Task 4.2: Test format options (pretty, json, compact)
• Task 4.3: Test output modes (file-only, file-and-stderr)
• Task 4.4: Test custom log directory
• Task 4.5: Test RUST_LOG environment variable
• Task 4.6: Test log file persistence

---

📄 Detailed Specification

Complete specification available at: docs/issues/3-setup-logging-for-production-cli.md

The specification includes:

• Detailed CLI argument structure
• Code examples for src/app.rs and src/main.rs
• Default behavior specifications
• Testing strategy
• Acceptance criteria

---

⏱️ Estimated Effort

Total: 4-5 hours

• Phase 1: 1-2 hours (7 subtasks)
• Phase 2: 1 hour (3 subtasks)
• Phase 3: 1-1.5 hours (4 subtasks)
• Phase 4: 0.5-0.75 hours (6 subtasks)
• Buffer: 0.5 hours

---

✅ Acceptance Criteria

• New src/app.rs module created with run() function
• src/main.rs is minimal (only calls app::run())
• CLI accepts --log-format, --log-output, --log-dir arguments
• Logging initializes before any application logic
• Log files created in specified directory
• Application logs startup and shutdown events
• README.md includes logging section
• User guide created at docs/user-guide/logging.md
• Contributor guide created/updated at docs/contributing/logging-guide.md
• All linters pass (cargo run --bin linter all)
• Pre-commit checks pass (./scripts/pre-commit.sh)

---

🔗 Related

• Epic: Scaffolding for main app - 8/9 tasks complete (89%) #2 (Scaffolding for main app)
• Roadmap: Section 1.1
• Specification: docs/issues/3-setup-logging-for-production-cli.md
• Development Principles
• User Output vs Logging Separation