# 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 |
| [Forgejo](docker-compose-files/forgejo/README.md) | Self-hosted Git service with automatic GitHub mirroring |
| [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 |
| [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)