feat: add local KVM/libvirt testing infrastructure with automated fixes

- Add complete local VM testing setup using OpenTofu and KVM/libvirt
- Create infrastructure automation with Makefile targets for setup and testing
- Add comprehensive libvirt troubleshooting and permission fixes
- Implement automated AppArmor override for libvirt-qemu storage access
- Add cloud-init configuration for Ubuntu 22.04 VMs with Docker setup
- Create test suite for infrastructure validation and Torrust Tracker integration
- Add detailed documentation with quick-start and troubleshooting guides
- Configure markdownlint for consistent documentation formatting
- Fix all markdown linting issues in core infrastructure documentation

Infrastructure includes:

- OpenTofu configuration for local VM deployment
- Cloud-init setup with torrust user, Docker, and security hardening
- Automated scripts for libvirt permission and storage pool fixes
- Comprehensive test coverage for prerequisites, deployment, and integration
- GitHub Actions workflow for CI/CD validation

This enables reliable local testing before cloud deployment and provides
automated solutions for common libvirt permission issues on Ubuntu/Debian.

Author: josecelano

.github/copilot-instructions.md

@@ -3,18 +3,22 @@ This repository contains all the configuration needed to run the live Torrust Tr
 The main goal is to provide a simple and easy-to-use setup for the Torrust Tracker, which can be deployed on a single server.
 
 The current major initiative is to migrate the tracker to a new infrastructure on Hetzner. This involves:
+
 - Running the tracker binary directly on the host for performance.
 - Using Docker for supporting services like Nginx, Prometheus, Grafana and MySQL.
 - Migrating the database from SQLite to MySQL.
 
 When providing assistance, please act as an experienced open-source developer and system administrator.
 
 Follow these conventions:
+
 - Use Conventional Commits for commit messages. Include the issue number in this format `#1` in the commit message if applicable, e.g., `feat: [#1] add new feature`.
-    - The issue number should be the branch prefix, e.g., `feat: [#1] add new feature` for branch `1-add-new-feature`.
+  - The issue number should be the branch prefix, e.g., `feat: [#1] add new feature` for branch `1-add-new-feature`.
 - We use the proposed GitHub branch naming convention:
-    - Starts with a number indicating the issue number.
-    - Followed by a hyphen and a short description of the feature or fix.
-    - Uses hyphens to separate words, e.g., `1-add-new-feature`.
+  - Starts with a number indicating the issue number.
+  - Followed by a hyphen and a short description of the feature or fix.
+  - Uses hyphens to separate words, e.g., `1-add-new-feature`.
 - Ensure that shell scripts are POSIX-compliant.
 - Provide clear and concise documentation for any new features or changes.
+- Follow https://github.com/DavidAnson/markdownlint conventions for Markdown files.
+- Use https://github.com/koalaman/shellcheck for shell scripts to ensure they are free of common errors.

.github/workflows/infrastructure.yml

@@ -0,0 +1,75 @@
+name: Infrastructure Tests
+
+on:
+  push:
+    branches: [main, develop]
+    paths:
+      - "infrastructure/**"
+      - "tests/infrastructure/**"
+      - "Makefile"
+      - ".github/workflows/infrastructure.yml"
+  pull_request:
+    branches: [main, develop]
+    paths:
+      - "infrastructure/**"
+      - "tests/infrastructure/**"
+      - "Makefile"
+      - ".github/workflows/infrastructure.yml"
+
+jobs:
+  validate-infrastructure:
+    runs-on: ubuntu-22.04
+
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v4
+
+      - name: Install OpenTofu
+        run: |
+          curl -fsSL https://get.opentofu.org/install-opentofu.sh -o install-opentofu.sh
+          chmod +x install-opentofu.sh
+          sudo ./install-opentofu.sh --install-method deb
+          rm install-opentofu.sh
+          tofu version
+
+      - name: Install yamllint
+        run: |
+          sudo apt-get update
+          sudo apt-get install -y yamllint
+
+      - name: Test script permissions
+        run: |
+          test -x tests/infrastructure/test-local-setup.sh
+          test -x tests/infrastructure/test-integration.sh
+
+      - name: Run syntax tests
+        env:
+          CI: true
+        run: |
+          make ci-test-syntax
+
+      - name: Validate Makefile targets
+        run: |
+          make help
+          make workflow-help
+
+  # Note: Full VM testing is not run in CI as it requires KVM/nested virtualization
+  # which is not available in GitHub Actions runners
+  documentation-check:
+    runs-on: ubuntu-22.04
+
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v4
+
+      - name: Check documentation links
+        run: |
+          # Verify documentation files exist
+          test -f docs/infrastructure/quick-start.md
+          test -f docs/infrastructure/local-testing-setup.md
+          test -f infrastructure/README.md
+
+          # Check for common documentation issues
+          grep -q "Quick Start" docs/infrastructure/quick-start.md
+          grep -q "OpenTofu" docs/infrastructure/local-testing-setup.md
+          grep -q "make" README.md

.markdownlint.json

@@ -0,0 +1,19 @@
+{
+    "default": true,
+    "MD013": {
+        "line_length": 80
+    },
+    "MD031": true,
+    "MD032": true,
+    "MD040": true,
+    "MD022": true,
+    "MD009": true,
+    "MD007": {
+        "indent": 2
+    },
+    "MD026": false,
+    "MD041": false,
+    "MD034": false,
+    "MD024": false,
+    "MD033": false
+}

.yamllint-ci.yml

@@ -0,0 +1,10 @@
+extends: default
+
+rules:
+  line-length: disable
+  comments: disable
+  document-start: disable
+  truthy: disable
+  trailing-spaces: disable
+  new-line-at-end-of-file: disable
+  indentation: disable