Architecture Overview

Architecture Overview

graph TD
    Server[Dedicated Server] --> OS[NixOS Bare Metal]

    OS --> PROD[💠 Production Environment]
    PROD --> HA_PROD[VM: Home Assistant OS Main]
    PROD --> DOCKER_PROD[Docker Stacks]
    DOCKER_PROD --> INFRA[stacks/infra Core]
    DOCKER_PROD --> PORTAL[stacks/portal Entry]
    DOCKER_PROD --> APPS[stacks/... Apps]

    OS --> LAB[🧪 Laboratory VM: NixOS Replica]
    LAB --> HA_TEST[VM: Home Assistant OS Testing]
    LAB --> DOCKER_TEST[Docker Stacks Mirror]

Server
└── NixOS (bare metal)
    │
    ├── 💠 Production Environment
    │   ├── VM: Home Assistant OS (Main)
    │   │   ├── Add-on Store
    │   │   └── Smart Home Services
    │   │
    │   └── Docker Stacks
    │       ├── stacks/infra/ (Core)
    │       ├── stacks/portal/ (Entry Point)
    │       ├── stacks/gallery/
    │       ├── stacks/media/
    │       └── [Other apps...]
    │
    └── 🧪 Laboratory VM (NixOS Replica)
        ├── VM: Home Assistant OS (Testing)
        │   └── [Sandbox for HA updates]
        │
        └── Docker Stacks (Mirror)
            └── [1:1 Mirror of production]

Stack

Operating System — NixOS

The entire OS is declared in nixos/ and versioned in this repo. On a new machine, a single command restores the full system configuration.

• Declarative, reproducible OS
• Home Manager for user-level dotfiles (replaces chezmoi)
• 1Password as the single source of truth for all keys, secrets, and passwords
• No configuration drift — every change goes through git

Virtualisation — microvm (HAOS)

Home Assistant OS runs as a lightweight VM managed by NixOS via microvm.nix. This gives access to the full Add-on Store (Zigbee2MQTT, Node-RED, Frigate, ESPHome) while keeping overhead minimal.

HAOS generates its own .tar backup natively, which is picked up by Restic alongside the rest of the data.

Laboratory (Staging)

The laboratory is a 1:1 mirror of the production environment, running inside an isolated MicroVM (Laboratory VM) that replicates the bare-metal server’s architecture. It hosts both the testing Home Assistant VM (via nested virtualization) and the production Docker stacks mirror.

Isolation & Lifecycle

• Network: Isolated bridge br-test with no access to production containers.
• Resources: Dynamically allocated (off by default).
• Control:

  # Start Laboratory
  systemctl start microvm@sandbox
  
  # Stop Laboratory (0 resource usage)
  systemctl stop microvm@sandbox

Synchronization (Cloning Pro → Test)

To make testing realistic, the laboratory can be “cloned” from production data in minutes using Restic snapshots. This ensures that you are testing against your real data, not placeholders.

./.scripts/07-sync-pro-to-test.sh