feat: [#10] implement comprehensive linting infrastructure

- Add comprehensive linting script (scripts/lint.sh) with yamllint, shellcheck, and markdownlint
- Simplify GitHub Actions workflow to focus only on linting checks
- Add Makefile targets for linting (lint, lint-yaml, lint-shell, lint-markdown)
- Fix all ShellCheck issues in shell scripts:
  - Quote variables properly in monitor-cloud-init.sh
  - Fix sed command in test-local-setup.sh
  - Use array handling for yamllint config
- Fix markdown line length issues in documentation files
- Update yamllint config to support GitHub Actions syntax
- Add linting documentation to main README
- Remove empty test file and cleanup directory structure

All linting checks now pass successfully, providing a solid foundation
for maintaining code quality across the entire project.

Author: josecelano

.github/workflows/infrastructure.yml

@@ -5,72 +5,41 @@ on:
     branches: [main, develop]
     paths:
       - "infrastructure/**"
-      - "infrastructure/tests/**"
+      - "application/**"
+      - "scripts/**"
       - "Makefile"
       - ".github/workflows/infrastructure.yml"
+      - "**/*.md"
+      - "**/*.yml"
+      - "**/*.yaml"
+      - "**/*.sh"
   pull_request:
     branches: [main, develop]
     paths:
       - "infrastructure/**"
-      - "infrastructure/tests/**"
+      - "application/**"
+      - "scripts/**"
       - "Makefile"
       - ".github/workflows/infrastructure.yml"
+      - "**/*.md"
+      - "**/*.yml"
+      - "**/*.yaml"
+      - "**/*.sh"
 
 jobs:
-  validate-infrastructure:
+  lint:
     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
+      - name: Install linting tools
         run: |
           sudo apt-get update
-          sudo apt-get install -y yamllint
-
-      - name: Test script permissions
-        run: |
-          test -x infrastructure/tests/test-local-setup.sh
-          test -x infrastructure/tests/test-integration.sh
+          sudo apt-get install -y yamllint shellcheck
+          sudo npm install -g markdownlint-cli
 
-      - name: Run syntax tests
-        env:
-          CI: true
+      - name: Run linting script
         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 infrastructure/docs/quick-start.md
-          test -f infrastructure/docs/local-testing-setup.md
-          test -f infrastructure/README.md
-          test -f application/README.md
-
-          # Check for common documentation issues
-          grep -q "Quick Start" infrastructure/docs/quick-start.md
-          grep -q "OpenTofu" infrastructure/docs/local-testing-setup.md
-          grep -q "make" README.md
+          ./scripts/lint.sh

.yamllint-ci.yml

@@ -7,4 +7,4 @@ rules:
     min-spaces-from-content: 1 # Allow single space before comments
   document-start: disable # Cloud-init files don't need --- start
   truthy:
-    allowed-values: ["true", "false", "yes", "no"] # Allow cloud-init common values
+    allowed-values: ["true", "false", "yes", "no", "on", "off"] # Allow cloud-init and GitHub Actions common values

Makefile

@@ -1,5 +1,5 @@
 # Makefile for Torrust Tracker Local Testing Infrastructure
-.PHONY: help init plan apply destroy test clean status ssh install-deps console vm-console
+.PHONY: help init plan apply destroy test clean status ssh install-deps console vm-console lint lint-yaml lint-shell lint-markdown
 
 # Default variables
 VM_NAME ?= torrust-tracker-demo
@@ -140,6 +140,22 @@ test-syntax: ## Test configuration syntax only
 	@echo "Testing configuration syntax..."
 	$(TESTS_DIR)/test-local-setup.sh syntax
 
+lint: ## Run all linting checks (yamllint, shellcheck, markdownlint)
+	@echo "Running linting checks..."
+	./scripts/lint.sh
+
+lint-yaml: ## Run only yamllint
+	@echo "Running yamllint..."
+	./scripts/lint.sh --yaml
+
+lint-shell: ## Run only shellcheck
+	@echo "Running shellcheck..."
+	./scripts/lint.sh --shell
+
+lint-markdown: ## Run only markdownlint
+	@echo "Running markdownlint..."
+	./scripts/lint.sh --markdown
+
 test-integration: ## Run integration tests (requires deployed VM)
 	@echo "Running integration tests..."
 	$(TESTS_DIR)/test-integration.sh full-test

README.md

@@ -118,6 +118,39 @@ For contributors and developers:
 - **General contributing guidelines**: See [`.github/copilot-instructions.md`](.github/copilot-instructions.md)
 - **Architecture decisions**: See [`docs/adr/`](docs/adr/) for design rationale
 
+### Code Quality and Linting
+
+The project uses automated linting to ensure code quality and consistency:
+
+```bash
+# Run all linting checks
+make lint
+
+# Run individual linters
+make lint-yaml        # YAML files (yamllint)
+make lint-shell       # Shell scripts (shellcheck)
+make lint-markdown    # Markdown files (markdownlint)
+```
+
+**Required tools:**
+
+- `yamllint` - YAML syntax and style checking
+- `shellcheck` - Shell script analysis
+- `markdownlint` - Markdown style and structure checking
+
+**Installation:**
+
+```bash
+# Ubuntu/Debian
+sudo apt-get install yamllint shellcheck
+sudo npm install -g markdownlint-cli
+
+# Or install all project dependencies
+make install-deps
+```
+
+Linting is automatically run in CI/CD pipelines to validate all contributions.
+
 > **Note**: The main `Makefile` is kept at the root level to serve as the
 > project's primary interface. See [ADR-001](docs/adr/001-makefile-location.md)
 > for the full rationale.

application/docs/backups.md

@@ -4,7 +4,7 @@
 
 ```bash
 cd /home/torrust/github/torrust/torrust-tracker-demo/
-./share/bin/tracker-db-backup.sh 
+./share/bin/tracker-db-backup.sh
 ```
 
 ## Check Backups Crontab Configuration
@@ -13,7 +13,9 @@ cd /home/torrust/github/torrust/torrust-tracker-demo/
 sudo crontab -e
 ```
 
-You should see the [crontab.conf](../share/container/default/config/crontab.conf) configuration file.
+You should see the
+[crontab.conf](../share/container/default/config/crontab.conf) configuration
+file.
 
 ## Check Backups
 

application/docs/deployment.md

@@ -4,39 +4,43 @@
 2. Execute the deployment script: `./bin/deploy-torrust-tracker-demo.com.sh`.
 3. Execute the smoke tests:
 
-    ```console
-    # Clone Torrust Tracker
-    [email protected]:torrust/torrust-tracker.git
-    cd torrust-tracker
-    ```
+   ```console
+   # Clone Torrust Tracker
+   [email protected]:torrust/torrust-tracker.git
+   cd torrust-tracker
+   ```
 
-    Execute the following commands to run the tracker client and checker.
+   Execute the following commands to run the tracker client and checker.
 
-    Simulate a torrent announce to the tracker using UDP:
+   Simulate a torrent announce to the tracker using UDP:
 
-    ```console
-    cargo run -p torrust-tracker-client --bin udp_tracker_client announce udp://tracker.torrust-demo.com:6969/announce 9c38422213e30bff212b30c360d26f9a02136422 | jq
-    ```
+   ```console
+   cargo run -p torrust-tracker-client --bin udp_tracker_client announce \
+     udp://tracker.torrust-demo.com:6969/announce \
+     9c38422213e30bff212b30c360d26f9a02136422 | jq
+   ```
 
-    Simulate a torrent scrape to the tracker using HTTP:
+   Simulate a torrent scrape to the tracker using HTTP:
 
-    ```console
-    cargo run -p torrust-tracker-client --bin http_tracker_client announce https://tracker.torrust-demo.com 9c38422213e30bff212b30c360d26f9a02136422 | jq
-    ```
+   ```console
+   cargo run -p torrust-tracker-client --bin http_tracker_client announce \
+     https://tracker.torrust-demo.com \
+     9c38422213e30bff212b30c360d26f9a02136422 | jq
+   ```
 
-    Make a request to the health check endpoint:
+   Make a request to the health check endpoint:
 
-    ```console
-    TORRUST_CHECKER_CONFIG='{
-        "udp_trackers": ["udp://tracker.torrust-demo.com:6969/announce"],
-        "http_trackers": ["https://tracker.torrust-demo.com"],
-        "health_checks": ["https://tracker.torrust-demo.com/api/health_check"]
-    }' cargo run -p torrust-tracker-client --bin tracker_checker
+   ```console
+   TORRUST_CHECKER_CONFIG='{
+       "udp_trackers": ["udp://tracker.torrust-demo.com:6969/announce"],
+       "http_trackers": ["https://tracker.torrust-demo.com"],
+       "health_checks": ["https://tracker.torrust-demo.com/api/health_check"]
+   }' cargo run -p torrust-tracker-client --bin tracker_checker
 
-    ```
+   ```
 
 4. Check the logs of the tracker container to see if everything is working:
 
-    ```console
-    ./share/bin/tracker-filtered-logs.sh
-    ```
+   ```console
+   ./share/bin/tracker-filtered-logs.sh
+   ```

application/docs/rollbacks.md

@@ -1,57 +1,58 @@
 # Rollbacks
 
-If you have a problems after a [deployment](deployment.md), you can rollback to the previous version of the app.
+If you have a problems after a [deployment](deployment.md), you can rollback
+to the previous version of the app.
 
 1. SSH into the server.
 
 2. Check the docker images to see the previous version of the app:
 
-    ```console
-    docker images torrust/tracker
-    REPOSITORY        TAG       IMAGE ID       CREATED          SIZE
-    torrust/tracker   develop   b081a7499542   19 minutes ago   133MB
-    torrust/tracker   <none>    7dbdad453cf3   6 hours ago      133MB
-    ```
+   ```console
+   docker images torrust/tracker
+   REPOSITORY        TAG       IMAGE ID       CREATED          SIZE
+   torrust/tracker   develop   b081a7499542   19 minutes ago   133MB
+   torrust/tracker   <none>    7dbdad453cf3   6 hours ago      133MB
+   ```
 
 3. Tag the previous version of the app with a new name (e.g. `rollback`):
 
-    ```console
-    docker tag 7dbdad453cf3 torrust/tracker:rollback
-    ```
+   ```console
+   docker tag 7dbdad453cf3 torrust/tracker:rollback
+   ```
 
-    This command tags the image with ID `7dbdad453cf3` as `torrust/tracker:rollback`.
+   This command tags the image with ID `7dbdad453cf3` as `torrust/tracker:rollback`.
 
-    ```console
-      docker images torrust/tracker
-        REPOSITORY        TAG        IMAGE ID       CREATED          SIZE
-        torrust/tracker   develop    b081a7499542   21 minutes ago   133MB
-        torrust/tracker   rollback   7dbdad453cf3   6 hours ago      133MB
-    ```
+   ```console
+     docker images torrust/tracker
+       REPOSITORY        TAG        IMAGE ID       CREATED          SIZE
+       torrust/tracker   develop    b081a7499542   21 minutes ago   133MB
+       torrust/tracker   rollback   7dbdad453cf3   6 hours ago      133MB
+   ```
 
-    The `rollback` tag now points to the previous version of the app.
+   The `rollback` tag now points to the previous version of the app.
 
 4. Edit the `compose.yaml` file to use the new tag:
 
-    Change the line:
+   Change the line:
 
-    ```yaml
-    image: torrust/tracker:develop
-    ```
+   ```yaml
+   image: torrust/tracker:develop
+   ```
 
-    to:
+   to:
 
-    ```yaml
-    image: torrust/tracker:rollback
-    ```
+   ```yaml
+   image: torrust/tracker:rollback
+   ```
 
 5. Run the following command to start the previous version of the app:
 
-    ```console
-    docker compose up --build --detach
-    ```
+   ```console
+   docker compose up --build --detach
+   ```
 
 6. Check the logs of the tracker container to see if everything is working:
 
-    ```console
-    ./share/bin/tracker-filtered-logs.sh
-    ```
+   ```console
+   ./share/bin/tracker-filtered-logs.sh
+   ```

application/docs/useful-commands.md

@@ -3,5 +3,6 @@
 - `docker ps`: list containers.
 - `docker compose logs -f`: print all containers' logs.
 - `docker compose logs -f tracker`: print tracker container' logs.
-- `docker compose logs -f tracker | head -n100`: print the first 100 lines in the tracker container log.
+- `docker compose logs -f tracker | head -n100`: print the first 100 lines
+  in the tracker container log.
 - `docker compose logs -f | grep "ERROR"`: print logs showing only errors.

docs/guides/integration-testing-guide.md

@@ -106,7 +106,6 @@ ls infrastructure/terraform/terraform.tfstate* 2>/dev/null && \
 
 **Expected Output**: All checks should show "✅" (no conflicts).
 
-
 ### 1.4.1 Manual Cleanup (if needed)
 
 If the verification step shows "❌ Volumes still exist!" then manually clean them:
@@ -126,7 +125,8 @@ virsh vol-list user-default 2>/dev/null | grep torrust-tracker-demo && \
 
 **Expected Output**: Should show "✅ No volume conflicts" after manual cleanup.
 
-**What This Fixes**: Removes leftover volumes that `make clean-and-fix` sometimes misses.
+**What This Fixes**: Removes leftover volumes that `make clean-and-fix`
+sometimes misses.
 
 ### 1.5 Set Up SSH Key Configuration
 
@@ -328,7 +328,7 @@ sudo systemctl status cloud-init-local cloud-init cloud-config cloud-final
 # Exit console: Ctrl+]
 ```
 
-**Method 2: Use virt-viewer for graphical console access**
+#### Method 2: Use virt-viewer for graphical console access
 
 ```bash
 # Connect to VM graphical console (shows login prompt)
@@ -338,7 +338,9 @@ virt-viewer spice://127.0.0.1:5900
 virt-viewer torrust-tracker-demo
 ```
 
-**Note**: The virt-viewer method provides a graphical console where you should see a login prompt. This is particularly useful when the text-based virsh console doesn't work or when you need to see the full boot process.
+**Note**: The virt-viewer method provides a graphical console where you should
+see a login prompt. This is particularly useful when the text-based virsh
+console doesn't work or when you need to see the full boot process.
 
 #### Check from Host System