Architecture

Architecture

This page provides the high-level view of how everything fits together — from a git push to a fully provisioned NAS.

Overview

flowchart TD
    subgraph GitHub
        A[nas-as-code<br/>Ansible] --> GA[GitHub Actions]
        B[nas-containers-as-code<br/>Docker Compose] --> GB[GitHub Actions]
    end

    GA --> KV[Azure KeyVault<br/>secrets pulled at runtime]
    GB --> KV

    KV --> WG[WireGuard VPN Tunnel<br/>runner → home network]

    WG --> NAS

    subgraph NAS
        MFS[MergerFS<br/>Storage Pool]
        SMB[Samba<br/>Shares]
        DCK[Docker<br/>Stacks]
        BKP[Backups<br/>LVM]
    end

Loading

Deployment Flow

nas-as-code (Provisioning)

1. Push to main triggers the Provision workflow
2. Workflow runs as a matrix — deploys to test first, then production
3. Connects to Azure → pulls all secrets from KeyVault
4. Replaces #{TOKEN}# patterns in Ansible group_vars with secret values
5. Establishes WireGuard tunnel to home network
6. Runs Ansible playbook over SSH against the NAS
7. Generates a deployment summary report in the GitHub Actions job summary

nas-containers-as-code (Containers)

1. Push to main triggers the Deploy workflow
2. Connects to Azure → pulls secrets → replaces tokens in .env files
3. Establishes WireGuard tunnel
4. Creates a Docker context pointing at the NAS over SSH
5. Iterates through each stack directory, running docker compose up -d
6. Syncs the repo content to /config/stacks on the NAS for local reference

Environments

Environment	Purpose	When
test	Validate changes on a test NAS instance	First in matrix
production	Apply to the real NAS	After test succeeds

Both environments share the same Ansible code but have their own GitHub Environment with distinct secrets and variables.

Key Design Principles

• Idempotent — run it once or ten times, same result
• Secrets never in code — everything sensitive lives in Azure KeyVault
• Minimal NAS surface — the OS is kept lean, everything runs in Docker
• Recoverable — the NAS can be rebuilt from scratch using just these repos + KeyVault