fix: [#326] require --output-dir flag to prevent artifact conflicts

AGENTS.md

@@ -215,12 +215,13 @@ The project provides Agent Skills in `.github/skills/` for specialized workflows
 
 Available skills:
 
-| Task                | Skill to Load                             |
-| ------------------- | ----------------------------------------- |
-| Adding commands     | `.github/skills/add-new-command/skill.md` |
-| Creating issues     | `.github/skills/create-issue/skill.md`    |
-| Creating new skills | `.github/skills/add-new-skill/skill.md`   |
-| Running linters     | `.github/skills/run-linters/skill.md`     |
+| Task                        | Skill to Load                                      |
+| --------------------------- | -------------------------------------------------- |
+| Adding commands             | `.github/skills/add-new-command/skill.md`          |
+| Creating issues             | `.github/skills/create-issue/skill.md`             |
+| Creating new skills         | `.github/skills/add-new-skill/skill.md`            |
+| Rendering tracker artifacts | `.github/skills/render-tracker-artifacts/skill.md` |
+| Running linters             | `.github/skills/run-linters/skill.md`              |
 
 Skills supplement (not replace) the rules in this file. Rules apply always; skills activate when their workflows are needed.
 

docs/console-commands.md

@@ -9,6 +9,7 @@
 - **Create Template**: Generate environment configuration template (JSON)
 - **Create Environment**: Create new deployment environment from configuration file
 - **Show**: Display environment information with state-aware details
+- **Render**: Generate deployment artifacts without provisioning infrastructure
 - **Provision**: VM infrastructure provisioning with OpenTofu (LXD and Hetzner Cloud)
 - **Register**: Register existing instances as an alternative to provisioning (for pre-existing VMs, servers, or containers)
 - **Configure**: VM configuration with Docker, Docker Compose, and firewall via Ansible
@@ -128,6 +129,7 @@ torrust-tracker-deployer create environment -f <file>   # ✅ Create environment
 torrust-tracker-deployer show <env>      # ✅ Display environment information
 
 # Plumbing Commands (Low-Level)
+torrust-tracker-deployer render --env-name <env> --instance-ip <IP> --output-dir <PATH> # ✅ Generate deployment artifacts
 torrust-tracker-deployer provision <env> # ✅ Create VM infrastructure
 torrust-tracker-deployer register <env> --instance-ip <IP>  # ✅ Register existing infrastructure
 torrust-tracker-deployer configure <env> # ✅ Setup VM (Docker, Docker Compose, firewall)
@@ -453,6 +455,129 @@ torrust-tracker-deployer register my-environment --instance-ip 192.168.1.100
 
 ---
 
+### `render` - Generate Deployment Artifacts
+
+**Status**: ✅ Implemented  
+**State Transition**: None (read-only operation)  
+**Purpose**: Generate all deployment artifacts without provisioning infrastructure.
+
+```bash
+# From existing environment
+torrust-tracker-deployer render --env-name <environment> --instance-ip <IP_ADDRESS> --output-dir <OUTPUT_PATH>
+
+# From configuration file
+torrust-tracker-deployer render --env-file <config_file> --instance-ip <IP_ADDRESS> --output-dir <OUTPUT_PATH>
+
+# Overwrite existing output directory
+torrust-tracker-deployer render --env-name <environment> --instance-ip <IP_ADDRESS> --output-dir <OUTPUT_PATH> --force
+```
+
+**Current Implementation**:
+
+- Validates input parameters (environment exists or config file valid)
+- Parses environment configuration
+- Validates IP address format (IPv4/IPv6)
+- Renders all 8 service templates:
+  - OpenTofu infrastructure code
+  - Ansible playbooks and inventory
+  - Docker Compose service definitions
+  - Tracker configuration (tracker.toml)
+  - Prometheus monitoring configuration
+  - Grafana dashboard provisioning
+  - Caddy reverse proxy configuration (if HTTPS enabled)
+  - Backup scripts (if backup enabled)
+- Writes artifacts to user-specified output directory
+- Does NOT change environment state
+
+**Use Cases**:
+
+- **Preview artifacts** - Inspect what will be deployed before provisioning
+- **Manual deployment** - Generate artifacts for use with external tools
+- **Configuration validation** - Verify template rendering with actual values
+- **Artifact comparison** - Compare configurations between different setups
+
+**Input Modes**:
+
+1. **`--env-name` mode** - Uses existing environment in `Created` state
+2. **`--env-file` mode** - Generates artifacts directly from config file (no environment required)
+
+**Arguments**:
+
+- `--env-name <NAME>` - Name of existing environment (mutually exclusive with `--env-file`)
+- `--env-file <PATH>` - Path to configuration file (mutually exclusive with `--env-name`)
+- `--instance-ip <IP>` - Target instance IP address (required)
+- `--output-dir <PATH>` - Output directory for generated artifacts (required)
+- `--force` - Overwrite existing output directory (optional)
+
+**Why IP is Required**:
+
+- In `Created` state, infrastructure doesn't exist yet (no real IP)
+- With `--env-file`, no infrastructure is ever created
+- IP is needed for Ansible inventory generation
+
+**Why Output Directory is Required**:
+
+- **Prevents conflicts** with provision artifacts in `build/{env}/`
+- **Enables preview** without overwriting deployment artifacts
+- **Allows multiple renders** with different IPs or configurations
+- **Clear separation** between preview (render) and deployment (provision)
+
+**Examples**:
+
+```bash
+# Preview artifacts before provisioning
+torrust-tracker-deployer create environment -f envs/prod.json
+torrust-tracker-deployer render --env-name prod --instance-ip 203.0.113.50 --output-dir ./preview-prod
+ls -la preview-prod/  # Inspect generated artifacts
+torrust-tracker-deployer provision prod  # Proceed if satisfied (writes to build/prod/)
+
+# Generate artifacts directly from config (no environment)
+torrust-tracker-deployer render \
+  --env-file envs/staging.json \
+  --instance-ip 192.168.1.100 \
+  --output-dir /tmp/staging-artifacts
+
+# Manual deployment workflow
+torrust-tracker-deployer render --env-file envs/prod.json --instance-ip 203.0.113.50 --output-dir /tmp/manual-deploy
+cd /tmp/manual-deploy/tofu && tofu apply
+cd ../ansible && ansible-playbook -i inventory.yml deploy.yml
+```
+
+**Output Directory Structure**:
+
+```text
+<output-dir>/
+├── tofu/           # Infrastructure code (OpenTofu)
+├── ansible/        # Configuration management (playbooks + inventory with IP)
+├── docker-compose/ # Service orchestration
+├── tracker/        # Tracker configuration
+├── prometheus/     # Metrics collection
+├── grafana/        # Visualization dashboards
+├── caddy/          # Reverse proxy (if HTTPS)
+└── backup/         # Backup scripts (if enabled)
+```
+
+**Comparison with Provision**:
+
+| Aspect          | render                   | provision                  |
+| --------------- | ------------------------ | -------------------------- |
+| Infrastructure  | None created             | Creates VMs/servers        |
+| State Change    | No change                | Created → Provisioned      |
+| IP Address      | User-provided            | From actual infrastructure |
+| Output Location | User-specified directory | build/{env}/ directory     |
+| Time            | Seconds                  | Minutes                    |
+| Cost            | Free                     | Provider charges           |
+
+**Key Feature**: Render generates **identical** artifacts to provision (except IP addresses in Ansible inventory).
+
+**Environment Variables**:
+
+- `RUST_LOG=debug` - Detailed rendering logs via tracing
+
+**See Also**: [Render Command Guide](user-guide/commands/render.md), [Manual E2E Testing: Render Verification](e2e-testing/manual/render-verification.md)
+
+---
+
 ### `configure` - System Configuration
 
 **Status**: ✅ Implemented  

docs/e2e-testing/manual/README.md

@@ -475,6 +475,17 @@ ls data/manual-test 2>/dev/null || echo "Cleaned up successfully"
 
 After deploying your environment, you may want to verify that specific services are working correctly. The following guides provide detailed verification steps for each supported service:
 
+### Render Command
+
+The render command generates deployment artifacts without provisioning infrastructure. See the [Render Verification Guide](render-verification.md) for detailed steps to:
+
+- Generate artifacts using `--env-name` mode (from existing environment)
+- Generate artifacts using `--env-file` mode (directly from config)
+- Compare rendered artifacts with provision command output
+- Verify artifact completeness (all 8 services)
+- Test idempotency and error handling
+- Understand artifact equivalence testing
+
 ### Torrust Tracker
 
 The tracker is the core service deployed by this tool. See the [Tracker Verification Guide](tracker-verification.md) for detailed steps to: