Skip to content

Commit 3306178

Browse files
josecelanojosecelano
committed
docs: extract advanced manual commands to dedicated guide
- Create comprehensive docs/user-guide/advanced-manual-commands.md for manual OpenTofu and Ansible command execution - Remove 86-line advanced commands section from main README - Replace collapsed section with concise link to new guide - Update docs/user-guide/README.md with link to advanced manual commands guide - Document complete build directory structure (tofu/, ansible/, docker-compose/, tracker/, prometheus/, grafana/) - List actual available Ansible playbooks (wait-cloud-init, update-apt-cache, install-docker, install-docker-compose, configure-firewall, configure-security-updates) - Add comprehensive sections: Overview, Create/Provision workflow, OpenTofu/Ansible manual execution, Connection methods, Destroy options, Use cases, Troubleshooting - Emphasize CLI commands as recommended approach with warnings about state management - Position manual commands as advanced debugging/development tool only This restructuring improves README readability while providing comprehensive advanced documentation for users who need manual control over infrastructure.
1 parent 54217da commit 3306178

File tree

3 files changed

+533
-161
lines changed

3 files changed

+533
-161
lines changed

‎README.md‎

Lines changed: 82 additions & 161 deletions
Original file line numberDiff line numberDiff line change
@@ -237,86 +237,7 @@ cargo run --bin e2e-complete-workflow-tests -- --help
237237
> - **[Quick Start Guide](docs/user-guide/quick-start.md)** - Complete workflow walkthrough
238238
> - **[Commands Reference](docs/user-guide/commands/)** - Detailed guide for each command _(coming soon)_
239239
> - **[Console Commands](docs/console-commands.md)** - Technical reference
240-
241-
<details>
242-
<summary>📋 <strong>Reference: Manual OpenTofu and Ansible Commands (Advanced)</strong></summary>
243-
244-
> **Note:** The CLI commands above are the recommended way to manage deployments. This section is for advanced users who want to execute OpenTofu and Ansible commands directly.
245-
246-
If you want to experiment with OpenTofu and Ansible commands directly using the generated templates:
247-
248-
#### 1️⃣ Generate Resolved Templates
249-
250-
```bash
251-
# Run E2E tests but keep the infrastructure for manual experimentation
252-
cargo run --bin e2e-complete-workflow-tests -- --keep
253-
254-
# This creates resolved templates (no variables) in build/ directories
255-
# ✅ Verified: Creates build/e2e-complete/tofu/lxd/ and build/e2e-complete/ansible/
256-
```
257-
258-
#### 2️⃣ Navigate to Generated Templates
259-
260-
```bash
261-
# Navigate to the specific environment's resolved OpenTofu templates
262-
cd build/e2e-complete/tofu/lxd/
263-
264-
# Or navigate to resolved Ansible templates
265-
cd build/e2e-complete/ansible/
266-
267-
# Other available environments:
268-
# cd build/e2e-infrastructure/tofu/lxd/
269-
# cd build/e2e-infrastructure/ansible/
270-
# cd build/e2e-deployment/ansible/
271-
```
272-
273-
#### 3️⃣ Execute Commands Manually
274-
275-
```bash
276-
# From build/e2e-complete/tofu/lxd/ - Execute OpenTofu commands
277-
tofu plan -var-file=variables.tfvars # ✅ Verified: Works with resolved templates
278-
tofu validate # Validate configuration
279-
tofu output -json # View current outputs
280-
# Note: tofu apply already executed during E2E test
281-
282-
# From build/e2e-complete/ansible/ - Execute Ansible commands
283-
ansible-playbook --list-hosts -i inventory.yml wait-cloud-init.yml # ✅ Verified: Works
284-
ansible-playbook -i inventory.yml wait-cloud-init.yml # Run playbook
285-
ansible-playbook -i inventory.yml install-docker.yml # Install Docker
286-
```
287-
288-
#### 4️⃣ Connect to the Instance
289-
290-
```bash
291-
# Connect to the running LXD instance directly
292-
lxc exec torrust-tracker-vm-e2e-complete -- /bin/bash
293-
294-
# Or via SSH (IP may vary, check tofu output)
295-
ssh -i fixtures/testing_rsa torrust@$(cd build/e2e-complete/tofu/lxd && tofu output -json | jq -r '.instance_info.value.ip_address')
296-
```
297-
298-
#### 5️⃣ Destroy Infrastructure
299-
300-
```bash
301-
# ✅ Verified: Destroy the infrastructure when done experimenting
302-
cd build/e2e-complete/tofu/lxd/
303-
tofu destroy -var-file=variables.tfvars -auto-approve
304-
305-
# ✅ Verified: This removes both the VM instance and the LXD profile
306-
# Alternative: Use LXD commands directly
307-
# lxc delete torrust-tracker-vm-e2e-complete --force
308-
# lxc profile delete torrust-profile-e2e-complete
309-
```
310-
311-
> **⚠️ Important:** Currently there's no application command to destroy infrastructure manually. You must use either:
312-
>
313-
> 1. **OpenTofu destroy** (recommended) - Uses resolved templates in `build/` directories
314-
> 2. **LXD commands** - Direct LXD resource management
315-
> 3. **Re-run E2E tests** - Automatically destroys and recreates infrastructure
316-
>
317-
> **📖 For comprehensive LXD commands and examples, see [LXD documentation](docs/tech-stack/lxd.md)**
318-
319-
</details>
240+
> - **[Advanced: Manual Commands](docs/user-guide/advanced-manual-commands.md)** - Manual OpenTofu and Ansible commands (advanced users only)
320241
321242
## 🎭 Infrastructure Workflow
322243
@@ -365,88 +286,88 @@ This project follows a structured development roadmap to evolve from the current
365286
## 📁 Repository Structure
366287
367288
```text
368-
├── .github/ # CI/CD workflows and GitHub configuration
369-
│ └── workflows/ # GitHub Actions workflow files
370-
├── build/ # 📁 Generated runtime configs (git-ignored)
371-
│ ├── e2e-complete/ # E2E complete workflow test runtime files
372-
│ ├── e2e-deployment/ # E2E deployment test runtime files
373-
│ ├── e2e-infrastructure/ # E2E infrastructure test runtime files
374-
│ └── manual-test-*/ # Manual test environment runtime files
375-
├── data/ # Environment-specific data and configurations
376-
│ ├── e2e-complete/ # E2E complete workflow test environment data
377-
│ ├── e2e-deployment/ # E2E deployment test environment data
378-
│ ├── e2e-infrastructure/ # E2E infrastructure test environment data
379-
│ ├── manual-test-*/ # Manual test environment data
380-
│ └── logs/ # Application logs
381-
├── docker/ # Docker-related configurations
382-
│ └── provisioned-instance/ # Docker setup for provisioned instances
383-
├── docs/ # 📖 Detailed documentation
384-
│ ├── tech-stack/ # Technology-specific documentation
385-
│ │ ├── opentofu.md # OpenTofu installation and usage
386-
│ │ ├── ansible.md # Ansible installation and usage
387-
│ │ └── lxd.md # LXD virtual machines
388-
│ ├── user-guide/ # User documentation
389-
│ │ ├── commands/ # Command reference documentation
390-
│ │ └── providers/ # Provider-specific guides (LXD, Hetzner)
391-
│ ├── decisions/ # Architecture Decision Records (ADRs)
392-
│ ├── contributing/ # Contributing guidelines and conventions
393-
│ │ ├── README.md # Main contributing guide
394-
│ │ ├── branching.md # Git branching conventions
395-
│ │ ├── commit-process.md # Commit process and pre-commit checks
396-
│ │ ├── error-handling.md # Error handling principles
289+
├── .github/ # CI/CD workflows and GitHub configuration
290+
│ └── workflows/ # GitHub Actions workflow files
291+
├── build/ # 📁 Generated runtime configs (git-ignored)
292+
│ ├── e2e-complete/ # E2E complete workflow test runtime files
293+
│ ├── e2e-deployment/ # E2E deployment test runtime files
294+
│ ├── e2e-infrastructure/ # E2E infrastructure test runtime files
295+
│ └── manual-test-*/ # Manual test environment runtime files
296+
├── data/ # Environment-specific data and configurations
297+
│ ├── e2e-complete/ # E2E complete workflow test environment data
298+
│ ├── e2e-deployment/ # E2E deployment test environment data
299+
│ ├── e2e-infrastructure/ # E2E infrastructure test environment data
300+
│ ├── manual-test-*/ # Manual test environment data
301+
│ └── logs/ # Application logs
302+
├── docker/ # Docker-related configurations
303+
│ └── provisioned-instance/ # Docker setup for provisioned instances
304+
├── docs/ # 📖 Detailed documentation
305+
│ ├── tech-stack/ # Technology-specific documentation
306+
│ │ ├── opentofu.md # OpenTofu installation and usage
307+
│ │ ├── ansible.md # Ansible installation and usage
308+
│ │ └── lxd.md # LXD virtual machines
309+
│ ├── user-guide/ # User documentation
310+
│ │ ├── commands/ # Command reference documentation
311+
│ │ └── providers/ # Provider-specific guides (LXD, Hetzner)
312+
│ ├── decisions/ # Architecture Decision Records (ADRs)
313+
│ ├── contributing/ # Contributing guidelines and conventions
314+
│ │ ├── README.md # Main contributing guide
315+
│ │ ├── branching.md # Git branching conventions
316+
│ │ ├── commit-process.md # Commit process and pre-commit checks
317+
│ │ ├── error-handling.md # Error handling principles
397318
│ │ ├── module-organization.md # Module organization conventions
398-
│ │ └── testing/ # Testing conventions and guides
399-
│ ├── features/ # Feature specifications and documentation
400-
│ ├── research/ # Research and analysis documents
401-
│ └── *.md # Various documentation files
402-
├── envs/ # 📁 User environment configurations (git-ignored)
403-
│ └── *.json # Environment configuration files for CLI
404-
├── fixtures/ # Test fixtures and sample data
405-
│ ├── testing_rsa* # SSH key pair for testing
406-
│ └── tofu/ # OpenTofu test fixtures
407-
├── packages/ # Rust workspace packages
408-
│ ├── dependency-installer/ # Dependency detection and installation
409-
│ └── linting/ # Linting utilities package
410-
│ └── src/ # Linting implementation source code
411-
├── scripts/ # Development and utility scripts
412-
│ └── setup/ # Installation scripts for dependencies
413-
├── src/ # 🦀 Main Rust application source code (DDD Architecture)
414-
│ ├── main.rs # Main application binary entry point
415-
│ ├── lib.rs # Library root module
416-
│ ├── container.rs # Dependency injection container
417-
│ ├── logging.rs # Logging configuration
418-
│ ├── bin/ # Binary executables
419-
│ │ ├── linter.rs # Unified linting command interface
420-
│ │ └── e2e*.rs # End-to-end testing binaries
421-
│ ├── application/ # Application layer (use cases, commands)
422-
│ ├── domain/ # Domain layer (business logic, entities)
423-
│ │ └── provider/ # Provider types (LXD, Hetzner)
424-
│ ├── infrastructure/ # Infrastructure layer (external systems)
425-
│ ├── presentation/ # Presentation layer (CLI interface)
426-
│ ├── adapters/ # External tool adapters (OpenTofu, Ansible, SSH, LXD)
427-
│ ├── shared/ # Shared utilities and common code
428-
│ ├── testing/ # Testing utilities and mocks
429-
│ ├── config/ # Configuration handling
430-
│ ├── bootstrap/ # Application bootstrapping
431-
│ └── e2e/ # End-to-end testing infrastructure
432-
├── templates/ # 📁 Template configurations (git-tracked)
433-
│ ├── tofu/ # 🏗️ OpenTofu/Terraform templates
434-
│ │ ├── lxd/ # LXD VM template configuration
435-
│ │ └── hetzner/ # Hetzner Cloud template configuration
436-
│ └── ansible/ # 🤖 Ansible playbook templates
437-
├── tests/ # Integration and system tests
438-
├── target/ # 🦀 Rust build artifacts (git-ignored)
439-
├── Cargo.toml # Rust workspace configuration
440-
├── Cargo.lock # Rust dependency lock file
441-
├── cspell.json # Spell checking configuration
442-
├── project-words.txt # Custom dictionary for spell checking
443-
├── .markdownlint.json # Markdown linting configuration
444-
├── .prettierignore # Prettier ignore rules (for Tera templates)
445-
├── .taplo.toml # TOML formatting configuration
446-
├── .yamllint-ci.yml # YAML linting configuration for CI
447-
├── README.md # This file - project overview
448-
├── LICENSE # Project license
449-
└── .gitignore # Git ignore rules
319+
│ │ └── testing/ # Testing conventions and guides
320+
│ ├── features/ # Feature specifications and documentation
321+
│ ├── research/ # Research and analysis documents
322+
│ └── *.md # Various documentation files
323+
├── envs/ # 📁 User environment configurations (git-ignored)
324+
│ └── *.json # Environment configuration files for CLI
325+
├── fixtures/ # Test fixtures and sample data
326+
│ ├── testing_rsa* # SSH key pair for testing
327+
│ └── tofu/ # OpenTofu test fixtures
328+
├── packages/ # Rust workspace packages
329+
│ ├── dependency-installer/ # Dependency detection and installation
330+
│ └── linting/ # Linting utilities package
331+
│ └── src/ # Linting implementation source code
332+
├── scripts/ # Development and utility scripts
333+
│ └── setup/ # Installation scripts for dependencies
334+
├── src/ # 🦀 Main Rust application source code (DDD Architecture)
335+
│ ├── main.rs # Main application binary entry point
336+
│ ├── lib.rs # Library root module
337+
│ ├── container.rs # Dependency injection container
338+
│ ├── logging.rs # Logging configuration
339+
│ ├── bin/ # Binary executables
340+
│ │ ├── linter.rs # Unified linting command interface
341+
│ │ └── e2e*.rs # End-to-end testing binaries
342+
│ ├── application/ # Application layer (use cases, commands)
343+
│ ├── domain/ # Domain layer (business logic, entities)
344+
│ │ └── provider/ # Provider types (LXD, Hetzner)
345+
│ ├── infrastructure/ # Infrastructure layer (external systems)
346+
│ ├── presentation/ # Presentation layer (CLI interface)
347+
│ ├── adapters/ # External tool adapters (OpenTofu, Ansible, SSH, LXD)
348+
│ ├── shared/ # Shared utilities and common code
349+
│ ├── testing/ # Testing utilities and mocks
350+
│ ├── config/ # Configuration handling
351+
│ ├── bootstrap/ # Application bootstrapping
352+
│ └── e2e/ # End-to-end testing infrastructure
353+
├── templates/ # 📁 Template configurations (git-tracked)
354+
│ ├── tofu/ # 🏗️ OpenTofu/Terraform templates
355+
│ │ ├── lxd/ # LXD VM template configuration
356+
│ │ └── hetzner/ # Hetzner Cloud template configuration
357+
│ └── ansible/ # 🤖 Ansible playbook templates
358+
├── tests/ # Integration and system tests
359+
├── target/ # 🦀 Rust build artifacts (git-ignored)
360+
├── Cargo.toml # Rust workspace configuration
361+
├── Cargo.lock # Rust dependency lock file
362+
├── cspell.json # Spell checking configuration
363+
├── project-words.txt # Custom dictionary for spell checking
364+
├── .markdownlint.json # Markdown linting configuration
365+
├── .prettierignore # Prettier ignore rules (for Tera templates)
366+
├── .taplo.toml # TOML formatting configuration
367+
├── .yamllint-ci.yml # YAML linting configuration for CI
368+
├── README.md # This file - project overview
369+
├── LICENSE # Project license
370+
└── .gitignore # Git ignore rules
450371
```
451372
452373
## 📚 Documentation

‎docs/user-guide/README.md‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -471,6 +471,7 @@ This shows real-time progress and detailed error information.
471471
- **[Command Reference](commands/README.md)** - Detailed documentation for all commands
472472
- **[Logging Guide](logging.md)** - Logging configuration and best practices
473473
- **[Template Customization](template-customization.md)** - Advanced configuration options
474+
- **[Advanced: Manual Commands](advanced-manual-commands.md)** - Manual OpenTofu and Ansible commands (advanced users)
474475

475476
### Development Documentation
476477

0 commit comments

Comments
 (0)