homelab/README.md

My OpenTofu homelab infrastructure

This project uses OpenTofu to manage the infrastructure on my private server.

Overview

This OpenTofu configuration manages various self-hosted services primarily as Docker/Podman 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:

• asdf-vm Version 0.18 to install appropriate opentofu.
• OpenTofu: Version 1.10.0 or higher. See .tool-versions for the tested version.
• Git: For version control.
• Docker/Podman: to host containers, I use Podman in my setup.

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
├── modules/                  # Local modules for different components
├───┐
│   ├── 00-globals/           # Optional: Global data sources/locals
│   ├── 01-networking/
│   │   ├── docker-network/
│   ├── 10-generic/
│   │   └── docker-service/   # Generic module for deploying Docker containers
│   └── 20-services-entertainment/     # Application-specific wrapper modules
│       ├── jellyfin/
│       └── ...               # Other application modules
│
└── services/                 # Application services (Docker containers)

Networking structure

Internal Network

For the global network I use the following IP range and Subnet:

• 10.100.0.0 - 10.100.0.254
• 255.255.255.0 (/24)

You will get 253 usable host addresses per network. This network is mainly for connecting pods to Caddy as the external ingress.

Intra pod network

For connecting pods to each other (For example: Postgres -> Project <- Redis ) I use the following IP range and Subnet:

• 172.17.0.0 - 172.17.0.254
• 255.255.255.248 (/29)

You get 6 usable host addresses per internal network, to find the usable addresses you can check here.

Addresses in use:

Network name	IP address range
Authentik	.0 - .7
Pelican	.8 - .15
Coder	.16 - .23
Tandoor	.24 - .31
Penpot	.32 - .39

Configuration

1. Clone the repository:

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

2. Create a .env file: Copy all .env.examples to .env:

   cp .env.example .env
   

   Edit .env to set your specific values. This file is included in .gitignore by default as it's expected to contain secrets.

Usage

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

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

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

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

   tofu apply
   

4. View Outputs: If you have defined outputs in outputs.tf or in your modules, you can view them:

   tofu output
   

5. Destroy Infrastructure (Use with caution!): This command will attempt to destroy all resources managed by this OpenTofu configuration.

   tofu destroy