Homelab Project: Setting Up Your Foundation

by SLV Team 44 views
Homelab Project: Setting Up Your Foundation

Hey guys! Let's get this homelab project rolling! This guide is all about setting up the initial directory structure and skeleton files. This is like laying the foundation for a house; we need to get this right before we start building anything fancy. Follow along, and you'll have a solid base to start your homelab adventure. Let's dive in!

1. Setting the Stage: Project Objective and Goals

First off, let's talk about what we're trying to achieve here. Our primary goal is to establish a well-organized directory structure that will house all the components of our homelab. We're talking about things like the Terraform configurations, Kubernetes deployments, handy scripts, documentation, and the all-important .github directory for our workflows. This structure will help us manage our project effectively. Think of it as creating a digital filing cabinet for all the moving parts of our homelab. Each directory has a specific purpose, and keeping everything organized from the get-go will save us a lot of headaches down the road. This also involves the creation of essential files like Makefile, .gitignore, and the README.md file. These will help us automate tasks, exclude unnecessary files from our repository, and provide documentation for the project.

Why is this important?

Creating a good directory structure is really important. It helps in: Organization: Makes it easier to find things. Collaboration: Makes it easier for others (or yourself in the future) to understand the project. Automation: Makes it easier to automate tasks. Scalability: Makes it easier to add more components later.

The initial plan

The plan here is to set up a logical and functional structure. This makes it easier to manage the project. This structured approach helps in organizing different components of your homelab, like infrastructure code using Terraform, Kubernetes configurations, and supporting scripts. This is the critical first step, so let's jump right in.

2. Directory Structure Deep Dive: Unveiling the Blueprint

Let's go through the directory structure in detail. We'll build a directory to hold all our infrastructure-as-code files. We'll be using Terraform, to manage all our resources. Then we'll build a kubernetes directory for our Kubernetes cluster, with subdirectories for bootstrap configurations and application deployments. This will house all our YAML files, deployment configurations, and other Kubernetes-related files. We'll also create directories for our scripts, documentation, and GitHub workflows. Finally, we'll need a .gitignore file to prevent our files from tracking unnecessary files and the README.md file to give a basic description of the project.

homelab/
β”œβ”€β”€ notes/                      βœ… (already exists)
β”œβ”€β”€ terraform/                  ← Create this
β”‚   β”œβ”€β”€ modules/
β”‚   β”‚   β”œβ”€β”€ proxmox-vm/
β”‚   β”‚   β”œβ”€β”€ k3s-cluster/
β”‚   β”‚   └── vault-init/
β”‚   β”œβ”€β”€ main.tf
β”‚   β”œβ”€β”€ variables.tf
β”‚   β”œβ”€β”€ outputs.tf
β”‚   └── terraform.tfvars       (gitignored)
β”œβ”€β”€ kubernetes/                 ← Create this
β”‚   β”œβ”€β”€ bootstrap/
β”‚   β”‚   β”œβ”€β”€ vault/
β”‚   β”‚   β”œβ”€β”€ cert-manager/
β”‚   β”‚   └── argocd/
β”‚   └── apps/
β”œβ”€β”€ scripts/                    ← Create this
β”œβ”€β”€ docs/                       ← Create this
β”œβ”€β”€ .github/                    ← Create this
β”‚   └── workflows/
β”œβ”€β”€ Makefile                    ← Create this
β”œβ”€β”€ .gitignore                  ← Create this
└── README.md                   βœ… (already exists)

Breaking it down

  • terraform/: This directory will contain all of our Terraform configuration files. Within this, we'll have a modules directory to organize reusable Terraform modules (like for creating VMs, setting up K3s, and initializing Vault). We'll also have the main configuration files (main.tf, variables.tf, outputs.tf) and a terraform.tfvars file (which will be git-ignored) to store our sensitive variables.
  • kubernetes/: This is where all things Kubernetes will live. It will have a bootstrap directory for the initial setup of our cluster (things like Vault, Cert-Manager, and ArgoCD) and an apps directory for deploying applications.
  • scripts/: This directory will be for any useful scripts we need. This could be anything from automation tasks to custom tools.
  • docs/: This is for our documentation. It is always a good practice to keep your documents well.
  • .github/: This is where our GitHub Actions workflows will live, which we'll use for CI/CD and automation.
  • Makefile: This file will contain commands to automate common tasks like initializing Terraform, planning, applying changes, and destroying infrastructure.
  • .gitignore: This file will specify files and directories that Git should ignore, like Terraform state files, secrets, and IDE-specific files.
  • README.md: This will be our project's main documentation file, providing an overview of the project, how to get started, and links to other documentation.

3. Hands-on: Building the Homelab Structure

Alright, guys, let's get our hands dirty and create the directories and files! First, we will create the main directories. Navigate to your homelab project directory and use the mkdir command to create the directories in the structure. This is a crucial step in ensuring that everything is organized.

cd ~/8do/homelab

# Create main directories
mkdir -p terraform/modules/{proxmox-vm,k3s-cluster,vault-init}
mkdir -p kubernetes/{bootstrap/{vault,cert-manager,argocd},apps}
mkdir -p scripts docs .github/workflows

Creating Terraform Skeleton Files

After we create the main directories, let's set up the basic Terraform files. We will start with a basic main.tf file that configures the Terraform provider. Then, we will create variables.tf, which holds our variables that we'll customize. We will then create an outputs.tf file to display outputs from the Terraform runs. Finally, we will create a terraform.tfvars.example file to store example values.

cd terraform

# Create main.tf
cat > main.tf << 'TFEOF'
terraform {
  required_version = ">= 1.5"

  required_providers {
    proxmox = {
      source  = "telmate/proxmox"
      version = "~> 2.9"
    }
  }
}

provider "proxmox" {
  pm_api_url          = var.proxmox_api_url
  pm_api_token_id     = var.proxmox_token_id
  pm_api_token_secret = var.proxmox_token_secret
  pm_tls_insecure     = true
}
TFEOF

# Create variables.tf
cat > variables.tf << 'TFEOF'
variable "proxmox_api_url" {
  description = "Proxmox API URL"
  type        = string
}

variable "proxmox_token_id" {
  description = "Proxmox API Token ID"
  type        = string
  sensitive   = true
}

variable "proxmox_token_secret" {
  description = "Proxmox API Token Secret"
  type        = string
  sensitive   = true
}

variable "proxmox_node" {
  description = "Proxmox node name"
  type        = string
  default     = "pve"
}

variable "storage_pool" {
  description = "Storage pool for VMs"
  type        = string
  default     = "local-lvm"
}
TFEOF

# Create outputs.tf
cat > outputs.tf << 'TFEOF'
# VM outputs will be added here
TFEOF

terraform.tfvars.example Creation

Then, we'll create the terraform.tfvars.example file. This file will contain example values for your Terraform variables. You'll need to update it with your actual values.

cd terraform

cat > terraform.tfvars.example << 'TFEOF'
proxmox_api_url      = "https://YOUR-PROXMOX-IP:8006/api2/json"
proxmox_token_id     = "root@pam!terraform"
proxmox_token_secret = "YOUR-SECRET-HERE"
proxmox_node         = "pve"
storage_pool         = "local-lvm"
TFEOF

# Create actual tfvars (will be gitignored)
# Fill in your actual values after creating API token

Create .gitignore

Next, we will create a .gitignore file. It will tell Git which files and directories to ignore. It is super important to keep sensitive information safe. This is especially true when working with secrets, API keys, and temporary files that shouldn't be tracked in the repository.

cd ~/8do/homelab

cat > .gitignore << 'GITEOF'
# Terraform
*.tfstate
*.tfstate.*
*.tfvars
!*.tfvars.example
.terraform/
.terraform.lock.hcl

# Kubeconfig
kubeconfig
*.kubeconfig

# Secrets
*.pem
*.key
secrets/

# IDE
.vscode/
.idea/
*.swp
*.swo

# OS
.DS_Store
Thumbs.db
GITEOF

Creating the Makefile

Then, let's create our Makefile. A Makefile is a file that contains a set of rules used by the make utility to automate tasks. In our case, the Makefile will automate common Terraform tasks like initialization, planning, and applying changes. It will also include helpful commands to format Terraform files and clean up temporary files.

cd ~/8do/homelab

cat > Makefile << 'MAKEEOF'
.PHONY: help init plan apply destroy clean

.DEFAULT_GOAL := help

help: ## Show this help message
	@echo "homelab - Production K8s Platform"
	@echo ""
	@echo "Available commands:"
	@grep -E '^[a-zA-Z_-]+:.*?## .*$' $(MAKEFILE_LIST) | awk 'BEGIN {FS = ":.*?## "}; {printf "  \033[36m%-15s\033[0m %s\n", $1, $2}'

init: ## Initialize Terraform
	cd terraform && terraform init

validate: ## Validate Terraform configuration
	cd terraform && terraform validate

plan: ## Show Terraform plan
	cd terraform && terraform plan

apply: ## Apply Terraform changes
	cd terraform && terraform apply

destroy: ## Destroy all infrastructure
	cd terraform && terraform destroy

clean: ## Clean up temporary files
	find . -name ".terraform" -type d -exec rm -rf {} +
	find . -name "*.tfstate*" -delete
	find . -name ".terraform.lock.hcl" -delete

fmt: ## Format Terraform files
	cd terraform && terraform fmt -recursive
MAKEEOF

Updating the README

We need to create the README.md file. It's the first thing people see when they visit your project. This will give them a general idea about what your project is about. It'll also have the basic info, like the goal of the project, the technologies used, and basic instructions on how to get started.

cd ~/8do/homelab

cat > README.md << 'READMEEOF'
# Homelab - Production K8s Platform

> Production-ready Kubernetes platform showcasing DevOps best practices

## 🎯 Project Goals

Build a fully automated Kubernetes platform demonstrating:
- **Infrastructure as Code** (Terraform + Proxmox)
- **Zero-Trust Secrets** (HashiCorp Vault + PKI)
- **GitOps Deployment** (ArgoCD)
- **Full Observability** (Prometheus + Grafana + Loki)
- **Production Security** (Network policies, RBAC, OPA)

## πŸ› οΈ Tech Stack

- **Infrastructure**: Proxmox, Terraform
- **Orchestration**: Kubernetes (K3s)
- **Secrets**: HashiCorp Vault
- **GitOps**: ArgoCD
- **Observability**: Prometheus, Grafana, Loki
- **CI/CD**: GitHub Actions

## πŸ“‹ Project Status

🚧 **In Progress** - Starting Nov 1, 2025

See [Project Board](https://github.com/users/8do-abehn/projects/6) for current status.

## πŸš€ Quick Start

```bash
# Initialize Terraform
make init

# Plan infrastructure
make plan

# Deploy
make apply

πŸ“– Documentation

🀝 About

Portfolio project by Adam Behn

Skills demonstrated: Terraform, Vault, Kubernetes, GitOps, Observability, Security

Open to DevOps/SRE opportunities READMEEOF


## 4. Putting it All Together: Verification and Next Steps

Alright, guys, let's make sure everything is in place. After setting up the directory structure and the skeleton files, verify that everything is set up correctly. This verification involves checking the directory structure and the contents of a few files. Make sure that everything is correct.

```bash
cd ~/8do/homelab

# Check directory structure
tree -L 3 -d

# Check Terraform files
ls -la terraform/

# Check Makefile works
make help

Verification

The tree -L 3 -d command will show the directory structure. This is a great way to visually confirm that everything is organized the way we want it. The output will show the directories and the depth.

The ls -la terraform/ command will list the files in the Terraform directory, allowing us to see that the main.tf, variables.tf, and outputs.tf files are present.

Finally, the make help command will display the help information from our Makefile, confirming that the Makefile is working and that all of our commands are available.

Next Steps

Now that the initial structure is in place, the next steps will involve diving deeper into the configuration. For Terraform, this will mean defining the infrastructure resources such as Proxmox VMs, networks, and storage. For Kubernetes, this involves defining our cluster configuration and deploying our workloads.

Final Thoughts

You've successfully created the initial structure. Good job, guys! This is an important step to make sure everything runs smoothly. We now have a solid structure to keep our project organized. In the next steps, we will dive deep into creating the Proxmox VMs, Kubernetes cluster configuration, and everything needed to run your homelab.