136 lines
4.6 KiB
Markdown
Executable File
136 lines
4.6 KiB
Markdown
Executable File
# SJHL Documentation
|
|
|
|
!!! warning "Early development"
|
|
This documentation is in early development and not all features are working yet. Use with caution.
|
|
|
|
Welcome to Seirian & James' homelab documentation! This is a docs site that is built to easily show all the configs we use. MOst of the content is auto-generated from the actual config files, so it should always be up to date. This should be completely publically viewable as all private information is kept in `.env` files that are not committed to Git. It should provide good information on how to recover and rebuild the homelab if needed, and also just be a nice reference for how everything is configured.
|
|
|
|
## Data Classification
|
|
|
|
| Type | Example | Git Repo? | Backup? | Location |
|
|
|------|---------|-----------|---------|----------|
|
|
| **Source Configs** | `docker-compose.yml`, `.env.example`, `Makefile` | Yes | No | `/srv/homelab-infra` |
|
|
| **Service Secrets** | `.env` (DB passwords, API keys) | No | Yes | `/srv/homelab-infra/services/<service>/.env` |
|
|
| **Runtime Configs** | `acme.json`, service configs | No | Yes | `/mnt/storage/docker-data/<service>` |
|
|
| **Persistent Data** | DB data, uploads, media | No | Yes | `/mnt/storage/docker-data/<service>` |
|
|
|
|
## Services
|
|
|
|
| Service | Image | Status |
|
|
|---------|-------|--------|
|
|
| [cloudflare-ddns](services/cloudflare-ddns.md) | `favonia/cloudflare-ddns:1` | active |
|
|
| [devbox](services/devbox.md) | `devbox-devcontainer` | active |
|
|
| [docs-site](services/docs-site.md) | `nginx:alpine` | active |
|
|
| [gitea](services/gitea.md) | `gitea/gitea:1.24.3` | active |
|
|
| [nextcloud](services/nextcloud.md) | `ghcr.io/nextcloud-releases/all-in-one:latest` | active |
|
|
| [obsidian-livesync](services/obsidian-livesync.md) | `couchdb:latest` | active |
|
|
| [traefik](services/traefik.md) | `traefik:v3.6` | active |
|
|
| [whoami](services/whoami.md) | `traefik/whoami` | active |
|
|
|
|
## Quick Start
|
|
|
|
```bash
|
|
git clone git@gitea.sjhl.nz:james/homelab-infra.git
|
|
cd homelab-infra
|
|
|
|
# Create all missing .env files from templates
|
|
make init-env
|
|
|
|
# Edit .env and services/*/.env with real secrets
|
|
|
|
# Create required Docker networks
|
|
docker network create web
|
|
|
|
# Start and verify everything
|
|
make up
|
|
make status
|
|
|
|
# Optional: start/stop one service
|
|
# make up-<service>
|
|
# make down-<service>
|
|
```
|
|
|
|
## 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
|
|
└── services/ # Service definitions
|
|
└── <service>/ # One folder per service
|
|
├── 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`
|