Update user documentation for provider selection

[josecelano]

Overview

This task updates all user-facing documentation to reflect the new provider selection feature and fixes several issues in the existing documentation. Users need clear guidance on how to configure their environment for different infrastructure providers (LXD for local development, Hetzner for production deployments).

This is Task 6 in Phase 1 ("Make LXD Explicit") of the Hetzner Provider Support epic. It is the final task before Phase 2 (Add Hetzner Provider) begins.

Parent Epic: #205 - Epic: Add Hetzner Provider Support
Related: #206, #207, #208, #212

Goals

• Update all documentation files that reference provider configuration
• Fix existing issues in README.md (emoji, E2E commands, structure, Next Steps)
• Create new provider documentation in user guide
• Ensure documentation follows project conventions and is user-friendly
• Add troubleshooting guidance for common provider-related issues

Documentation Files to Update

Main Documentation Updates

File Path	Action	Description
README.md	Update	Fix emoji, E2E commands, structure, Next Steps
docs/user-guide/quick-start.md	Update	Add provider selection to quick start workflow
docs/user-guide/commands.md	Update	Document provider requirements for commands
docs/user-guide/commands/create.md	Update	Add provider config to create command docs
docs/user-guide/commands/provision.md	Update	Document provider-specific provisioning

New Provider Documentation (Create)

File Path	Action	Description
docs/user-guide/providers/README.md	Create	Provider overview and selection guide
docs/user-guide/providers/lxd.md	Create	LXD provider setup and configuration
docs/user-guide/providers/hetzner.md	Create	Hetzner provider setup and configuration

README.md Fixes Required

A) Fix E2E Test Commands

Update incorrect E2E test command references:

Current (incorrect): cargo run --bin e2e-provision-tests
Correct: cargo run --bin e2e-provision-and-destroy-tests

B) Fix Roadmap Emoji

Line 337 shows a broken emoji character: � instead of the roadmap emoji. Replace with proper emoji 🗺️ or 📋

C) Update Repository Structure

Update to reflect current directory layout, especially:

• New docs/user-guide/providers/ directory
• Any changes to template directories for multi-provider support

D) Update Next Steps Section

Update to reflect:

• Hetzner provider is now implemented (Phase 1 complete)
• What remains in the roadmap
• Current production-ready status

Configuration Examples

LXD Provider Example:

{
  "name": "my-local-env",
  "instance_name": "torrust-tracker-vm",
  "provider_config": {
    "provider": "lxd",
    "profile_name": "torrust-profile"
  },
  "ssh_credentials": {
    "private_key_path": "~/.ssh/id_rsa",
    "public_key_path": "~/.ssh/id_rsa.pub"
  },
  "ssh_port": 22
}

Hetzner Provider Example:

{
  "name": "my-production-env",
  "instance_name": "torrust-tracker-prod",
  "provider_config": {
    "provider": "hetzner",
    "api_token": "your-hetzner-api-token-here",
    "server_type": "cx22",
    "location": "nbg1"
  },
  "ssh_credentials": {
    "private_key_path": "~/.ssh/id_rsa",
    "public_key_path": "~/.ssh/id_rsa.pub"
  },
  "ssh_port": 22
}

Acceptance Criteria

README.md Fixes:

• Roadmap emoji displays correctly (not �)
• E2E test commands are correct (e2e-provision-and-destroy-tests)
• Repository structure is accurate
• Next Steps reflects current Hetzner implementation status

Provider Documentation:

• docs/user-guide/providers/README.md exists with provider overview
• docs/user-guide/providers/lxd.md exists with complete LXD documentation
• docs/user-guide/providers/hetzner.md exists with complete Hetzner documentation
• All provider docs include configuration examples
• All provider docs include troubleshooting sections

User Guide Updates:

• Quick start references provider selection
• Commands documentation mentions provider requirements
• Create command docs include provider_config examples
• Provision command docs explain provider-specific behavior

Quality Checks:

• Pre-commit checks pass: ./scripts/pre-commit.sh
• All markdown files pass linting
• Documentation is clear and understandable for new users
• Code examples can be copy-pasted and work

Implementation Details

Full specification available at: docs/issues/update-user-documentation-for-provider-selection.md

---

Created: December 3, 2025
Epic: Phase 1 - Make LXD Explicit (Task 6 of 6)