From fb31bcb0a36f94e1b2e10e2112e0750bd449ccbf Mon Sep 17 00:00:00 2001 From: James Thompson <1jamesthompson1@gmail.com> Date: Mon, 23 Mar 2026 04:40:34 +0000 Subject: [PATCH] Move around docs --- README.md | 121 ++++++----------------------- docs/index.md | 96 ++++++++++++++++++++++- docs/services/devbox.md | 2 +- docs/services/gitea.md | 2 +- docs/services/nextcloud.md | 2 +- docs/services/obsidian-livesync.md | 2 +- docs/services/traefik.md | 2 +- docs/services/whoami.md | 2 +- 8 files changed, 126 insertions(+), 103 deletions(-) diff --git a/README.md b/README.md index 46f1000..798df40 100755 --- a/README.md +++ b/README.md @@ -1,117 +1,46 @@ # homelab-infra -GitOps-managed infrastructure for homelab services. +GitOps-managed infrastructure for homelab services using Docker Compose and Traefik for routing. -## Quick Start +## Overview -```bash -git clone git@gitea.sjhl.nz:james/homelab-infra.git -cd homelab-infra +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. -# Set up environment -cp .env.example .env -# Edit .env with real values +### Key Features -# Set up service secrets -for svc in traefik gitea nextcloud qbittorrent jellyfin devbox obsidian; do - [ -f "$svc/.env.example" ] && cp "$svc/.env.example" "$svc/.env" - # Edit each .env with real secrets -done - -# Create required Docker networks -docker network create web - -# Start everything -make up -``` +- **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 -| Service | Description | URL | -|---------|-------------|-----| -| gitea | Self-hosted Git | [gitea.sjhl.nz](https://gitea.sjhl.nz) | -| nextcloud | Cloud storage (AIO) | [nextcloud.sjhl.nz](https://nextcloud.sjhl.nz) | -| devbox | Dev container | Internal only | -| obsidian | CouchDB for Obsidian LiveSync | Internal | +Currently includes: Gitea (Git hosting), Nextcloud (cloud storage), Devbox (development container), Obsidian LiveSync (CouchDB), Traefik (reverse proxy), and Whoami (test service). -## Commands +## Getting Started -```bash -make up # Start all services -make down # Stop all services -make restart # Restart all services -make status # Show status of all services -make logs # Show recent logs -make backup # Run Restic backup -make init-env # Create missing .env files from templates -make env-sync # Rewrite .env files to match templates -make docs # Build MkDocs site -``` +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 -This repo uses **MkDocs** with the **include-markdown** plugin to generate live documentation. - -### How it works: -1. Each service page is auto-generated to include: - - `docker-compose.yml` configuration - - `Dockerfile` (if exists) - - `README.md` (if exists) - - `.env.example` for environment variables - -2. Files are automatically pulled at build time—changes to service files appear in docs immediately - -3. Build docs with: - ```bash - make docs # Generate docs and build site - make serve-docs # Serve docs locally at http://localhost:8000 - ``` - -### Pre-commit Checks - -This repo includes a pre-commit hook that syncs .env.example from .env schema. - -Behavior: -- `.env` defines the schema: keys, structure, comments -- `.env.example` provides defaults and is regenerated from `.env` -- Keys in `.env.example` are kept only if they exist in `.env` -- Default values are preserved from `.env.example` -- New keys from `.env` get `__CHANGEME__` placeholder if not in template - -One-time install: - -```bash -uvx pre-commit install -``` - -Run manually at any time: - -```bash -uvx pre-commit run --all-files -make env-sync -``` - -If files were updated, re-stage and commit again. +Full documentation is available at the [MkDocs site](https://homelab.sjhl.nz) or build locally with `make docs`. ## Directory Structure ``` homelab-infra/ -├── .env.example # Global env template -├── Makefile # Service management +├── Makefile # Service management commands ├── backup.sh # Restic backup script -├── .pre-commit-config.yaml # Pre-commit hooks -├── docs/ # MkDocs documentation -├── mkdocs.yml # MkDocs config -├── scripts/ # Utility scripts -└── [service subdirs]/ # All services have their own subdir - - +├── docs/ # MkDocs documentation source +├── mkdocs.yml # MkDocs configuration +├── scripts/ # Utility scripts +└── [service]/ # Per-service configurations + ├── docker-compose.yml + ├── .env.example + └── README.md ``` - -## Data Locations - -- Configs (in Git): this repo -- Secrets (not in Git): per-service `.env` files -- Persistent data: `/mnt/storage/docker-data/` -- Backups: `/mnt/storage/backups` diff --git a/docs/index.md b/docs/index.md index 2712f28..99c1cc9 100755 --- a/docs/index.md +++ b/docs/index.md @@ -25,8 +25,102 @@ Welcome to Seirian & James' homelab documentation! This is a docs site that is b ## Quick Start ```bash +git clone git@gitea.sjhl.nz:james/homelab-infra.git +cd homelab-infra + +# Set up environment cp .env.example .env -for svc in */; do [ -f "$svc/.env.example" ] && cp "$svc/.env.example" "$svc/.env"; done +# Edit .env with real values + +# Set up service secrets +for svc in traefik gitea nextcloud qbittorrent jellyfin devbox obsidian; do + [ -f "$svc/.env.example" ] && cp "$svc/.env.example" "$svc/.env" + # Edit each .env with real secrets +done + +# Create required Docker networks docker network create web + +# Start everything make up ``` + +## Commands + +```bash +make up # Start all services +make down # Stop all services +make restart # Restart all services +make status # Show status of all services +make logs # Show recent logs +make backup # Run Restic backup +make init-env # Create missing .env files from templates +make env-sync # Rewrite .env files to match templates +make docs # Build MkDocs site +``` + +## Documentation + +This repo uses **MkDocs** with the **include-markdown** plugin to generate live documentation. + +### How it works: +1. Each service page is auto-generated to include: + - `docker-compose.yml` configuration + - `Dockerfile` (if exists) + - `README.md` (if exists) + - `.env.example` for environment variables + +2. Files are automatically pulled at build time—changes to service files appear in docs immediately + +3. Build docs with: + ```bash + make docs # Generate docs and build site + make serve-docs # Serve docs locally at http://localhost:8000 + ``` + +### Pre-commit Checks + +This repo includes a pre-commit hook that syncs .env.example from .env schema. + +Behavior: +- `.env` defines the schema: keys, structure, comments +- `.env.example` provides defaults and is regenerated from `.env` +- Keys in `.env.example` are kept only if they exist in `.env` +- Default values are preserved from `.env.example` +- New keys from `.env` get `__CHANGEME__` placeholder if not in template + +One-time install: + +```bash +uvx pre-commit install +``` + +Run manually at any time: + +```bash +uvx pre-commit run --all-files +make env-sync +``` + +If files were updated, re-stage and commit again. + +## Directory Structure + +``` +homelab-infra/ +├── .env.example # Global env template +├── Makefile # Service management +├── backup.sh # Restic backup script +├── .pre-commit-config.yaml # Pre-commit hooks +├── docs/ # MkDocs documentation +├── mkdocs.yml # MkDocs config +├── scripts/ # Utility scripts +└── [service subdirs]/ # All services have their own subdir +``` + +## Data Locations + +- Configs (in Git): this repo +- Secrets (not in Git): per-service `.env` files +- Persistent data: `/mnt/storage/docker-data/` +- Backups: `/mnt/storage/backups` diff --git a/docs/services/devbox.md b/docs/services/devbox.md index 7c29b44..5ca3732 100755 --- a/docs/services/devbox.md +++ b/docs/services/devbox.md @@ -1,7 +1,7 @@ # devbox -> This page auto-includes the service configuration files. +> Below are the configuration files for this service. For details on how to deploy or customize, refer to the README above or the official documentation for the service. ## Docker Compose Configuration ```yaml diff --git a/docs/services/gitea.md b/docs/services/gitea.md index 23d472b..19ac060 100755 --- a/docs/services/gitea.md +++ b/docs/services/gitea.md @@ -1,7 +1,7 @@ # gitea -> This page auto-includes the service configuration files. +> Below are the configuration files for this service. For details on how to deploy or customize, refer to the README above or the official documentation for the service. ## Docker Compose Configuration ```yaml diff --git a/docs/services/nextcloud.md b/docs/services/nextcloud.md index d581b26..1fecd77 100755 --- a/docs/services/nextcloud.md +++ b/docs/services/nextcloud.md @@ -1,7 +1,7 @@ # nextcloud -> This page auto-includes the service configuration files. +> Below are the configuration files for this service. For details on how to deploy or customize, refer to the README above or the official documentation for the service. ## Docker Compose Configuration ```yaml diff --git a/docs/services/obsidian-livesync.md b/docs/services/obsidian-livesync.md index 02203e7..ad123b7 100755 --- a/docs/services/obsidian-livesync.md +++ b/docs/services/obsidian-livesync.md @@ -1,7 +1,7 @@ # obsidian-livesync -> This page auto-includes the service configuration files. +> Below are the configuration files for this service. For details on how to deploy or customize, refer to the README above or the official documentation for the service. ## Docker Compose Configuration ```yaml diff --git a/docs/services/traefik.md b/docs/services/traefik.md index 0eef96f..1871fbf 100755 --- a/docs/services/traefik.md +++ b/docs/services/traefik.md @@ -1,8 +1,8 @@ # traefik -> This page auto-includes the service configuration files. --8<-- "traefik/README.md" +> Below are the configuration files for this service. For details on how to deploy or customize, refer to the README above or the official documentation for the service. ## Docker Compose Configuration ```yaml diff --git a/docs/services/whoami.md b/docs/services/whoami.md index 7af73f9..2c0c39c 100755 --- a/docs/services/whoami.md +++ b/docs/services/whoami.md @@ -1,7 +1,7 @@ # whoami -> This page auto-includes the service configuration files. +> Below are the configuration files for this service. For details on how to deploy or customize, refer to the README above or the official documentation for the service. ## Docker Compose Configuration ```yaml