first commit
This commit is contained in:
Yuris Cakranegara
163
README.md
Normal file
163
README.md
Normal file
@@ -0,0 +1,163 @@
|
||||
# My OpenTofu Homelab Infrastructure
|
||||
|
||||
This project uses [OpenTofu](https://opentofu.org/) 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
|
||||
|
||||
## Table of Contents
|
||||
|
||||
1. [Overview](#overview)
|
||||
2. [Prerequisites](#prerequisites)
|
||||
3. [Project Structure](#project-structure)
|
||||
4. [Configuration](#configuration)
|
||||
5. [Usage](#usage)
|
||||
6. [Module Overview](#module-overview)
|
||||
7. [Future Plans](#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](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.
|
||||
* **(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
|
||||
|
||||
1. **Clone the repository:**
|
||||
```bash
|
||||
git clone https://github.com/yurisasc/homelab.git
|
||||
cd 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`:
|
||||
```bash
|
||||
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/`).
|
||||
|
||||
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.
|
||||
```bash
|
||||
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.
|
||||
```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:**
|
||||
If you have defined outputs in `outputs.tf` or in your modules, you can view them:
|
||||
```bash
|
||||
tofu output
|
||||
```
|
||||
|
||||
5. **Destroy Infrastructure (Use with Extreme Caution!):**
|
||||
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
|
||||
|
||||
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
|
||||
|
||||
1. **Phase 1 (Current):** Codify all existing Dockerized services running on the primary Debian server ("casa") using OpenTofu.
|
||||
2. **Phase 2:** Set up a new machine with Proxmox VE.
|
||||
3. **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.
|
||||
|
||||
---
|
||||
|
||||
Remember to replace placeholders like `<your-repo-url>` and customize the content based on the specifics of your setup as it evolves.
|
||||
Reference in New Issue
Block a user