93 lines
4.3 KiB
Markdown
93 lines
4.3 KiB
Markdown
# Homelab Blueprint
|
|
|
|
Docker Compose templates and deployment guides for self-hosted services.
|
|
|
|
## Quick Start
|
|
|
|
1. Copy the sample environment file:
|
|
```bash
|
|
cp -n .env.sample .env
|
|
```
|
|
2. Configure `.env` with your values.
|
|
3. Use the `Makefile` to deploy a stack:
|
|
```bash
|
|
make help # See all available commands
|
|
make check-env # Validate your .env file
|
|
make deploy-caddy # Deploy the reverse proxy
|
|
```
|
|
|
|
Each stack guide in `docker-compose-files/<stack>/README.md` explains appdata placement, rendering, and networking.
|
|
|
|
## Stacks
|
|
|
|
| Stack | Description |
|
|
|---|---|
|
|
| [Arr Stack](docker-compose-files/arr-stack/README.md) | Media management, downloads, VPN, Emby, and Recyclarr |
|
|
| [BentoPDF](docker-compose-files/bento-pdf/README.md) | Privacy-first client-side PDF toolkit |
|
|
| [Beszel Agent](docker-compose-files/beszel-agent/README.md) | Host and Docker monitoring agent |
|
|
| [Beszel Hub](docker-compose-files/beszel-hub/README.md) | Beszel monitoring dashboard |
|
|
| [Beszel Socket Proxy](docker-compose-files/socket-proxy/README.md) | Restricted Docker API access for Beszel |
|
|
| [Caddy](docker-compose-files/caddy/README.md) | Reverse proxy with Cloudflare DNS-01 |
|
|
| [Gramps Web](docker-compose-files/gramps-web/README.md) | Genealogy web application |
|
|
| [Home Assistant](docker-compose-files/homeassistant/README.md) | Home Assistant, Mosquitto, and Zigbee2MQTT |
|
|
| [Immich](docker-compose-files/immich/README.md) | Photo and video management with GPU acceleration |
|
|
| [IT-Tools](docker-compose-files/it-tools/README.md) | Developer and sysadmin utility toolbox |
|
|
| [Koffan](docker-compose-files/koffan/README.md) | Shared household grocery/shopping list |
|
|
| [Paperless-ngx](docker-compose-files/paperless-ngx/README.md) | Document management with OCR and full-text search |
|
|
| [PostgreSQL](docker-compose-files/postgres/README.md) | PostgreSQL and pgAdmin |
|
|
| [Rackula](docker-compose-files/rackula/README.md) | Drag-and-drop server rack layout designer |
|
|
| [Technitium DNS](docker-compose-files/technitium/README.md) | DNS server and ad blocking |
|
|
| [Youtarr](docker-compose-files/youtarr/README.md) | YouTube downloader with metadata and media-server integrations |
|
|
|
|
## Management
|
|
|
|
The repository includes a `Makefile` to unify management of all stacks. It supports **modular environment files**, loading variables first from the root `.env` (Global) and then from the stack's own `.env` (Local).
|
|
|
|
| Command | Description |
|
|
|---|---|
|
|
| `make check-env` | Validates root and stack `.env` files against required placeholders in renderable templates |
|
|
| `make status` | Shows `docker compose ps` for all generated compose files |
|
|
| `make reload-caddy` | Zero-downtime reload of the Caddy configuration |
|
|
| `make ip-check` | Verifies VPN connectivity for Arr Stack containers |
|
|
| `make deploy-<stack>` | Renders templates and starts the specified stack |
|
|
|
|
### Custom Services (Rust/MQTT)
|
|
|
|
To add your own services (e.g., Rust-based backends):
|
|
1. Add your service to a new or existing `docker-compose.*.yml`.
|
|
2. Connect it to the `ha-network` if it needs to reach Home Assistant.
|
|
3. Expose it via Caddy by adding a block to `docker-compose-files/caddy/Caddyfile_template` and running `make deploy-caddy`.
|
|
|
|
## Shared Commands
|
|
|
|
Most stacks use the following manual pattern (automated by `make`):
|
|
|
|
```bash
|
|
./substitute_env.sh docker-compose-files/<stack>/template.yaml docker-compose.<stack>.yml .env
|
|
docker compose -f docker-compose.<stack>.yml config --quiet
|
|
docker compose -f docker-compose.<stack>.yml up -d
|
|
```
|
|
|
|
Home Assistant uses its setup script instead. Arr Stack, Caddy, and Gramps Web
|
|
render additional configuration templates.
|
|
|
|
`substitute_env.sh` only reads env files passed on the command line. It does
|
|
not fall back to OS environment variables or an implicit `.env`.
|
|
|
|
## Requirements
|
|
|
|
- Linux host with Docker Engine and Docker Compose
|
|
- Git
|
|
- A configured `.env` based on `.env.sample`
|
|
- Service-specific storage and network access described in each stack README
|
|
|
|
Generated `docker-compose.*.yml` files may contain secrets and are ignored by
|
|
Git.
|
|
|
|
## Operational Documentation
|
|
|
|
See the [documentation index](docs/README.md) for all guides. Most-used:
|
|
|
|
- [Arr Stack storage deployment](docs/arr-stack/deployment.md)
|
|
- [Troubleshooting](docs/troubleshooting.md)
|
|
- [UniFi custom firewall rules](docs/network/firewall-rules.md)
|