feat: add design document for tracker version coupling

Author: josecelano

docs/redesign/phase3-design/tracker-version-coupling.md

@@ -0,0 +1,156 @@
+# Design Prop
+
+## 1. Overview
+
+This document proposes a design to decouple the Torrust Tracker Demo installer from specific
+tracker versions. The current implementation has an implicit dependency on a single tracker
+version, which limits flexibility and makes upgrades difficult. This proposal introduces a
+version management system that allows users to specify the desired tracker version for
+deployment.
+
+## 2. Problem Statement
+
+The current deployment process is tightly coupled to a specific version of the Torrust
+Tracker. This coupling manifests in two key areas:
+
+1. **Docker Image**: The `docker-compose.yaml` file references a hardcoded Docker
+   image tag, which corresponds to a specific tracker release.
+2. **Configuration Templates**: The configuration templates (e.g.,
+   `tracker.toml.tpl`) are designed for a specific tracker version and may not
+   be compatible with other releases.
+
+This tight coupling makes it difficult to:
+
+- Deploy older or newer versions of the tracker.
+- Test different tracker releases in a consistent manner.
+- Manage configuration changes between tracker versions.
+
+## 3. Proposed Solution
+
+We will implement a version management system that allows users to define the desired
+tracker version in their deployment configuration. This system will consist of the
+following components:
+
+### 3.1. User-Defined Tracker Version
+
+The user will specify the tracker version in the environment configuration file
+(e.g., `development-libvirt.env`). A new variable, `TRACKER_VERSION`, will be
+introduced for this purpose.
+
+**Example Configuration (`development-libvirt.env`):**
+
+```env
+# ... other configuration ...
+
+# -- Tracker Version Configuration --
+# Specifies the version of the Torrust Tracker to deploy.
+# Can be a specific version (e.g., "v2.0.0") or "latest".
+TRACKER_VERSION=v2.0.0
+```
+
+### 3.2. Version-Specific Docker Images
+
+The `docker-compose.yaml` file will be updated to use the `TRACKER_VERSION` variable to
+dynamically select the appropriate Docker image.
+
+**Example `compose.yaml`:**
+
+```yaml
+services:
+  tracker:
+    image: ghcr.io/torrust/torrust-tracker:${TRACKER_VERSION:-latest}
+    # ... other service configuration ...
+```
+
+This change allows the deployment to pull the correct Docker image based on the user's
+configuration. The `:-latest` default ensures backward compatibility and provides a
+sensible default if the variable is not set.
+
+### 3.3. Versioned Configuration Templates
+
+To manage configuration differences between tracker releases, we will introduce a
+versioned directory structure for configuration templates.
+
+**Proposed Directory Structure:**
+
+```text
+application/
+└── config/
+    └── templates/
+        └── tracker/
+            ├── v2.0.0/
+            │   └── tracker.toml.tpl
+            ├── v2.1.0/
+            │   └── tracker.toml.tpl
+            └── latest/
+                └── tracker.toml.tpl
+```
+
+The deployment script (`configure-app.sh`) will be updated to select the appropriate
+template directory based on the `TRACKER_VERSION` variable.
+
+**Deployment Logic (`configure-app.sh`):**
+
+```bash
+# ... other script logic ...
+
+# Determine the template directory based on the tracker version
+if [ -d "application/config/templates/tracker/${TRACKER_VERSION}" ]; then
+  TEMPLATE_DIR="application/config/templates/tracker/${TRACKER_VERSION}"
+else
+  # Fallback to the 'latest' templates if the specific version is not found
+  TEMPLATE_DIR="application/config/templates/tracker/latest"
+fi
+
+# Process the tracker configuration template
+envsubst < "${TEMPLATE_DIR}/tracker.toml.tpl" > "path/to/generated/tracker.toml"
+
+# ... other script logic ...
+```
+
+This approach ensures that the generated configuration is always compatible with the
+deployed tracker version.
+
+### 3.4. "Latest" Version Support
+
+A special version, `latest`, will be supported to facilitate testing and development.
+When `TRACKER_VERSION` is set to `latest`:
+
+- The deployment will use the `latest` tag for the Docker image, which typically
+  corresponds to the tracker's development branch.
+- The configuration templates from the
+  `application/config/templates/tracker/latest/` directory will be used.
+
+This allows for continuous integration and testing against the most recent tracker
+updates without requiring a new release.
+
+## 4. Implementation Plan
+
+1. **Add `TRACKER_VERSION` to Environment Configuration**:
+
+   - Update all environment configuration files (`*.env`) to include the `TRACKER_VERSION` variable.
+   - Set a sensible default (e.g., the current stable release).
+
+2. **Update `docker-compose.yaml`**:
+
+   - Modify the `tracker` service to use the `TRACKER_VERSION` variable for the image tag.
+
+3. **Create Versioned Template Directories**:
+
+   - Reorganize the tracker configuration templates into the versioned directory
+     structure described above.
+   - Ensure that templates for all supported tracker versions are available.
+
+4. **Update Deployment Scripts**:
+   - Modify `configure-app.sh` to select the correct template directory based on `TRACKER_VERSION`.
+   - Add logic to fall back to the `latest` directory if a specific version is not found.
+
+## 5. Benefits
+
+- **Flexibility**: Users can deploy any supported version of the Torrust Tracker.
+- **Maintainability**: Configuration changes between tracker versions are managed
+  in a structured and predictable way.
+- **Testability**: The "latest" version support allows for continuous testing
+  against the tracker's development branch.
+- **Clarity**: The deployment configuration explicitly defines the tracker version,
+  making the deployment process more transparent.