Welcome to the Torrust Tracker Deployer documentation! This index helps you quickly find the right documentation for your needs.
| When You Need To... | Read This Document |
|---|---|
| Understand the codebase architecture | codebase-architecture.md - DDD layers, module organization |
| Place code in the correct layer | contributing/ddd-layer-placement.md - CRITICAL decision flowchart |
| Follow development principles | development-principles.md - Observability, Testability, User Friendliness, Actionability |
| Commit code | contributing/commit-process.md - Pre-commit checks, conventional commits |
| Handle errors properly | contributing/error-handling.md - Explicit enums, actionable messages |
| Handle output properly | contributing/output-handling.md - CRITICAL UserOutput, never println! |
| Organize Rust code | contributing/module-organization.md - CRITICAL import conventions |
| Work with templates | contributing/templates/ - CRITICAL Tera syntax, registration |
| Write unit tests | contributing/testing/unit-testing.md - Naming conventions (no test_ prefix!) |
| Run E2E tests | e2e-testing/README.md - Quick start, test suites |
| Understand a past decision | decisions/README.md - 30+ ADRs indexed |
| Use the CLI | user-guide/README.md - Complete user guide |
docs/
├── contributing/ 🤝 Contribution guidelines (branching, commits, DDD, errors, templates, testing)
├── decisions/ 📋 Architectural Decision Records (30+ ADRs with context and rationale)
├── e2e-testing/ 🧪 E2E test documentation (architecture, running, manual, troubleshooting)
├── experiments/ 🧪 Active experiments exploring potential features and improvements
├── features/ ✨ Feature specifications and development tracking (5 active features)
├── user-guide/ 📖 User documentation (commands, providers, quick start)
├── tech-stack/ 🛠️ Technology docs (Ansible, LXD, OpenTofu, SSH)
├── technical/ 🔧 Technical deep dives (template system, type erasure patterns)
├── research/ 🔬 Research notes (Ansible testing, UX patterns, MVVM analysis)
├── refactors/ 🔄 Refactoring plans and tracking
├── implementation-plans/ 📝 Step-by-step plans for complex changes
├── issues/ 📋 Issue templates and specifications
├── external-issues/ ⚠️ External tool issues (GitHub Actions, Tracker)
└── analysis/ 📊 Code analysis (presentation layer structure)
- Getting Started:
user-guide/README.md,user-guide/quick-start/ - Commands:
user-guide/commands/,console-commands.md - Providers:
user-guide/providers/
- Contributing Guide:
contributing/README.md - Architecture:
codebase-architecture.md,contributing/ddd-layer-placement.md - Testing:
contributing/testing/,e2e-testing/ - Code Quality:
contributing/linting.md,development-principles.md
- Decisions:
decisions/(30+ ADRs) - Features:
features/(active and planned features) - Refactoring:
refactors/(ongoing improvements) - Roadmap:
roadmap.md
- Research:
research/(testing strategies, UX patterns, MVVM analysis) - Analysis:
analysis/(code structure analysis) - Vision:
vision-infrastructure-as-software.md
| Task | Start Here |
|---|---|
| Start using the deployer | user-guide/README.md |
| Contribute code | contributing/README.md |
| Understand architecture | codebase-architecture.md |
| Add code to correct layer | contributing/ddd-layer-placement.md |
| Run E2E tests | e2e-testing/README.md |
| Write unit tests | contributing/testing/unit-testing.md |
| Understand a decision | decisions/README.md |
| Plan a new feature | features/README.md |
| Fix external tool issues | external-issues/README.md |
| Work with templates | contributing/templates/ |
| Handle errors properly | contributing/error-handling.md |
| Handle output properly | contributing/output-handling.md |
| Organize Rust modules | contributing/module-organization.md |
📁 Root Level Documentation (Click to Expand)
| File | Description |
|---|---|
codebase-architecture.md |
Comprehensive overview of DDD architecture, layer structure (Domain, Application, Infrastructure, Presentation), and module organization |
console-commands.md |
Complete reference for CLI commands, deployment states, and implementation status of all commands (create, provision, configure, release, run, destroy, etc.) |
deployment-overview.md |
High-level overview of deployment lifecycle states, command relationships, and state transitions with visual diagrams |
development-principles.md |
Core principles: Observability, Testability, User Friendliness, Actionability - guiding all development decisions and code quality standards |
documentation.md |
Guide explaining documentation organization structure, categories, and where to place different types of documentation |
linting.md |
Linting tool usage, configuration files, and quick commands for maintaining code quality across all file types |
roadmap.md |
Development roadmap with epics, features, and implementation status tracking |
roadmap-questions.md |
Open questions and discussions about roadmap priorities and future development direction |
tofu-lxd-configuration.md |
OpenTofu configuration details for LXD provider setup and usage |
vision-infrastructure-as-software.md |
Long-term vision for evolving Infrastructure as Code to Infrastructure as Software with DDD principles |
vm-providers.md |
Overview of supported VM providers (LXD, Hetzner) and provider architecture |
🤝 Contributing Guidelines (18 documents) (Click to Expand)
Essential guides: DDD layer placement, module organization, error handling, templates, commit process, testing conventions Key Documents:
contributing/README.md- Quick reference guide to all contribution documentationcontributing/ddd-layer-placement.md- CRITICAL: Rules for placing code in correct DDD layerscontributing/module-organization.md- CRITICAL: Module organization and Rust import patternscontributing/templates/- CRITICAL: Tera template syntax and registrationcontributing/output-handling.md- CRITICAL: Output handling with UserOutput (neverprintln!)contributing/error-handling.md- Error handling principlescontributing/commit-process.md- Commit process and pre-commit checkscontributing/testing/unit-testing.md- Unit testing conventionscontributing/testing/unit-testing.md- Unit testing conventions
📋 Architectural Decision Records (30+ ADRs) (Click to Expand)
Index at decisions/README.md - All architectural decisions documented with context, rationale, and consequences
Recent Notable Decisions:
- Cloud-Init SSH Port Configuration with Reboot
- Single Docker Image for Sequential E2E Command Testing
- Register Command SSH Port Override
- Migration to AGENTS.md Standard
- ReentrantMutex Pattern for UserOutput
- Environment Variable Prefix (
TORRUST_TD_) - Command State Return Pattern
- Actionable Error Messages
- LXD VMs over Containers
- Tera Minimal Templating Strategy
🧪 E2E Testing Documentation (8 documents) (Click to Expand)
Architecture, running tests, manual testing, troubleshooting, test suites, contributing, advanced techniques
Key Documents:
e2e-testing/README.md- Overview and quick starte2e-testing/running-tests.md- How to run automated testse2e-testing/manual-testing.md- Manual testing guidee2e-testing/troubleshooting.md- Common issues and solutionse2e-testing/architecture.md- Testing architecture and design
✨ Feature Development (7+ features) (Click to Expand)
Feature specs, templates, 5 active features
Active Features:
- Hetzner Provider Support
- Import Existing Instances
- Hybrid Command Architecture
- Linter Auto-fix
- Linter Parallel Execution (deferred)
- Environment State Management (refactoring)
- Progress Reporting in Application Layer
- SDK — Programmatic Deployer Access (completed)
See features/README.md for complete list and templates.
📖 User Documentation (Click to Expand)
Complete user guide with command documentation, provider guides, quick start, logging, template customization
Key Documents:
user-guide/README.md- Complete user guideuser-guide/quick-start/- Quick start guides (Docker and native)user-guide/commands/- Individual command documentation (8 commands)user-guide/providers/- Provider-specific guides (LXD, Hetzner)
🛠️ Technology Documentation (4 documents) (Click to Expand)
Ansible, LXD, OpenTofu, SSH keys - installation, setup, and usage
🔧 Technical Deep Dives (2 documents) (Click to Expand)
contributing/templates/template-system-architecture.md- CRITICAL: Template system architecture and Project Generator patterntechnical/type-erasure-pattern.md- Type erasure pattern for Environment states
🔬 Research Notes (Click to Expand)
Ansible testing strategy, Docker vs LXD, E2E testing, UX patterns, MVVM analysis, presentation layer organization
Key Documents:
research/ansible-testing-strategy.md- Comprehensive Ansible testing strategyresearch/docker-vs-lxd-ansible-testing.md- Technology comparisonresearch/UX/- UX research documents (console output patterns, logging strategy)research/mvvm-pattern-analysis/- MVVM pattern research
🧪 Experiments (Click to Expand)
Active experiments exploring potential features and improvements
Active Experiments:
experiments/cli-json-schema/- JSON Schema generation for CLI interface (machine-readable, versionable CLI specification)
🔄 Other Documentation Categories (Click to Expand)
Refactoring Plans:
refactors/README.md- Process, templates, active/completed refactorings
Implementation Plans:
implementation-plans/README.md- Step-by-step plans for complex changes
Issue Documentation:
issues/- Templates for epics, issues, and specifications
External Tool Issues:
external-issues/README.md- Issues with external tools (GitHub Actions, Tracker)external-issues/github-actions/- GitHub Actions CI/CD issuesexternal-issues/tracker/- Torrust Tracker issues
Code Analysis:
analysis/presentation-layer/- Presentation layer structure analysis
- Total Documentation Files: 160+ markdown files
- Major Categories: 13 top-level directories
- ADRs: 30+ architectural decisions documented
- Active Features: 5 features in various stages
- Test Documentation: Comprehensive E2E testing guides
- Contribution Guides: 18 contributor-focused documents