homelab-infra/README.md

⚠️ Early development

This project is in early development and not all features are working yet. Use with caution.

homelab-infra

GitOps-managed infrastructure for homelab services using Docker Compose and Traefik for routing.

Overview

This repository manages a homelab setup with multiple self-hosted services. It uses GitOps principles where infrastructure as code is version-controlled, and documentation is automatically generated from configuration files using MkDocs.

Key Features

• GitOps Workflow: All infrastructure configurations are stored in Git
• Automated Documentation: MkDocs site built from actual config files
• Service Management: Makefile for easy service control
• Environment Sync: Pre-commit hooks ensure .env files stay in sync
• Backup Integration: Restic-based backups for data protection

Services

Currently includes: Gitea (Git hosting), Nextcloud (cloud storage), Devbox (development container), Obsidian LiveSync (CouchDB), Traefik (reverse proxy), and Whoami (test service).

Getting Started

1. Clone the repo
2. Copy environment templates: make init-env
3. Edit .env files with your secrets
4. Create Docker networks: docker network create web
5. Start services: make up

Documentation

Full documentation is available at the MkDocs site or build locally with make docs.

Directory Structure

homelab-infra/
├── Makefile              # Service management commands
├── backup.sh             # Restic backup script
├── docs/                 # MkDocs documentation source
├── mkdocs.yml            # MkDocs configuration
├── scripts/              # Utility scripts
└── services/             # Per-service configurations
    └── [service]/
        ├── docker-compose.yml
        ├── .env.example
        └── README.md