Skip to content
This repository was archived by the owner on Oct 10, 2025. It is now read-only.

Commit d140fd1

Browse files
josecelanojosecelano
committed
refactor: [#28] reorganize guides with providers structure
- Create docs/guides/providers/ directory for cloud provider-specific guides - Move Hetzner guides to docs/guides/providers/hetzner/: * hetzner-cloud-setup-guide.md -> providers/hetzner/ * hetzner-dns-setup-guide.md -> providers/hetzner/ - Add comprehensive README files: * docs/guides/README.md - Complete guides overview and navigation * docs/guides/providers/README.md - Multi-provider architecture overview * docs/guides/providers/hetzner/README.md - Hetzner integration guide - Fix relative links in moved files to maintain documentation integrity - Prepare structure for future cloud providers (AWS, DigitalOcean, Vultr) This reorganization improves documentation scalability and provides clear navigation paths for users deploying to different cloud providers.
1 parent cecc6f2 commit d140fd1

File tree

5 files changed

+522
-3
lines changed

5 files changed

+522
-3
lines changed

‎docs/guides/README.md‎

Lines changed: 184 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,184 @@
1+
# User Guides Documentation
2+
3+
This directory contains comprehensive guides for deploying, configuring, and testing
4+
the Torrust Tracker Demo across different environments and use cases.
5+
6+
## 📁 Directory Structure
7+
8+
```text
9+
guides/
10+
├── README.md # This file - guides overview
11+
├── providers/ # Provider-specific deployment guides
12+
│ ├── README.md # Providers overview
13+
│ └── hetzner/ # Hetzner Cloud + DNS guides
14+
│ ├── README.md # Hetzner integration overview
15+
│ ├── hetzner-cloud-setup-guide.md # Hetzner Cloud server setup
16+
│ └── hetzner-dns-setup-guide.md # Hetzner DNS configuration
17+
├── cloud-deployment-guide.md # General cloud deployment guide
18+
├── dns-setup-for-testing.md # DNS configuration for testing
19+
├── grafana-setup-guide.md # Grafana monitoring setup
20+
├── grafana-subdomain-setup.md # Grafana subdomain configuration
21+
├── integration-testing-guide.md # Full infrastructure testing
22+
├── smoke-testing-guide.md # Quick functionality validation
23+
├── ssl-testing-guide.md # SSL certificate testing
24+
└── database-backup-testing-guide.md # Database backup procedures
25+
```
26+
27+
## 🎯 Quick Navigation
28+
29+
### 🚀 Getting Started
30+
31+
| Guide | Description | Time | Use Case |
32+
| --------------------------------------------------------- | ------------------------ | ------ | ---------------- |
33+
| [Cloud Deployment Guide](cloud-deployment-guide.md) | General cloud deployment | 30 min | First deployment |
34+
| [Integration Testing Guide](integration-testing-guide.md) | Complete testing setup | 15 min | Development |
35+
| [Smoke Testing Guide](smoke-testing-guide.md) | Quick validation | 5 min | Post-deployment |
36+
37+
### ☁️ Cloud Providers
38+
39+
| Provider | Documentation | Status |
40+
| ------------ | ------------------------------------ | ------------------ |
41+
| **Hetzner** | [Provider Guide](providers/hetzner/) | ✅ Fully Supported |
42+
| AWS | _Coming Soon_ | 🚧 Planned |
43+
| DigitalOcean | _Coming Soon_ | 🚧 Planned |
44+
| Vultr | _Coming Soon_ | 🚧 Planned |
45+
46+
### 🔧 Configuration & Setup
47+
48+
| Guide | Description | Complexity |
49+
| ----------------------------------------------------- | -------------------------- | ------------ |
50+
| [DNS Setup for Testing](dns-setup-for-testing.md) | General DNS configuration | Beginner |
51+
| [Grafana Setup Guide](grafana-setup-guide.md) | Monitoring dashboard setup | Intermediate |
52+
| [Grafana Subdomain Setup](grafana-subdomain-setup.md) | Subdomain configuration | Intermediate |
53+
| [SSL Testing Guide](ssl-testing-guide.md) | Certificate configuration | Advanced |
54+
55+
### 🧪 Testing & Validation
56+
57+
| Guide | Description | Time | Scope |
58+
| ----------------------------------------------------------- | ------------------------- | --------- | ------------------- |
59+
| [Integration Testing Guide](integration-testing-guide.md) | Full infrastructure test | 10-15 min | Complete deployment |
60+
| [Smoke Testing Guide](smoke-testing-guide.md) | Quick functionality check | 3-5 min | Core features only |
61+
| [Database Backup Testing](database-backup-testing-guide.md) | Backup validation | 5-10 min | Data persistence |
62+
63+
## 🎨 Guide Categories
64+
65+
### Deployment Guides
66+
67+
**Purpose**: Step-by-step instructions for deploying the Torrust Tracker Demo
68+
69+
- **Cloud Deployment**: General cloud deployment procedures
70+
- **Provider-Specific**: Detailed guides for specific cloud providers
71+
- **Local Testing**: Development environment setup
72+
73+
### Configuration Guides
74+
75+
**Purpose**: Detailed configuration for specific components and features
76+
77+
- **DNS Management**: Domain and subdomain configuration
78+
- **SSL Certificates**: HTTPS and certificate management
79+
- **Monitoring**: Grafana and Prometheus setup
80+
- **Database**: MySQL configuration and backups
81+
82+
### Testing Guides
83+
84+
**Purpose**: Validation and testing procedures for different scenarios
85+
86+
- **Integration Testing**: Complete infrastructure validation
87+
- **Smoke Testing**: Quick functional validation
88+
- **Component Testing**: Specific service validation
89+
90+
## 🚀 Recommended Workflow
91+
92+
### For New Users
93+
94+
1. **Start Here**: [Cloud Deployment Guide](cloud-deployment-guide.md)
95+
2. **Choose Provider**: [Providers Directory](providers/)
96+
3. **Validate**: [Smoke Testing Guide](smoke-testing-guide.md)
97+
4. **Monitor**: [Grafana Setup Guide](grafana-setup-guide.md)
98+
99+
### For Developers
100+
101+
1. **Local Setup**: [Integration Testing Guide](integration-testing-guide.md)
102+
2. **Provider Testing**: [Provider-Specific Guides](providers/)
103+
3. **Component Validation**: [Individual Component Guides](#-configuration--setup)
104+
4. **Full Validation**: [Testing Guides](#-testing--validation)
105+
106+
### For Operators
107+
108+
1. **Production Deployment**: [Provider Guides](providers/)
109+
2. **Monitoring Setup**: [Grafana Guides](#-configuration--setup)
110+
3. **Backup Procedures**: [Database Backup Guide](database-backup-testing-guide.md)
111+
4. **SSL Management**: [SSL Testing Guide](ssl-testing-guide.md)
112+
113+
## 📖 Contributing to Guides
114+
115+
### Writing New Guides
116+
117+
When creating new guides:
118+
119+
1. **Follow the structure**: Use consistent formatting and sections
120+
2. **Include prerequisites**: List required tools and setup
121+
3. **Provide examples**: Include command examples and expected output
122+
4. **Add troubleshooting**: Common issues and solutions
123+
5. **Test thoroughly**: Validate all commands and procedures
124+
125+
### Guide Template
126+
127+
```markdown
128+
# Guide Title
129+
130+
Brief description of what this guide covers and when to use it.
131+
132+
## Prerequisites
133+
134+
- Required tools and setup
135+
- Previous guides or knowledge needed
136+
137+
## Step-by-Step Instructions
138+
139+
### Step 1: Clear Action Title
140+
141+
Description and commands...
142+
143+
### Step 2: Next Action
144+
145+
Description and commands...
146+
147+
## Validation
148+
149+
How to verify the guide worked correctly.
150+
151+
## Troubleshooting
152+
153+
Common issues and solutions.
154+
155+
## Related Documentation
156+
157+
Links to other relevant guides.
158+
```
159+
160+
### Provider-Specific Guides
161+
162+
For new cloud provider support:
163+
164+
1. **Create provider directory**: `providers/{provider-name}/`
165+
2. **Add provider README**: Overview of provider integration
166+
3. **Create setup guides**: Infrastructure and DNS setup
167+
4. **Update main documentation**: Add to providers list
168+
5. **Test thoroughly**: Validate with actual provider resources
169+
170+
## 🔗 External Resources
171+
172+
### General Cloud Documentation
173+
174+
- [The Twelve-Factor App](https://12factor.net/) - Application deployment methodology
175+
- [Infrastructure as Code Guide](https://en.wikipedia.org/wiki/Infrastructure_as_code)
176+
- [OpenTofu Documentation](https://opentofu.org/docs/)
177+
178+
### Testing Resources
179+
180+
- [Testing Strategies for Infrastructure](https://martinfowler.com/articles/testing-infrastructure.html)
181+
- [End-to-End Testing Best Practices](https://martinfowler.com/articles/practical-test-pyramid.html)
182+
183+
This guide documentation provides comprehensive coverage for deploying and managing
184+
the Torrust Tracker Demo across different environments and use cases.

‎docs/guides/providers/README.md‎

Lines changed: 82 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,82 @@
1+
# Cloud Providers Documentation
2+
3+
This directory contains provider-specific guides for deploying the Torrust Tracker
4+
Demo on different cloud platforms and infrastructure providers.
5+
6+
## 📁 Directory Structure
7+
8+
```text
9+
providers/
10+
├── README.md # This file - providers overview
11+
└── hetzner/ # Hetzner-specific guides
12+
├── README.md # Hetzner services overview
13+
├── hetzner-cloud-setup-guide.md # Hetzner Cloud server setup
14+
└── hetzner-dns-setup-guide.md # Hetzner DNS configuration
15+
```
16+
17+
## 🏗️ Available Providers
18+
19+
### ✅ Hetzner (Current)
20+
21+
**Services**: Hetzner Cloud + Hetzner DNS
22+
**Status**: Fully implemented and documented
23+
**Location**: [`hetzner/`](hetzner/)
24+
25+
**Features**:
26+
27+
- VM provisioning with Hetzner Cloud
28+
- DNS management with Hetzner DNS API
29+
- Infrastructure as Code with OpenTofu
30+
- Automated SSL certificate generation
31+
- Complete deployment automation
32+
33+
### 🚧 Future Providers (Planned)
34+
35+
We plan to add support for additional cloud providers in the future:
36+
37+
- **AWS**: EC2 + Route 53
38+
- **DigitalOcean**: Droplets + DNS
39+
- **Vultr**: Compute + DNS
40+
- **Linode**: Compute + DNS
41+
- **Azure**: VMs + DNS
42+
- **Google Cloud**: Compute Engine + Cloud DNS
43+
44+
Each provider will follow the same structure with dedicated setup guides and automation scripts.
45+
46+
## 📖 General Documentation
47+
48+
For provider-agnostic guides, see the main guides directory:
49+
50+
- [Integration Testing Guide](../integration-testing-guide.md) - Testing across all providers
51+
- [Smoke Testing Guide](../smoke-testing-guide.md) - End-to-end validation
52+
- [SSL Testing Guide](../ssl-testing-guide.md) - Certificate validation
53+
54+
## 🎯 Provider Selection Criteria
55+
56+
When choosing a cloud provider for your deployment, consider:
57+
58+
1. **Geographic Location**: Choose a provider with data centers near your users
59+
2. **API Integration**: Providers with comprehensive APIs enable better automation
60+
3. **Cost**: Compare pricing for compute, storage, and bandwidth
61+
4. **Features**: DNS management, load balancers, managed databases
62+
5. **Documentation**: Quality of provider documentation and community support
63+
64+
## 🚀 Getting Started
65+
66+
1. **Choose a provider** from the available options above
67+
2. **Navigate to the provider directory** (e.g., `hetzner/`)
68+
3. **Follow the provider-specific setup guide**
69+
4. **Use the common testing guides** for validation
70+
71+
## 📝 Contributing New Providers
72+
73+
To add support for a new cloud provider:
74+
75+
1. **Create provider directory**: `providers/{provider-name}/`
76+
2. **Add provider README**: Document services and capabilities
77+
3. **Create setup guides**: Follow existing guide structure
78+
4. **Implement automation**: Add OpenTofu/Terraform configurations
79+
5. **Add testing**: Ensure integration with existing test framework
80+
6. **Update documentation**: Add provider to this README
81+
82+
For detailed contribution guidelines, see the main project documentation.

0 commit comments

Comments
 (0)