|
1 | | -# Setup Scripts |
| 1 | +# Setup Scripts - MIGRATION NOTICE |
2 | 2 |
|
3 | | -This directory contains installation and configuration scripts for the tools required by the Torrust Tracker Deployer project. |
| 3 | +**⚠️ This directory has been migrated to the Rust-based dependency installer.** |
4 | 4 |
|
5 | | -## Available Scripts |
| 5 | +## Migration Notice |
6 | 6 |
|
7 | | -### Core Infrastructure Tools |
| 7 | +The bash installation scripts (`install-opentofu.sh`, `install-ansible.sh`, `install-lxd-ci.sh`) have been **removed** and replaced with the Rust-based `dependency-installer` binary. |
8 | 8 |
|
9 | | -- **`install-opentofu.sh`** - Install OpenTofu (Terraform alternative) |
10 | | -- **`install-ansible.sh`** - Install Ansible automation platform |
| 9 | +### New Installation Method |
11 | 10 |
|
12 | | -### Container/VM Providers |
13 | | - |
14 | | -- **`install-lxd-ci.sh`** - Install and configure LXD (CI-optimized) |
15 | | - |
16 | | -## Usage |
17 | | - |
18 | | -### Individual Installation |
| 11 | +For dependency installation, use the `dependency-installer` binary: |
19 | 12 |
|
20 | 13 | ```bash |
21 | | -# Install OpenTofu |
22 | | -./scripts/setup/install-opentofu.sh |
23 | | - |
24 | | -# Install Ansible |
25 | | -./scripts/setup/install-ansible.sh |
| 14 | +# Install all dependencies |
| 15 | +cargo run -p torrust-dependency-installer --bin dependency-installer -- install |
26 | 16 |
|
27 | | -# Install LXD (CI environment) |
28 | | -./scripts/setup/install-lxd-ci.sh |
29 | | -``` |
| 17 | +# Check which dependencies are installed |
| 18 | +cargo run -p torrust-dependency-installer --bin dependency-installer -- check |
30 | 19 |
|
31 | | -### Batch Installation |
| 20 | +# List all available dependencies |
| 21 | +cargo run -p torrust-dependency-installer --bin dependency-installer -- list |
32 | 22 |
|
33 | | -```bash |
34 | | -# Install all core tools |
35 | | -./scripts/setup/install-opentofu.sh |
36 | | -./scripts/setup/install-ansible.sh |
| 23 | +# Install specific dependency |
| 24 | +cargo run -p torrust-dependency-installer --bin dependency-installer -- install --dependency opentofu |
37 | 25 |
|
38 | | -# Install container provider |
39 | | -./scripts/setup/install-lxd-ci.sh |
| 26 | +# See all options |
| 27 | +cargo run -p torrust-dependency-installer --bin dependency-installer -- --help |
40 | 28 | ``` |
41 | 29 |
|
42 | | -## CI vs Local Development |
43 | | - |
44 | | -### CI Environment Detection |
45 | | - |
46 | | -The scripts automatically detect CI environments and apply appropriate configurations: |
| 30 | +### Benefits of the New Approach |
47 | 31 |
|
48 | | -- **CI Detection**: Checks for `CI=true`, `GITHUB_ACTIONS=true`, or `RUNNER_USER` environment variables |
49 | | -- **CI Optimizations**: Uses `sudo` commands and socket permission fixes |
50 | | -- **Logging**: Provides clear feedback about environment detection |
| 32 | +- **Type-safe**: Rust's type system catches errors at compile time |
| 33 | +- **Better error handling**: Clear, actionable error messages |
| 34 | +- **Consistent logging**: Structured logging via `tracing` crate |
| 35 | +- **Testable**: Unit and integration tests ensure reliability |
| 36 | +- **Maintainable**: Single codebase for all dependency management |
| 37 | +- **Cross-platform ready**: Foundation for supporting multiple platforms |
51 | 38 |
|
52 | | -### Local Development |
53 | | - |
54 | | -For local development, see the dedicated documentation: |
55 | | - |
56 | | -- **LXD**: [templates/tofu/lxd/README.md](../../templates/tofu/lxd/README.md) |
57 | | -- **LXD Tech Stack**: [docs/tech-stack/lxd.md](../../docs/tech-stack/lxd.md) |
| 39 | +### Supported Dependencies |
58 | 40 |
|
59 | | -**Important**: The CI scripts use `sudo` commands and socket permission modifications that are **NOT recommended** for local development. Use proper group membership for local setups. |
| 41 | +The dependency installer supports: |
60 | 42 |
|
61 | | -## Script Features |
| 43 | +- **cargo-machete** - Detects unused Rust dependencies |
| 44 | +- **OpenTofu** - Infrastructure provisioning tool (Terraform alternative) |
| 45 | +- **Ansible** - Configuration management and automation platform |
| 46 | +- **LXD** - Lightweight VM manager for container-based testing |
62 | 47 |
|
63 | | -### Common Features |
| 48 | +### Documentation |
64 | 49 |
|
65 | | -- **Idempotent**: Safe to run multiple times |
66 | | -- **Verbose Logging**: Clear progress indicators with colored output |
67 | | -- **Error Handling**: Proper error checking and meaningful messages |
68 | | -- **Version Detection**: Skips installation if tool is already installed |
| 50 | +For complete documentation on the dependency installer, see: |
69 | 51 |
|
70 | | -### Error Handling |
71 | | - |
72 | | -All scripts use `set -euo pipefail` for strict error handling: |
| 52 | +- **Package README**: [packages/dependency-installer/README.md](../../packages/dependency-installer/README.md) |
| 53 | +- **LXD Setup**: [templates/tofu/lxd/README.md](../../templates/tofu/lxd/README.md) |
| 54 | +- **LXD Tech Stack**: [docs/tech-stack/lxd.md](../../docs/tech-stack/lxd.md) |
73 | 55 |
|
74 | | -- **`-e`**: Exit on any command failure |
75 | | -- **`-u`**: Exit on undefined variable usage |
76 | | -- **`-o pipefail`**: Exit on pipe command failures |
| 56 | +### CI/CD Integration |
77 | 57 |
|
78 | | -### Logging Levels |
| 58 | +GitHub Actions workflows now use the dependency installer: |
79 | 59 |
|
80 | | -- **🟢 INFO**: Normal progress messages |
81 | | -- **🟡 WARN**: Important notices or CI-specific actions |
82 | | -- **🔴 ERROR**: Failure messages |
| 60 | +- **`.github/workflows/test-e2e-provision.yml`** - E2E provision and destroy tests |
| 61 | +- **`.github/workflows/test-e2e-config.yml`** - E2E configuration tests |
| 62 | +- **`.github/workflows/test-lxd-provision.yml`** - LXD provisioning tests |
83 | 63 |
|
84 | | -## Integration with Workflows |
| 64 | +Example workflow step: |
85 | 65 |
|
86 | | -These scripts replace duplicated installation code in GitHub Actions workflows: |
| 66 | +```yaml |
| 67 | +- name: Install dependencies |
| 68 | + run: | |
| 69 | + cargo build -p torrust-dependency-installer --bin dependency-installer |
| 70 | + cargo run -p torrust-dependency-installer --bin dependency-installer -- install |
| 71 | +``` |
87 | 72 |
|
88 | | -- **`.github/workflows/test-e2e.yml`** |
89 | | -- **`.github/workflows/test-lxd-provision.yml`** |
| 73 | +### Local Development |
90 | 74 |
|
91 | | -## Troubleshooting |
| 75 | +For local development, the dependency installer automatically handles: |
92 | 76 |
|
93 | | -### Permission Issues |
| 77 | +- **CI Detection**: Automatically applies CI-specific configurations when needed |
| 78 | +- **Permissions**: Proper handling of LXD socket permissions |
| 79 | +- **Group Membership**: Sets up appropriate user groups |
94 | 80 |
|
95 | | -If you encounter permission errors: |
| 81 | +**Important**: For local LXD development, follow the proper group membership approach documented in the tech stack guides. |
96 | 82 |
|
97 | | -1. **For CI**: Scripts should handle permissions automatically |
98 | | -2. **For Local**: Follow the group membership setup in the tech stack documentation |
| 83 | +### Troubleshooting |
99 | 84 |
|
100 | | -### Installation Failures |
| 85 | +If you encounter issues with the dependency installer: |
101 | 86 |
|
102 | | -1. Check internet connectivity for download-based installations |
103 | | -2. Verify system requirements (Ubuntu/Debian for apt-based installs) |
104 | | -3. Check available disk space |
105 | | -4. Review script output for specific error messages |
| 87 | +1. **Check installation status**: `cargo run -p torrust-dependency-installer --bin dependency-installer -- check` |
| 88 | +2. **Enable debug logging**: Add `--verbose` flag or `--log-level debug` |
| 89 | +3. **View available dependencies**: `cargo run -p torrust-dependency-installer --bin dependency-installer -- list` |
| 90 | +4. **Check exit codes**: Exit code 0 = success, non-zero = failure |
106 | 91 |
|
107 | | -### Tool-Specific Issues |
| 92 | +For detailed troubleshooting, see the [dependency installer README](../../packages/dependency-installer/README.md). |
108 | 93 |
|
109 | | -- **OpenTofu**: Requires `curl` and package management tools |
110 | | -- **Ansible**: Requires Python and pip (usually pre-installed) |
111 | | -- **LXD**: Requires snap and sufficient privileges |
| 94 | +### Migration Timeline |
112 | 95 |
|
113 | | -## Future Enhancements |
| 96 | +- **Created**: Issue #113 (Create Dependency Installation Package) |
| 97 | +- **Migrated**: Issue #119 (Update CI Workflows and Remove Bash Scripts) |
| 98 | +- **Removed bash scripts**: November 2025 |
114 | 99 |
|
115 | | -These bash scripts are designed to be simple and maintainable. For more complex installation logic, they may be replaced by Rust utilities in the future while maintaining the same interface. |
| 100 | +This directory is preserved for documentation purposes and may be removed in future versions. |
0 commit comments