118 lines
3.1 KiB
Markdown
Executable File
118 lines
3.1 KiB
Markdown
Executable File
# homelab-infra
|
|
|
|
GitOps-managed infrastructure for homelab services.
|
|
|
|
## Quick Start
|
|
|
|
```bash
|
|
git clone git@gitea.sjhl.nz:james/homelab-infra.git
|
|
cd homelab-infra
|
|
|
|
# Set up environment
|
|
cp .env.example .env
|
|
# 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
|
|
```
|
|
|
|
## 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 |
|
|
|
|
## 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`
|