Skip to content

configure.md

Latest commit

 

History

History
450 lines (320 loc) · 12.7 KB

configure.md

File metadata and controls

450 lines (320 loc) · 12.7 KB

configure - Configure Provisioned Infrastructure

Configure software dependencies on provisioned infrastructure.

Purpose

Installs and configures Docker and Docker Compose on provisioned VM infrastructure. This command takes an environment from the "Provisioned" state to the "Configured" state with all required software installed.

Command Syntax

torrust-tracker-deployer configure <ENVIRONMENT>

Verbosity Levels

Control the amount of progress detail displayed during configuration with the global -v flag. This helps you see what's happening under the hood when you need more visibility.

Available Levels

Level Flag Shows Use Case
Normal (default) Essential progress and results Regular usage, clean output
Verbose -v + Detailed progress (4 configuration steps) Understanding the configuration workflow
VeryVerbose -vv + Context details (versions, status) Troubleshooting configuration issues
Debug -vvv + Technical details (Ansible commands) Deep troubleshooting, development debugging

Important: Verbosity controls only progress messages. For internal diagnostic logs, use the RUST_LOG environment variable (see Logging Guide).

Normal Level (Default)

Shows essential progress with minimal output:

torrust-tracker-deployer configure my-env

Output:

⏳ [1/3] Validating environment...
⏳   ✓ Environment name validated: my-env (took 0ms)
⏳ [2/3] Creating command handler...
⏳   ✓ Done (took 0ms)
⏳ [3/3] Configuring infrastructure...
⏳   ✓ Infrastructure configured (took 37.3s)
✅ Environment 'my-env' configured successfully

Verbose Level (-v)

Shows the 4 internal configuration steps:

torrust-tracker-deployer configure my-env -v

Output:

⏳ [1/3] Validating environment...
⏳   ✓ Environment name validated: my-env (took 0ms)
⏳ [2/3] Creating command handler...
⏳   ✓ Done (took 0ms)
⏳ [3/3] Configuring infrastructure...
📋   [Step 1/4] Installing Docker...
📋   [Step 2/4] Installing Docker Compose...
📋   [Step 3/4] Configuring automatic security updates...
📋   [Step 4/4] Configuring firewall (UFW)...
⏳   ✓ Infrastructure configured (took 34.1s)
✅ Environment 'my-env' configured successfully

When to use: Understanding the configuration workflow, seeing which step is taking time, or confirming the command is making progress.

VeryVerbose Level (-vv)

Adds contextual details like software versions, configurations, and status information:

torrust-tracker-deployer configure my-env -vv

Output:

⏳ [3/3] Configuring infrastructure...
📋   [Step 1/4] Installing Docker...
📋      → Installing Docker Engine from official repository
📋      → Docker version: 24.0.7
📋   [Step 2/4] Installing Docker Compose...
📋      → Installing Docker Compose plugin
📋      → Compose version: 2.23.3
📋   [Step 3/4] Configuring automatic security updates...
📋      → Configuring unattended-upgrades for automatic security patches
📋      → Update configuration status: enabled
📋   [Step 4/4] Configuring firewall (UFW)...
📋      → Configuring UFW with restrictive default policies
📋      → Allowing SSH access before enabling firewall
📋      → Firewall status: active
⏳   ✓ Infrastructure configured (took 34.1s)
✅ Environment 'my-env' configured successfully

When to use: Troubleshooting installation issues, verifying software versions, understanding firewall configurations, or monitoring security update setup.

Debug Level (-vvv)

Shows technical implementation details including Ansible commands executed:

torrust-tracker-deployer configure my-env -vvv

Output:

⏳ [3/3] Configuring infrastructure...
📋   [Step 1/4] Installing Docker...
🔍      → Ansible working directory: ./build/my-env/ansible
🔍      → Executing playbook: ansible-playbook install-docker.yml -i inventory.ini
📋      → Installing Docker Engine from official repository
📋      → Docker version: 24.0.7
📋   [Step 2/4] Installing Docker Compose...
🔍      → Ansible working directory: ./build/my-env/ansible
🔍      → Executing playbook: ansible-playbook install-docker-compose.yml -i inventory.ini
📋      → Installing Docker Compose plugin
📋      → Compose version: 2.23.3
📋   [Step 3/4] Configuring automatic security updates...
🔍      → Ansible working directory: ./build/my-env/ansible
🔍      → Executing playbook: ansible-playbook configure-security-updates.yml -i inventory.ini
📋      → Configuring unattended-upgrades for automatic security patches
📋      → Update configuration status: enabled
📋   [Step 4/4] Configuring firewall (UFW)...
🔍      → Ansible working directory: ./build/my-env/ansible
🔍      → Executing playbook: ansible-playbook configure-firewall.yml -e @variables.yml -i inventory.ini
📋      → Configuring UFW with restrictive default policies
📋      → Allowing SSH access before enabling firewall
📋      → Firewall status: active
⏳   ✓ Infrastructure configured (took 36.0s)
✅ Environment 'my-env' configured successfully

When to use: Deep debugging, understanding exactly what Ansible playbooks are executed, verifying working directories, or reporting issues with detailed context.

Symbol Legend:

  • ⏳ = Major progress milestone (all levels)
  • ✅ = Success message (all levels)
  • 📋 = Detailed progress (Verbose -v and above)
  • 🔍 = Technical details (Debug -vvv only)

Combining with Other Flags

Verbosity works with all other flags:

# Debug output with file and stderr logging
torrust-tracker-deployer configure my-env -vvv --log-output file-and-stderr

# Verbose output with custom log file
torrust-tracker-deployer configure my-env -v --log-output file --log-file custom.log

Arguments

  • <ENVIRONMENT> (required) - Name of the environment to configure

Prerequisites

  1. Environment provisioned - Must run provision first
  2. VM running - Instance must be accessible via SSH
  3. Ansible installed - Ansible CLI available in PATH
  4. SSH connectivity - Network access to VM

State Transition

[Provisioned] --configure--> [Configured]

What Happens

When you configure an environment:

  1. Validates prerequisites - Checks environment state and connectivity
  2. Runs Ansible playbooks - Executes configuration management tasks
  3. Installs Docker - Sets up Docker Engine
  4. Installs Docker Compose - Sets up Docker Compose plugin
  5. Configures user permissions - Adds SSH user to docker group
  6. Verifies installation - Tests Docker and Docker Compose availability
  7. Updates environment state - Transitions to "Configured"

Examples

Basic configuration

# Configure the environment
torrust-tracker-deployer configure full-stack-docs

# Output:
# ⏳ [1/3] Validating environment...
# ⏳   ✓ Environment name validated: full-stack-docs (took 0ms)
# ⏳ [2/3] Creating command handler...
# ⏳   ✓ Done (took 0ms)
# ⏳ [3/3] Configuring infrastructure...
# ⏳   ✓ Infrastructure configured (took 38.2s)
# ✅ Environment 'full-stack-docs' configured successfully

Configure multiple environments

# Development
torrust-tracker-deployer configure dev-local

# Staging
torrust-tracker-deployer configure staging

# Production
torrust-tracker-deployer configure production

Full workflow from start

# Complete setup sequence
torrust-tracker-deployer create environment -f config.json
torrust-tracker-deployer provision my-environment
torrust-tracker-deployer configure my-environment
torrust-tracker-deployer test my-environment

Output

The configure command installs:

  • Docker Engine - Latest stable version
  • Docker Compose - Plugin version (v2.x)
  • User permissions - SSH user added to docker group
  • Verification results - Docker and Compose version info

Ansible logs are written to:

  • data/logs/ansible-<timestamp>.log

Next Steps

After configuration:

# Verify the infrastructure is ready
torrust-tracker-deployer test my-environment

# Expected output:
# ✓ All infrastructure tests passed

Troubleshooting

Environment not provisioned

Problem: Cannot configure an environment that hasn't been provisioned

Solution: Provision the environment first

# Check environment state
cat data/my-environment/state.json

# If state is "Created", provision first
torrust-tracker-deployer provision my-environment

Ansible not found

Problem: Ansible CLI is not installed or not in PATH

Solution: Install Ansible

# Ubuntu/Debian
sudo apt update
sudo apt install ansible

# Or use pip
pip install ansible

# Verify installation
ansible --version

SSH connection failed

Problem: Cannot connect to VM via SSH

Solution: Verify VM is running and SSH is accessible

# Check VM status
lxc list

# Get VM IP
lxc list my-environment --format json | jq -r '.[0].state.network.eth0.addresses[0].address'

# Try manual SSH connection
ssh -i <private-key> torrust@<vm-ip>

# If cloud-init is still running, wait for it
lxc exec <instance-name> -- cloud-init status --wait

Docker installation failed

Problem: Ansible playbook fails during Docker installation

Solution: Check Ansible logs and VM network connectivity

# Review Ansible logs
tail -f data/logs/ansible-*.log

# Manually check VM network
lxc exec <instance-name> -- ping -c 3 8.8.8.8

# Check VM DNS
lxc exec <instance-name> -- cat /etc/resolv.conf

# Retry configuration
torrust-tracker-deployer configure my-environment

Permission denied after install

Problem: User cannot run Docker commands without sudo

Solution: The configure command should handle this, but if it fails:

# SSH into the VM
ssh -i <private-key> torrust@<vm-ip>

# Add user to docker group (done by playbook normally)
sudo usermod -aG docker $USER

# Log out and log back in for group changes to take effect
exit
ssh -i <private-key> torrust@<vm-ip>

# Verify
docker ps

Common Use Cases

Automated testing pipeline

#!/bin/bash
set -e

ENV_NAME="test-${BUILD_ID}"

# Setup
torrust-tracker-deployer create environment -f test.json
torrust-tracker-deployer provision ${ENV_NAME}
torrust-tracker-deployer configure ${ENV_NAME}

# Verify
torrust-tracker-deployer test ${ENV_NAME}

# Your tests here...

# Cleanup
torrust-tracker-deployer destroy ${ENV_NAME}

Manual development setup

# Set up infrastructure
torrust-tracker-deployer create environment -f dev.json
torrust-tracker-deployer provision dev-local
torrust-tracker-deployer configure dev-local

# SSH into VM for manual work
ssh -i fixtures/testing_rsa torrust@$(lxc list --format json | jq -r '.[0].state.network.eth0.addresses[0].address')

# Inside VM: verify Docker
docker --version
docker compose version

Reconfiguration

If you need to reconfigure without reprovisioning:

# Just run configure again (idempotent)
torrust-tracker-deployer configure my-environment

# Ansible playbooks are designed to be idempotent
# Safe to run multiple times

Technical Details

Ansible Playbooks

The configure command runs these playbooks in order:

  1. install-docker.yml - Installs Docker Engine

    • Adds Docker GPG key
    • Adds Docker repository
    • Installs docker-ce, docker-ce-cli, containerd.io
    • Starts and enables Docker service

  2. install-docker-compose.yml - Installs Docker Compose

    • Downloads Docker Compose plugin
    • Installs to /usr/local/lib/docker/cli-plugins/docker-compose
    • Sets executable permissions

  3. configure-docker-permissions.yml - Sets up user permissions

    • Adds SSH user to docker group
    • Applies group changes

Generated Files

Configuration generates:

  • Ansible inventory - build/<env>/ansible/inventory.yml
  • Ansible logs - data/logs/ansible-<timestamp>.log
  • Environment state - Updated with "Configured" status

Verification Steps

After configuration, the command verifies:

  • Docker daemon is running
  • Docker CLI is accessible
  • Docker Compose is installed
  • User has docker group permissions

See Also

  • provision - Provision infrastructure (prerequisite)
  • test - Verify configuration (next step)
  • destroy - Clean up infrastructure
  • create - Create environment