james/homelab-infra
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Move around docs

Browse Source
This commit is contained in:
James Thompson
2026-03-23 04:40:34 +00:00
parent 90073c1d7a
commit fb31bcb0a3
8 changed files with 126 additions and 103 deletions
Download Patch File Download Diff File Expand all files Collapse all files

121
README.md
View File

@@ -1,117 +1,46 @@
# homelab-infra # 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 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.
git clone git@gitea.sjhl.nz:james/homelab-infra.git
cd homelab-infra
# Set up environment ### Key Features
cp .env.example .env
# Edit .env with real values
# Set up service secrets - **GitOps Workflow**: All infrastructure configurations are stored in Git
for svc in traefik gitea nextcloud qbittorrent jellyfin devbox obsidian; do - **Automated Documentation**: MkDocs site built from actual config files
[ -f "$svc/.env.example" ] && cp "$svc/.env.example" "$svc/.env" - **Service Management**: Makefile for easy service control
# Edit each .env with real secrets - **Environment Sync**: Pre-commit hooks ensure .env files stay in sync
done - **Backup Integration**: Restic-based backups for data protection
# Create required Docker networks
docker network create web
# Start everything
make up
```
## Services ## Services
| Service | Description | URL | Currently includes: Gitea (Git hosting), Nextcloud (cloud storage), Devbox (development container), Obsidian LiveSync (CouchDB), Traefik (reverse proxy), and Whoami (test service).
|---------|-------------|-----|
| 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 |
## Commands ## Getting Started
```bash 1. Clone the repo
make up # Start all services 2. Copy environment templates: `make init-env`
make down # Stop all services 3. Edit `.env` files with your secrets
make restart # Restart all services 4. Create Docker networks: `docker network create web`
make status # Show status of all services 5. Start services: `make up`
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 ## Documentation
This repo uses **MkDocs** with the **include-markdown** plugin to generate live documentation. Full documentation is available at the [MkDocs site](https://homelab.sjhl.nz) or build locally with `make docs`.
### 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 ## Directory Structure
``` ```
homelab-infra/ homelab-infra/
├── .env.example # Global env template ├── Makefile # Service management commands
├── Makefile # Service management
├── backup.sh # Restic backup script ├── backup.sh # Restic backup script
├── .pre-commit-config.yaml # Pre-commit hooks ├── docs/ # MkDocs documentation source
├── docs/ # MkDocs documentation ├── mkdocs.yml # MkDocs configuration
├── mkdocs.yml # MkDocs config ├── scripts/ # Utility scripts
├── scripts/ # Utility scripts └── [service]/ # Per-service configurations
└── [service subdirs]/ # All services have their own subdir ├── 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/<service>`
- Backups: `/mnt/storage/backups`

96
docs/index.md
View File

@@ -25,8 +25,102 @@ Welcome to Seirian & James' homelab documentation! This is a docs site that is b
## Quick Start ## Quick Start
```bash ```bash
git clone git@gitea.sjhl.nz:james/homelab-infra.git
cd homelab-infra
# Set up environment
cp .env.example .env 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 docker network create web
# Start everything
make up 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/<service>`
- Backups: `/mnt/storage/backups`

2
docs/services/devbox.md
View File

@@ -1,7 +1,7 @@
# devbox # 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 ## Docker Compose Configuration
```yaml ```yaml

2
docs/services/gitea.md
View File

@@ -1,7 +1,7 @@
# gitea # 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 ## Docker Compose Configuration
```yaml ```yaml

2
docs/services/nextcloud.md
View File

@@ -1,7 +1,7 @@
# nextcloud # 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 ## Docker Compose Configuration
```yaml ```yaml

2
docs/services/obsidian-livesync.md
View File

@@ -1,7 +1,7 @@
# obsidian-livesync # 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 ## Docker Compose Configuration
```yaml ```yaml

2
docs/services/traefik.md
View File

@@ -1,8 +1,8 @@
# traefik # traefik
> This page auto-includes the service configuration files.
--8<-- "traefik/README.md" --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 ## Docker Compose Configuration
```yaml ```yaml

2
docs/services/whoami.md
View File

@@ -1,7 +1,7 @@
# whoami # 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 ## Docker Compose Configuration
```yaml ```yaml