This project uses OpenTofu to manage the infrastructure for my personal homelab. It's designed to be modular and evolve, initially focusing on deploying Dockerized applications on a Debian server ("casa") and later expanding to include Proxmox VE for virtualization.

Current Time: June 5, 2025

Overview
Prerequisites
Project Structure
Configuration
Usage
Module Overview
Future Plans

Overview

This OpenTofu configuration manages various self-hosted services primarily as Docker containers. The goals are:

Reproducibility: Easily set up or replicate the homelab environment.
Version Control: Track all infrastructure changes using Git.
Automation: Automate the provisioning and management of services.
Modularity: Organize infrastructure into reusable and understandable components.

Prerequisites

Before you begin, ensure you have the following installed and configured:

OpenTofu: Version 1.6.0 or higher (see versions.tf). Installation Guide
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.
(Future) Proxmox VE: When moving to the virtualization phase, a Proxmox VE host will be required.
(Optional) Tailscale: For secure remote access.

Project Structure

The project is organized as follows:

homelab/
├── .gitignore                # Files and directories to ignore
├── README.md                 # This file
│
├── main.tf                   # Root module: orchestrates module calls
├── variables.tf              # Root module: global input variables
├── outputs.tf                # Root module: global outputs
├── providers.tf              # Root module: provider configurations
├── 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
    ├── 00-globals/           # Optional: Global data sources/locals
    ├── 01-networking/
    │   ├── docker-network/
    │   ├── cloudflare-dns-record/
    │   └── cloudflared-tunnel/
    ├── 02-compute/           # Future: Proxmox VM/LXC modules
    │   └── proxmox-vm/
    ├── 10-services-generic/
    │   └── docker-service/   # Generic module for deploying Docker containers
    └── 20-services-apps/     # Application-specific wrapper modules
        ├── jellyfin/
        ├── affine/
        └── ...               # Other application modules

Configuration

Clone the repository:

git clone https://github.com/yurisasc/homelab.git
cd homelab

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.
Create a terraform.tfvars file: Copy terraform.tfvars.example to terraform.tfvars:
```
cp terraform.tfvars.example terraform.tfvars
```
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.

Usage

Make sure you are in the root directory of the project (homelab/).

Initialize OpenTofu: This downloads the necessary provider plugins. Run this once when you first set up the project or when you add/change providers or modules.
```
tofu init
```
Plan Changes: This command shows you what OpenTofu will do to reach the desired state defined in your configuration files. Review the plan carefully.
```
tofu plan
# To use a specific .tfvars file:
# tofu plan -var-file="terraform.tfvars"
```

Apply Changes: This command applies the changes outlined in the plan. You will be prompted for confirmation.

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"

View Outputs: If you have defined outputs in outputs.tf or in your modules, you can view them:
```
tofu output
```
Destroy Infrastructure (Use with Extreme Caution!): This command will attempt to destroy all resources managed by this OpenTofu configuration.
```
tofu destroy
# To use a specific .tfvars file:
# tofu destroy -var-file="terraform.tfvars"
```

Module Overview

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/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.

Each module should have its own README.md (eventually) detailing its purpose, inputs, and outputs.

Future Plans

Phase 1 (Current): Codify all existing Dockerized services running on the primary Debian server ("casa") using OpenTofu.
Phase 2: Set up a new machine with Proxmox VE.
Phase 3: Adapt and expand these OpenTofu configurations to:
- Provision VMs on Proxmox (e.g., a dedicated Docker host VM).
- Deploy the Dockerized services (from Phase 1) inside these VMs using OpenTofu.
- Potentially manage LXC containers on Proxmox for suitable services.

README.md

My OpenTofu Homelab Infrastructure

Table of Contents