feat: add VM console access commands and documentation

- Add 'make console' command for text-based VM console access
- Add 'make vm-console' command for graphical VM console access via virt-viewer
- Update install-deps to include virt-viewer package
- Document virt-viewer usage in integration testing guide
- Update local testing setup documentation with console access options
- Add console commands to main commands table in copilot instructions

These commands provide easy access to VM console for debugging when SSH fails
during cloud-init or boot processes. Users can now use:
- virt-viewer spice://127.0.0.1:5900 for graphical console
- virsh console for text-based console access

Author: josecelano

.github/copilot-instructions.md

@@ -121,11 +121,13 @@ make test-syntax # Syntax validation only
 | Command                   | Purpose                           |
 | ------------------------- | --------------------------------- |
 | `make help`               | Show all available commands       |
-| `make install-deps`       | Install OpenTofu, libvirt, KVM    |
+| `make install-deps`       | Install OpenTofu, libvirt, KVM, virt-viewer |
 | `make test`               | Run complete infrastructure tests |
 | `make apply`              | Deploy VM with full configuration |
 | `make apply-minimal`      | Deploy VM with minimal config     |
 | `make ssh`                | Connect to deployed VM            |
+| `make console`            | Access VM console (text-based)    |
+| `make vm-console`         | Access VM graphical console (GUI) |
 | `make destroy`            | Remove deployed VM                |
 | `make monitor-cloud-init` | Watch VM provisioning progress    |
 

Makefile

@@ -1,5 +1,5 @@
 # Makefile for Torrust Tracker Local Testing Infrastructure
-.PHONY: help init plan apply destroy test clean status ssh install-deps
+.PHONY: help init plan apply destroy test clean status ssh install-deps console vm-console
 
 # Default variables
 VM_NAME ?= torrust-tracker-demo
@@ -16,7 +16,7 @@ help: ## Show this help message
 install-deps: ## Install required dependencies (Ubuntu/Debian)
 	@echo "Installing dependencies..."
 	sudo apt update
-	sudo apt install -y qemu-kvm libvirt-daemon-system libvirt-clients bridge-utils virt-manager genisoimage
+	sudo apt install -y qemu-kvm libvirt-daemon-system libvirt-clients bridge-utils virt-manager virt-viewer genisoimage
 	sudo usermod -aG libvirt $$USER
 	sudo usermod -aG kvm $$USER
 	sudo systemctl enable libvirtd
@@ -306,3 +306,17 @@ vm-info: ## Show detailed VM network information
 	@echo ""
 	@echo "DHCP leases:"
 	@virsh net-dhcp-leases default 2>/dev/null | grep $(VM_NAME) || echo "No DHCP lease found"
+
+console: ## Access VM console (text-based)
+	@echo "Connecting to VM console..."
+	@echo "Use Ctrl+] to exit console"
+	@virsh console $(VM_NAME)
+
+vm-console: ## Access VM graphical console (GUI)
+	@echo "Opening VM graphical console..."
+	@if command -v virt-viewer >/dev/null 2>&1; then \
+		virt-viewer $(VM_NAME) || virt-viewer spice://127.0.0.1:5900; \
+	else \
+		echo "virt-viewer not found. Please install it:"; \
+		echo "  sudo apt install virt-viewer"; \
+	fi

docs/guides/integration-testing-guide.md

@@ -316,7 +316,7 @@ techniques based on [cloud-init debugging documentation](https://cloudinit.readt
 #### Access VM Console
 
 ```bash
-# Connect to VM console (bypass SSH)
+# Method 1: Connect to VM console via virsh (text-based)
 virsh console torrust-tracker-demo
 
 # Login as 'ubuntu' (default user) with no password, then:
@@ -328,6 +328,18 @@ sudo systemctl status cloud-init-local cloud-init cloud-config cloud-final
 # Exit console: Ctrl+]
 ```
 
+**Method 2: Use virt-viewer for graphical console access**
+
+```bash
+# Connect to VM graphical console (shows login prompt)
+virt-viewer spice://127.0.0.1:5900
+
+# Alternative using VM name
+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.
+
 #### Check from Host System
 
 ```bash

infrastructure/docs/local-testing-setup.md

@@ -306,7 +306,7 @@ tofu refresh
 5. **SSH connection refused**
 
    - VM might still be booting/configuring
-   - Check VM console: `virsh console torrust-tracker-demo`
+   - Check VM console: `virsh console torrust-tracker-demo` or `virt-viewer spice://127.0.0.1:5900`
    - Verify firewall rules
 
 6. **VM deployment timeout (can't get IP address)**
@@ -315,6 +315,6 @@ tofu refresh
      configuration, reboot)
    - **Solution**: This is normal; VM will get IP after cloud-init completes
      (~5-10 minutes)
-   - **Check**: Use `virsh console torrust-tracker-demo` to monitor boot progress
+   - **Check**: Use `virsh console torrust-tracker-demo` or `virt-viewer spice://127.0.0.1:5900` to monitor boot progress
 
 ### Logs and Debugging