Raspberry Pi 5 home server — Home Assistant, Zigbee, MQTT, and a Telegram-integrated AI agent, all managed via Docker Compose and accessible anywhere through Tailscale.
| Service | Port | Purpose |
|---|---|---|
| Home Assistant | 8123 | Smart home automation |
| Mosquitto | 1883 / 9001 | MQTT broker |
| Zigbee2MQTT | 8080 | Zigbee device bridge |
| AI Agent | — | Polls HA, sends Telegram alerts |
| Portainer | 9443 | Container management UI |
| Watchtower | — | Auto-updates (7-day cooldown) |
| Glances | 61208 | System monitoring |
- Raspberry Pi 5 8GB with active cooling
- NVMe SSD via M.2 HAT+ (mandatory — SD cards won't survive 24/7 writes)
- Zigbee dongle (e.g., Sonoff Zigbee 3.0 USB dongle Plus)
Raspberry Pi OS Lite (64-bit) — based on Debian 13 (Trixie), kernel 6.12.
- Release date: 4 Dec 2025
- Headless — no desktop environment needed for a server
- Flash with Raspberry Pi Imager or hold Shift at boot on Pi 5 to use the built-in network installer
Download: https://www.raspberrypi.com/software/operating-systems/
# 1. Clone and configure
cp .env.example .env
$EDITOR .env # fill in your tokens
# 2. Run setup (installs Docker, Tailscale, launches everything)
./scripts/setup.shSetup runs through three phases automatically:
- setup.sh — installs Docker + Tailscale, creates directories, launches containers
- validate.sh — verifies all services are healthy and reachable
- serve.sh — configures Tailscale Serve for HTTPS access
Copy .env.example to .env and fill in:
| Variable | Required | Description |
|---|---|---|
HA_TOKEN |
yes | Home Assistant Long-Lived Access Token |
TELEGRAM_BOT_TOKEN |
yes | From @BotFather |
TELEGRAM_CHAT_ID |
yes | From @userinfobot |
TZ |
no | Timezone (default: UTC) |
ZIGBEE_DEVICE |
no | Dongle path (default: /dev/ttyUSB0) |
TAILNET_HOSTNAME |
no | Tailscale hostname (default: bramble) |
After setup, services are available over HTTPS via Tailscale Serve:
https://bramble.<tailnet>.ts.net/ha → Home Assistant
https://bramble.<tailnet>.ts.net/portainer → Portainer
https://bramble.<tailnet>.ts.net/zigbee → Zigbee2MQTT
https://bramble.<tailnet>.ts.net/glances → Glances
./scripts/backup.shStops Home Assistant, tars config directories, and rotates the last 10 backups.
Zigbee devices ──USB──▶ Zigbee2MQTT ──MQTT──▶ Mosquitto ◀──HA──▶ Automations
│
AI Agent ──▶ Telegram
- Home Assistant runs on the host network for mDNS/discovery
- AI agent is a Python container that polls the HA REST API on a 5-minute schedule
- Watchtower checks for image updates nightly at 04:00 with a 7-day cooldown (supply-chain defense — only updates images on the registry for 7+ days)
- All containers use
json-filelogging with 10MB/3-file limits to protect SSD
bramble/
├── docker-compose.yml # Service definitions
├── .env.example # Configuration template
├── ai-agent/
│ ├── Dockerfile
│ ├── requirements.txt
│ └── agent/
│ ├── config.py # Environment config (frozen dataclass)
│ ├── main.py # Scheduler entry point
│ ├── ha_client.py # Home Assistant REST client
│ └── telegram_client.py # Telegram Bot API client
├── mosquitto/
│ └── config/mosquitto.conf
├── zigbee2mqtt/
│ └── data/configuration.yaml
└── scripts/
├── setup.sh # First-run setup
├── validate.sh # Health checks
├── serve.sh # Tailscale Serve config
└── backup.sh # Config backups
MIT