Skip to content

Memory

Curated long-term knowledge about the sepia infrastructure.

Architecture

sepia is a home server running a self-hosted infrastructure stack. It serves as a home automation hub, smart meter reader, and storage platform.

Layers

┌───────────────────────────────────────────┐
│  Ingress Layer                           │
│  - Caddy (reverse proxy + HTTPS)         │
└───────────────────────────────────────────┘
                    │
┌───────────────────────────────────────────┐
│  Application Layer                       │
│  - Home Assistant (home automation)      │
│  - ESPHome (ESP device firmware)         │
│  - Seafile (file sync & share)           │
│  - DSMR Reader (smart meter P1)          │
│  - Node-RED (flow-based automations)     │
└───────────────────────────────────────────┘
                    │
┌───────────────────────────────────────────┐
│  Data & Processing Layer                │
│  - TimescaleDB (time-series DB, pg14)    │
│  - InfluxDB (time-series metrics)        │
│  - PostgreSQL (DSMR reader DB)           │
└───────────────────────────────────────────┘
                    │
┌───────────────────────────────────────────┐
│  Monitoring Layer                        │
│  - Grafana (visualization)               │
│  - Collectd (system metrics)             │
└───────────────────────────────────────────┘

Key Integration Points

Home Automation 1. DSMR Reader -> smart meter P1 data -> InfluxDB 2. ESPHome -> ESP device firmware 3. Home Assistant -> automation hub (host network) 4. Node-RED -> flow-based automations

Data Collection 1. Collectd -> system metrics -> InfluxDB 2. DSMR -> energy data -> PostgreSQL + InfluxDB 3. TimescaleDB -> sensor time-series data

Storage 1. Seafile -> file sync and share (MariaDB backend) 2. DNS ad-blocker -> network-wide ad blocking

Technology Stack

  • Container Orchestration: Docker Compose
  • Reverse Proxy: Caddy (with automatic HTTPS, Route53 DNS)
  • Monitoring: Grafana + InfluxDB
  • Databases: PostgreSQL (DSMR), TimescaleDB (pg14), InfluxDB, MariaDB (Seafile)
  • Backup: Borgmatic

Conventions

Code Style

  • No unnecessary comments unless asked
  • Follow existing conventions in the codebase
  • Concise and direct

Docker

  • Compose files use modular structure: compose.<service>.yaml
  • Main compose at /opt/compose.yaml includes all modules
  • All services use restart: unless-stopped
  • Ports: document in REFERENCE/network.md

Networking

  • Services use extra_hosts with host:${HOST_IP} for host access
  • Host networking used only when hardware access required (homeassistant, esphome)
  • Caddy handles all HTTPS termination

Secrets

  • All secrets in .env file; never hardcoded in compose files
  • .env.example checked in to repo with values stripped (structure reference)
  • Compose files reference secrets with ${VAR:?} for fail-fast on missing vars

Storage

  • Service configs in /opt/<service>/
  • Persistent data on /media/

Timezone

  • Most services set to Europe/Amsterdam

Domain

  • Primary: veenboer.xyz
  • Subdomain: uitgeest.veenboer.xyz
  • Services typically at <service>.uitgeest.veenboer.xyz

Ansible

Infrastructure provisioning is managed via standalone Ansible playbooks in /ansible/. Two host profiles exist: sepia (this machine, Debian 13) and server (Debian 12). All playbooks target localhost with become: true. See REFERENCE/ansible.md for full documentation.

Git

  • Do not commit .env, credentials, or secrets
  • Follow commit message style of repository (short, imperative)
  • Git identity: user.name=Hermes, user.email=hermes@local