From 87bf052d14ed4923074fa3fecd598ba0eb3151ec Mon Sep 17 00:00:00 2001 From: Yuris Cakranegara Date: Sat, 7 Jun 2025 15:21:20 +1000 Subject: [PATCH] chore: update README --- README.md | 36 +++------- .../cloudflared-tunnel/README.md | 70 +++++++++---------- .../docker-service/README.md | 29 ++++---- modules/20-services-apps/watchtower/README.md | 33 --------- 4 files changed, 59 insertions(+), 109 deletions(-) diff --git a/README.md b/README.md index a38d796..3262a31 100644 --- a/README.md +++ b/README.md @@ -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. diff --git a/modules/01-networking/cloudflared-tunnel/README.md b/modules/01-networking/cloudflared-tunnel/README.md index 69dd5b7..19eb7ea 100644 --- a/modules/01-networking/cloudflared-tunnel/README.md +++ b/modules/01-networking/cloudflared-tunnel/README.md @@ -31,23 +31,27 @@ Before using this module, you need: ```hcl module "homelab_tunnel" { source = "./modules/01-networking/cloudflared-tunnel" - + cloudflare_account_id = var.cloudflare_account_id cloudflare_zone_id = var.cloudflare_zone_id - + tunnel_name = "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,21 +62,14 @@ 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" { source = "./modules/01-networking/cloudflared-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 | diff --git a/modules/10-services-generic/docker-service/README.md b/modules/10-services-generic/docker-service/README.md index 75c433f..1cf8b35 100644 --- a/modules/10-services-generic/docker-service/README.md +++ b/modules/10-services-generic/docker-service/README.md @@ -22,10 +22,10 @@ module "my_service" { container_name = "my-service" image = "organization/image" tag = "latest" - + restart_policy = "unless-stopped" network_mode = "bridge" - + // Port mappings ports = [ { @@ -34,7 +34,7 @@ module "my_service" { protocol = "tcp" } ] - + // Volume mappings volumes = [ { @@ -43,17 +43,17 @@ module "my_service" { read_only = false } ] - + // Environment variables env_vars = { VARIABLE_NAME = "value" } - + // Container labels labels = { "com.example.description" = "My service description" } - + // Enable Watchtower updates monitoring = true } @@ -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 | diff --git a/modules/20-services-apps/watchtower/README.md b/modules/20-services-apps/watchtower/README.md index c616b7b..891c08c 100644 --- a/modules/20-services-apps/watchtower/README.md +++ b/modules/20-services-apps/watchtower/README.md @@ -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 |