Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
18 changes: 8 additions & 10 deletions docs/user-guide/commands/configure.md
Original file line number Diff line number Diff line change
Expand Up @@ -47,16 +47,16 @@ When you configure an environment:

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

# Output:
# Validating prerequisites...
# ✓ Running Ansible playbooks...
# ✓ Installing Docker...
# ✓ Installing Docker Compose...
# Configuring permissions...
# ✓ Verifying installation...
# Environment configured successfully
# ⏳ [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
Expand Down Expand Up @@ -261,14 +261,12 @@ torrust-tracker-deployer configure my-environment
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
Expand Down
18 changes: 9 additions & 9 deletions docs/user-guide/commands/create.md
Original file line number Diff line number Diff line change
Expand Up @@ -248,21 +248,21 @@ torrust-tracker-deployer create environment --env-file config.json

```text
⏳ [1/3] Loading configuration...
⏳ → Loading configuration from 'config.json'...
⏳ ✓ Configuration loaded: my-env (took 2ms)
⏳ → Loading configuration from 'envs/full-stack-docs.json'...
⏳ ✓ Configuration loaded: full-stack-docs (took 0ms)
⏳ [2/3] Creating command handler...
⏳ ✓ Done (took 0ms)
⏳ [3/3] Creating environment...
⏳ → Creating environment 'my-env'...
⏳ → Creating environment 'full-stack-docs'...
⏳ → Validating configuration and creating environment...
⏳ ✓ Environment created: my-env (took 15ms)
✅ Environment 'my-env' created successfully
⏳ ✓ Environment created: full-stack-docs (took 1ms)
✅ Environment 'full-stack-docs' created successfully

Environment Details:
1. Environment name: my-env
2. Instance name: torrust-tracker-vm-my-env
3. Data directory: ./data/my-env
4. Build directory: ./build/my-env
1. Environment name: full-stack-docs
2. Instance name: torrust-tracker-vm-full-stack-docs
3. Data directory: ./data/full-stack-docs
4. Build directory: ./build/full-stack-docs
```

**Features**:
Expand Down
25 changes: 20 additions & 5 deletions docs/user-guide/commands/destroy.md
Original file line number Diff line number Diff line change
Expand Up @@ -36,6 +36,21 @@ Destroy an environment:
torrust-tracker-deployer destroy my-environment
```

**Output**:

```text
⏳ [1/3] Validating environment...
⏳ ✓ Environment name validated: full-stack-docs (took 0ms)
⏳ [2/3] Creating command handler...
⏳ ✓ Done (took 0ms)
⏳ [3/3] Tearing down infrastructure...
⏳ ✓ Infrastructure torn down (took 2.6s)
✅ Environment 'full-stack-docs' destroyed successfully

💡 Local data preserved for debugging. To completely remove and reuse the name:
torrust-tracker-deployer purge full-stack-docs --force
```

With verbose logging to see progress:

```bash
Expand Down Expand Up @@ -344,18 +359,18 @@ name: Cleanup Test Environments

on:
schedule:
- cron: '0 2 * * *' # Run at 2 AM daily
- cron: "0 2 * * *" # Run at 2 AM daily

jobs:
cleanup:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v3

- name: Setup tools
run: |
# Install OpenTofu, LXD, etc.

- name: Destroy old environments
run: |
for env in test-1 test-2 staging-temp; do
Expand All @@ -382,14 +397,14 @@ for env in "${ENVIRONMENTS_TO_DESTROY[@]}"; do
echo "═══════════════════════════════════════════"
echo "Destroying environment: $env"
echo "═══════════════════════════════════════════"

if torrust-tracker-deployer destroy "$env"; then
echo "✓ Successfully destroyed $env"
else
echo "✗ Failed to destroy $env"
# Continue with other environments
fi

echo ""
done

Expand Down
52 changes: 29 additions & 23 deletions docs/user-guide/commands/provision.md
Original file line number Diff line number Diff line change
Expand Up @@ -35,34 +35,40 @@ Use the global `--output-format` flag to control the format.
The default output format provides human-readable information with visual formatting:

```bash
torrust-tracker-deployer provision my-environment
torrust-tracker-deployer provision full-stack-docs
```

**Output**:

```text
✓ Rendering OpenTofu templates...
✓ Initializing infrastructure...
✓ Planning infrastructure changes...
✓ Applying infrastructure...
✓ Retrieving instance information...
✓ Instance IP: 10.140.190.42
✓ Rendering Ansible templates...
✓ Waiting for SSH connectivity...
✓ Waiting for cloud-init completion...
✓ Environment provisioned successfully

Provisioning Details:
1. Environment name: my-environment
2. Instance name: torrust-tracker-vm-my-environment
3. Instance IP: 10.140.190.42
4. SSH credentials:
- Private key: /home/user/.ssh/id_rsa
- Public key: /home/user/.ssh/id_rsa.pub
- Username: torrust
- Port: 22
5. Provider: lxd
6. Domains: (none)
⏳ [1/3] Validating environment...
⏳ ✓ Environment name validated: full-stack-docs (took 0ms)
⏳ [2/3] Creating command handler...
⏳ ✓ Done (took 0ms)
⏳ [3/3] Provisioning infrastructure...
⏳ ✓ Infrastructure provisioned (took 26.5s)
✅ Environment 'full-stack-docs' provisioned successfully


Instance Connection Details:
IP Address: 10.140.190.211
SSH Port: 22
SSH Private Key: /home/josecelano/Documents/git/committer/me/github/torrust/torrust-tracker-deployer-agent-01/fixtures/testing_rsa
SSH Username: torrust

Connect using:
ssh -i /home/josecelano/Documents/git/committer/me/github/torrust/torrust-tracker-deployer-agent-01/fixtures/testing_rsa torrust@10.140.190.211 -p 22

⚠️ DNS Setup Required:
Your configuration uses custom domains. Remember to update your DNS records
to point your domains to the server IP: 10.140.190.211

Configured domains:
- tracker1.example.com
- tracker2.example.com
- api.example.com
- grafana.example.com
- health.example.com
```

**Features**:
Expand Down
10 changes: 10 additions & 0 deletions docs/user-guide/commands/purge.md
Original file line number Diff line number Diff line change
Expand Up @@ -61,6 +61,16 @@ For scripts and automation, use `--force` to skip the confirmation prompt:
torrust-tracker-deployer purge my-environment --force
```

**Output**:

```text
⏳ [1/3] Validating environment...
⏳ ✓ Done (took 0ms)
⏳ [2/3] Purging local data...
⏳ ✓ Done (took 0ms)
✅ Environment 'full-stack-docs' purged successfully
```

### With Verbose Logging

See detailed progress during purge:
Expand Down
12 changes: 11 additions & 1 deletion docs/user-guide/commands/release.md
Original file line number Diff line number Diff line change
Expand Up @@ -96,7 +96,17 @@ If backup is enabled in your environment configuration, the release command also

```bash
# Release after configuration
torrust-tracker-deployer release my-environment
torrust-tracker-deployer release full-stack-docs
```

**Output**:

```text
⏳ [1/2] Validating environment...
⏳ ✓ Environment name validated: full-stack-docs (took 0ms)
⏳ [2/2] Releasing application...
⏳ ✓ Application released successfully (took 27.4s)
✅ Release command completed successfully for 'full-stack-docs'
```

### Complete Workflow
Expand Down
25 changes: 17 additions & 8 deletions docs/user-guide/commands/run.md
Original file line number Diff line number Diff line change
Expand Up @@ -77,14 +77,23 @@ All services run inside a single `torrust/tracker:develop` Docker container.
When the run command completes successfully, it displays service URLs for easy access:

```text
✓ Run command completed for 'my-environment'

Service URLs:
API: http://192.168.1.100:1212
HTTP Tracker: http://192.168.1.100:7070
Health Check: http://192.168.1.100:1212/api/health_check

Tip: Run 'torrust-tracker-deployer show my-environment' for full details
⏳ [1/2] Validating environment...
⏳ ✓ Environment name validated: full-stack-docs (took 0ms)
⏳ [2/2] Running application services...
⏳ ✓ Services started (took 39.9s)
✅ Run command completed for 'full-stack-docs'

Services are now accessible:
Tracker (UDP): udp://10.140.190.211:6969/announce
Tracker (UDP): udp://10.140.190.211:6970/announce
Tracker (HTTP): https://tracker1.example.com/announce
Tracker (HTTP): https://tracker2.example.com/announce
API: https://api.example.com/api
Health Check: https://health.example.com/health_check
Grafana: https://grafana.example.com/

Note: HTTPS services require DNS configuration. See 'show' command for details.
Tip: Run 'torrust-tracker-deployer show full-stack-docs' for full details
```

**Notes**:
Expand Down
83 changes: 58 additions & 25 deletions docs/user-guide/commands/show.md
Original file line number Diff line number Diff line change
Expand Up @@ -68,31 +68,46 @@ Next: Run 'configure my-environment' to install software
When services have been deployed:

```text
Environment: my-environment
Environment: full-stack-docs
State: Running
Provider: LXD
Created: 2025-01-07 14:30:00 UTC
Created: 2026-02-17 12:10:49 UTC

Infrastructure:
Instance IP: 10.140.190.171
Instance IP: 10.140.190.211
SSH Port: 22
SSH User: torrust
SSH Key: ~/.ssh/torrust_deployer_key
SSH Key: /home/josecelano/Documents/git/committer/me/github/torrust/torrust-tracker-deployer-agent-01/fixtures/testing_rsa

Connection:
ssh -i ~/.ssh/torrust_deployer_key torrust@10.140.190.171
ssh -i /home/josecelano/Documents/git/committer/me/github/torrust/torrust-tracker-deployer-agent-01/fixtures/testing_rsa torrust@10.140.190.211

Tracker Services:
UDP Trackers:
- udp://10.140.190.171:6969/announce
HTTP Trackers:
- http://10.140.190.171:7070/announce
API Endpoint:
- http://10.140.190.171:1212/api
Health Check:
- http://10.140.190.171:1313/health_check

Tracker is running! Use the URLs above to connect.
- udp://10.140.190.211:6969/announce
- udp://10.140.190.211:6970/announce
HTTP Trackers (HTTPS via Caddy):
- https://tracker1.example.com/announce
- https://tracker2.example.com/announce
API Endpoint (HTTPS via Caddy):
- https://api.example.com/api
Health Check (HTTPS via Caddy):
- https://health.example.com/health_check

Prometheus:
Internal only (localhost:9090) - not exposed externally

Grafana (HTTPS via Caddy):
https://grafana.example.com/

Note: HTTPS services require domain-based access. For local domains (*.local),
add the following to your /etc/hosts file:

10.140.190.211 tracker1.example.com tracker2.example.com api.example.com grafana.example.com health.example.com

Internal ports (7070, 7071, 1212, 3000, 1313) are not directly accessible when TLS is enabled.

Services are running. Use 'test' to verify health.
```

## Output Formats
Expand Down Expand Up @@ -142,43 +157,61 @@ torrust-tracker-deployer show my-environment --output-format json

```json
{
"name": "my-environment",
"name": "full-stack-docs",
"state": "Running",
"provider": "LXD",
"created_at": "2026-02-11T09:52:28.800407753Z",
"created_at": "2026-02-17T12:10:49.328958106Z",
"infrastructure": {
"instance_ip": "10.140.190.36",
"instance_ip": "10.140.190.211",
"ssh_port": 22,
"ssh_user": "torrust",
"ssh_key_path": "/home/user/.ssh/torrust_key"
"ssh_key_path": "/home/josecelano/Documents/git/committer/me/github/torrust/torrust-tracker-deployer-agent-01/fixtures/testing_rsa"
},
"services": {
"udp_trackers": ["udp://udp.tracker.local:6969/announce"],
"https_http_trackers": ["https://http.tracker.local/announce"],
"udp_trackers": [
"udp://10.140.190.211:6969/announce",
"udp://10.140.190.211:6970/announce"
],
"https_http_trackers": [
"https://tracker1.example.com/announce",
"https://tracker2.example.com/announce"
],
"direct_http_trackers": [],
"localhost_http_trackers": [],
"api_endpoint": "https://api.tracker.local/api",
"api_endpoint": "https://api.example.com/api",
"api_uses_https": true,
"api_is_localhost_only": false,
"health_check_url": "https://health.tracker.local/health_check",
"health_check_url": "https://health.example.com/health_check",
"health_check_uses_https": true,
"health_check_is_localhost_only": false,
"tls_domains": [
{
"domain": "http.tracker.local",
"domain": "tracker1.example.com",
"internal_port": 7070
},
{
"domain": "api.tracker.local",
"domain": "tracker2.example.com",
"internal_port": 7071
},
{
"domain": "api.example.com",
"internal_port": 1212
},
{
"domain": "grafana.example.com",
"internal_port": 3000
},
{
"domain": "health.example.com",
"internal_port": 1313
}
]
},
"prometheus": {
"access_note": "Internal only (localhost:9090) - not exposed externally"
},
"grafana": {
"url": "https://grafana.tracker.local/",
"url": "https://grafana.example.com/",
"uses_https": true
},
"state_name": "running"
Expand Down
Loading
Loading