Skip to content

Commit dffdde1

Browse files
josecelanojosecelano
committed
docs: add issue specification for #409 
1 parent 986bc9b commit dffdde1

1 file changed

Lines changed: 130 additions & 0 deletions

File tree

‎docs/issues/409-fix-hardcoded-deploy-dir-in-ansible-templates.md‎

Lines changed: 130 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,130 @@
1+
# Fix Hardcoded Deployment Directory in Ansible Templates
2+
3+
**Issue**: #409
4+
**Parent Epic**: None
5+
**Related**: #405 - Deploy Hetzner Demo Tracker and Document the Process
6+
7+
## Overview
8+
9+
Several Ansible playbook templates under `templates/ansible/` hardcode the deployment directory as `/opt/torrust` instead of using the `{{ deploy_dir }}` variable sourced from `variables.yml`. This causes deployment failures when a user configures a custom deployment directory other than the default `/opt/torrust`.
10+
11+
The correct pattern — used by `create-grafana-storage.yml`, `create-mysql-storage.yml`, and `deploy-grafana-provisioning.yml` — is to load `variables.yml` via `vars_files` and reference `{{ deploy_dir }}` in all paths.
12+
13+
This bug was discovered while deploying the Torrust Tracker demo to the Hetzner provider (issue #405).
14+
15+
## Goals
16+
17+
- [ ] Replace all hardcoded `/opt/torrust` path occurrences in `templates/ansible/` task definitions with `{{ deploy_dir }}`
18+
- [ ] Ensure all affected playbooks load `variables.yml` via `vars_files` where not already done
19+
- [ ] Standardize the variable name (`deploy_dir`) across all playbooks — `deploy-compose-files.yml` currently uses a different name (`remote_deploy_dir`)
20+
- [ ] Verify the fix works for both the default value `/opt/torrust` and a custom deployment directory
21+
22+
## Specifications
23+
24+
### Affected Templates
25+
26+
The following 10 templates need to be updated:
27+
28+
#### 1. Templates with fully hardcoded paths (no variable usage at all)
29+
30+
These templates use `/opt/torrust` directly in task `path:`, `dest:`, and loop items. None of them load `variables.yml`.
31+
32+
| Template | Hardcoded occurrences |
33+
| ------------------------------------------------- | ---------------------------------- |
34+
| `templates/ansible/create-tracker-storage.yml` | 3 (loop items) |
35+
| `templates/ansible/create-prometheus-storage.yml` | 1 (loop item) |
36+
| `templates/ansible/create-backup-storage.yml` | 2 (`path:` params) |
37+
| `templates/ansible/deploy-backup-config.yml` | 4 (`dest:` and `path:` params) |
38+
| `templates/ansible/deploy-tracker-config.yml` | 2 (`dest:` and `path:` params) |
39+
| `templates/ansible/deploy-prometheus-config.yml` | 2 (`dest:` and `path:` params) |
40+
| `templates/ansible/init-tracker-database.yml` | 2 (`path:` params) |
41+
| `templates/ansible/deploy-caddy-config.yml` | 6 (loop items + `dest:` + `path:`) |
42+
43+
#### 2. Templates using a variable inline (not from `variables.yml`)
44+
45+
These templates define the deployment directory as an inline playbook variable, bypassing the user-configured value from `variables.yml`.
46+
47+
| Template | Issue |
48+
| -------------------------------------------- | ----------------------------------------------------------------------------------------------------------------- |
49+
| `templates/ansible/run-compose-services.yml` | Defines `deploy_dir: /opt/torrust` inline — does not load from `variables.yml` |
50+
| `templates/ansible/deploy-compose-files.yml` | Defines `remote_deploy_dir: /opt/torrust` inline — different variable name AND does not load from `variables.yml` |
51+
52+
#### 3. Templates already correct (reference)
53+
54+
These correctly use `vars_files: variables.yml` and `{{ deploy_dir }}`:
55+
56+
- `templates/ansible/create-grafana-storage.yml` ✓
57+
- `templates/ansible/create-mysql-storage.yml` ✓
58+
- `templates/ansible/deploy-grafana-provisioning.yml` ✓
59+
60+
### Required Fix Pattern
61+
62+
Each affected playbook must be updated to follow the correct pattern:
63+
64+
```yaml
65+
- name: <playbook name>
66+
hosts: all
67+
become: true
68+
vars_files:
69+
- variables.yml
70+
71+
tasks:
72+
- name: <task name>
73+
ansible.builtin.file:
74+
path: "{{ deploy_dir }}/storage/..."
75+
```
76+
77+
### Variable Naming
78+
79+
The variable must consistently be named `deploy_dir` across all playbooks, matching the name defined in `variables.yml.tera`:
80+
81+
```yaml
82+
deploy_dir: /opt/torrust
83+
```
84+
85+
The `deploy-compose-files.yml` template must be updated to rename `remote_deploy_dir` to `deploy_dir` for consistency.
86+
87+
## Implementation Plan
88+
89+
### Phase 1: Fix fully hardcoded templates
90+
91+
- [ ] `create-tracker-storage.yml`: Add `vars_files: variables.yml` and replace all 3 hardcoded loop items with `{{ deploy_dir }}/storage/...`
92+
- [ ] `create-prometheus-storage.yml`: Add `vars_files: variables.yml` and replace the hardcoded loop item
93+
- [ ] `create-backup-storage.yml`: Add `vars_files: variables.yml` and replace 2 hardcoded `path:` values
94+
- [ ] `deploy-backup-config.yml`: Add `vars_files: variables.yml` and replace all 4 hardcoded `dest:`/`path:` values
95+
- [ ] `deploy-tracker-config.yml`: Add `vars_files: variables.yml` and replace 2 hardcoded `dest:`/`path:` values
96+
- [ ] `deploy-prometheus-config.yml`: Add `vars_files: variables.yml` and replace 2 hardcoded `dest:`/`path:` values
97+
- [ ] `init-tracker-database.yml`: Add `vars_files: variables.yml` and replace 2 hardcoded `path:` values
98+
- [ ] `deploy-caddy-config.yml`: Add `vars_files: variables.yml` and replace all 6 hardcoded occurrences
99+
100+
### Phase 2: Fix inline-variable templates
101+
102+
- [ ] `run-compose-services.yml`: Remove inline `deploy_dir: /opt/torrust` from `vars` and add `vars_files: variables.yml` instead
103+
- [ ] `deploy-compose-files.yml`: Remove inline `remote_deploy_dir: /opt/torrust` from `vars`, add `vars_files: variables.yml`, and rename all `remote_deploy_dir` references to `deploy_dir`
104+
105+
### Phase 3: Update comments in affected templates
106+
107+
- [ ] Update inline comments in all modified templates to reference `{{ deploy_dir }}` instead of `/opt/torrust` as the example path (where applicable)
108+
- [ ] Run linters: `cargo run --bin linter all`
109+
110+
## Acceptance Criteria
111+
112+
> **Note for Contributors**: These criteria define what the PR reviewer will check. Use this as your pre-review checklist before submitting the PR to minimize back-and-forth iterations.
113+
114+
**Quality Checks**:
115+
116+
- [ ] Pre-commit checks pass: `./scripts/pre-commit.sh`
117+
118+
**Task-Specific Criteria**:
119+
120+
- [ ] No playbook task in `templates/ansible/` uses a hardcoded `/opt/torrust` path in `path:`, `dest:`, or loop items
121+
- [ ] All playbooks that reference the deployment directory load `variables.yml` via `vars_files`
122+
- [ ] The variable name `deploy_dir` is used consistently (no `remote_deploy_dir` or other aliases)
123+
- [ ] Playbooks that previously had inline `vars:` blocks for the deploy directory no longer define it inline
124+
- [ ] The default behavior (with `deploy_dir: /opt/torrust`) is unchanged
125+
126+
## Related Documentation
127+
128+
- [docs/issues/409-fix-hardcoded-deploy-dir-in-ansible-templates.md](409-fix-hardcoded-deploy-dir-in-ansible-templates.md) — this specification
129+
- [templates/ansible/variables.yml.tera](../../templates/ansible/variables.yml.tera) — defines `deploy_dir`
130+
- [docs/issues/405-deploy-hetzner-demo-tracker-and-document-process.md](405-deploy-hetzner-demo-tracker-and-document-process.md) — parent issue where this bug was discovered

0 commit comments

Comments
 (0)