HotaruBlaze/homelab-opentofu
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

chore: update README

Browse Source
This commit is contained in:
Yuris Cakranegara
2025-06-07 15:21:20 +10:00
parent 0f3d672a11
commit 87bf052d14
4 changed files with 59 additions and 109 deletions
Download Patch File Download Diff File Expand all files Collapse all files

36
README.md
View File

@@ -27,7 +27,7 @@ This OpenTofu configuration manages various self-hosted services primarily as Do
Before you begin, ensure you have the following installed and configured:
* **OpenTofu:** Version `1.6.0` or higher (see `versions.tf`). [Installation Guide](https://opentofu.org/docs/intro/install/)
* **OpenTofu:** Version `1.6.0` or higher. [Installation Guide](https://opentofu.org/docs/intro/install/)
* **Git:** For version control.
* **Docker:** Installed and running on the target host(s) (initially "casa", later on VMs within Proxmox).
* **(Optional) Cloudflare Account:** If using the Cloudflare provider for DNS management or Tunnels. You'll need your Zone ID and an API Token.
@@ -50,12 +50,7 @@ homelab/
├── versions.tf # Root module: OpenTofu & provider version constraints
├── terraform.tfvars.example # Example variables file
│
├── environments/
│ ├── core/ # Core infrastructure (monitoring, globals)
│ ├── network/ # Network infrastructure (Docker networks, Cloudflare)
│ └── services/ # Application services (Docker containers)
│
└── modules/ # Local modules for different components
├── modules/ # Local modules for different components
├── 00-globals/ # Optional: Global data sources/locals
├── 01-networking/
│ ├── docker-network/
@@ -69,6 +64,8 @@ homelab/
├── jellyfin/
├── affine/
└── ... # Other application modules
│
└── services/ # Application services (Docker containers)
```
## Configuration
@@ -82,19 +79,12 @@ homelab/
2. **Provider Configuration:**
Review `providers.tf` and ensure provider configurations are suitable. For providers requiring authentication (like Cloudflare or Proxmox later), API tokens and other sensitive data should be supplied via variables.
3. **Create a `terraform.tfvars` file:**
Copy `terraform.tfvars.example` to `terraform.tfvars`:
3. **Create a `.env` file:**
Copy `.env.example` to `.env`:
```bash
cp terraform.tfvars.example terraform.tfvars
cp .env.example .env
```
**Edit `terraform.tfvars` to set your specific values.** This file is included in `.gitignore` by default if it's expected to contain secrets.
Common variables to configure might include:
* `cloudflare_api_token`
* `cloudflare_zone_id`
* `docker_host_data_path_base` (e.g., `/srv/docker_data` on "casa")
* `domain_name` (e.g., `homelab.yourdomain.com`)
* Specific application settings (ports, image tags, paths for persistent data).
* (Future) Proxmox API details.
**Edit `.env` to set your specific values.** This file is included in `.gitignore` by default as it's expected to contain secrets.
## Usage
@@ -110,18 +100,12 @@ Make sure you are in the root directory of the project (`homelab/`).
This command shows you what OpenTofu will do to reach the desired state defined in your configuration files. Review the plan carefully.
```bash
tofu plan
# To use a specific .tfvars file:
# tofu plan -var-file="terraform.tfvars"
```
3. **Apply Changes:**
This command applies the changes outlined in the plan. You will be prompted for confirmation.
```bash
tofu apply
# To use a specific .tfvars file:
# tofu apply -var-file="terraform.tfvars"
# To auto-approve (use with caution):
# tofu apply -auto-approve -var-file="terraform.tfvars"
```
4. **View Outputs:**
@@ -134,8 +118,6 @@ Make sure you are in the root directory of the project (`homelab/`).
This command will attempt to destroy all resources managed by this OpenTofu configuration.
```bash
tofu destroy
# To use a specific .tfvars file:
# tofu destroy -var-file="terraform.tfvars"
```
## Module Overview
@@ -143,7 +125,7 @@ Make sure you are in the root directory of the project (`homelab/`).
This project aims for a high degree of modularity:
* **`modules/01-networking/`**: Contains modules for creating Docker networks, managing Cloudflare DNS records, and deploying `cloudflared` tunnels.
* **`modules/10-services-generic/docker-service/`**: A reusable module to deploy any generic Docker container with common configurations (ports, volumes, environment variables, etc.).
* **`modules/10-services-generic/`**: A reusable module to deploy any generic module with common configurations (Docker container setup, etc.).
* **`modules/20-services-apps/`**: Contains "wrapper" modules for specific applications (e.g., Jellyfin, Affine, Nginx Proxy Manager). These modules typically call the generic `docker-service` module with pre-filled defaults and simpler inputs specific to that application.
* **`modules/02-compute/`**: (Planned for future Proxmox integration) Will contain modules for provisioning Virtual Machines or LXC containers on Proxmox VE, which can then serve as hosts for Docker or other services.

62
modules/01-networking/cloudflared-tunnel/README.md
View File

@@ -39,15 +39,19 @@ module "homelab_tunnel" {
container_name = "cloudflared-homelab"
ingress_rules = [
{
hostname = "budget.example.com"
service = "http://actualbudget:5006"
},
{
hostname = "dashboard.example.com"
service = "http://homepage:3000"
}
]
service_definitions = [
{
name = "homepage"
subdomains = ["dashboard"]
endpoint = "http://homepage:3000"
}
]
}
```
@@ -58,11 +62,6 @@ For cleaner code organization, use the globals module:
```hcl
module "cloudflare_globals" {
source = "./modules/00-globals/cloudflare"
cloudflare_api_token = var.cloudflare_api_token
cloudflare_account_id = var.cloudflare_account_id
cloudflare_zone_id = var.cloudflare_zone_id
domain = "example.com"
}
module "homelab_tunnel" {
@@ -70,9 +69,7 @@ module "homelab_tunnel" {
cloudflare_account_id = module.cloudflare_globals.cloudflare_account_id
cloudflare_zone_id = module.cloudflare_globals.cloudflare_zone_id
tunnel_name = "homelab-tunnel"
ingress_rules = [
{
hostname = "budget.${module.cloudflare_globals.domain}"
@@ -84,16 +81,17 @@ module "homelab_tunnel" {
## Variables
| Name | Description | Type | Default |
|------|-------------|------|---------|
| `cloudflare_account_id` | Cloudflare account ID | string | (required) |
| `cloudflare_zone_id` | Cloudflare zone ID for your domain | string | (required) |
| `container_name` | Name of the Cloudflare tunnel container | string | "" (defaults to "cloudflared-{tunnel_name}") |
| `image_tag` | Docker image tag for cloudflared | string | "latest" |
| `tunnel_name` | Name of the tunnel | string | (required) |
| `tunnel_secret` | Secret for the tunnel | string | "" (auto-generated if empty) |
| `ingress_rules` | List of ingress rules | list(object) | (required) |
| `monitoring` | Enable monitoring via Watchtower | bool | true |
| Name | Description | Type | Default |
| ----------------------- | --------------------------------------- | ------------ | -------------------------------------------- |
| `cloudflare_account_id` | Cloudflare account ID | string | (required) |
| `cloudflare_zone_id` | Cloudflare zone ID for your domain | string | (required) |
| `container_name` | Name of the Cloudflare tunnel container | string | "" (defaults to "cloudflared-{tunnel_name}") |
| `image_tag` | Docker image tag for cloudflared | string | "latest" |
| `tunnel_name` | Name of the tunnel | string | (required) |
| `tunnel_secret` | Secret for the tunnel | string | "" (auto-generated if empty) |
| `ingress_rules` | List of ingress rules | list(object) | (optional) |
| `service_definitions` | List of service definitions. Tunnel will create DNS records for each service with a subdomain. | list(object) | (optional) |
| `monitoring` | Enable monitoring via Watchtower | bool | true |
### Ingress Rules Object Structure
@@ -110,14 +108,14 @@ ingress_rules = [
## Outputs
| Name | Description |
|------|-------------|
| `tunnel_id` | ID of the created tunnel |
| `tunnel_name` | Name of the tunnel |
| `tunnel_token` | Token for the tunnel (sensitive) |
| `cname_target` | CNAME target for the tunnel |
| `dns_records` | Map of created DNS records |
| `container_name` | Name of the cloudflared container |
| `container_id` | ID of the cloudflared container |
| `image_id` | ID of the cloudflared image |
| `ip_address` | IP address of the cloudflared container |
| Name | Description |
| ---------------- | --------------------------------------- |
| `tunnel_id` | ID of the created tunnel |
| `tunnel_name` | Name of the tunnel |
| `tunnel_token` | Token for the tunnel (sensitive) |
| `cname_target` | CNAME target for the tunnel |
| `dns_records` | Map of created DNS records |
| `container_name` | Name of the cloudflared container |
| `container_id` | ID of the cloudflared container |
| `image_id` | ID of the cloudflared image |
| `ip_address` | IP address of the cloudflared container |

17
modules/10-services-generic/docker-service/README.md
View File

@@ -69,6 +69,9 @@ terraform {
docker = {
source = "kreuzwerker/docker"
}
dotenv = {
source = "germanbrew/dotenv"
}
}
}
```
@@ -79,10 +82,10 @@ See the `variables.tf` file for a complete list of input variables and their des
## Outputs
| Name | Description |
|------|-------------|
| container_name | Name of the Docker container |
| container_id | ID of the Docker container |
| image_id | ID of the Docker image |
| ip_address | IP address of the container (if applicable) |
| container_ports | Published ports of the container |
| Name | Description |
| --------------- | ------------------------------------------- |
| container_name | Name of the Docker container |
| container_id | ID of the Docker container |
| image_id | ID of the Docker image |
| ip_address | IP address of the container (if applicable) |
| container_ports | Published ports of the container |

33
modules/20-services-apps/watchtower/README.md
View File

@@ -10,39 +10,6 @@ This module deploys a Watchtower container which automatically updates your runn
- Notification support via shoutrrr
- Container monitoring options
## Usage
To use this module in your root module, add the following code:
```hcl
module "watchtower" {
source = "./modules/20-services-apps/watchtower"
# Basic configuration
container_name = "watchtower"
image_tag = "latest"
timezone = "Australia/Sydney"
# Update settings
poll_interval = 86400 # Check once per day (in seconds)
cleanup = true # Remove old images after updating
rolling_restart = true # Update containers one by one
# Optional notification settings
enable_notifications = false
# notification_url = "discord://webhook-id/webhook-token"
# Additional settings as needed
# additional_env_vars = {
# WATCHTOWER_MONITOR_ONLY = "true"
# }
}
```
## Required Resources
This module leverages the generic `docker-service` module, which handles the Docker container deployment.
## Input Variables
| Name | Description | Type | Default |