Knowledge Vault

Homelab File Management Principles

2 min read

Homelab File Management Principles

Problem

Multi-device hybrid environment (Mac Mini, Lenovo, Gaming PC) with no centralized storage. File structure, repo management, and data synchronization are inconsistent, creating risk before significant hardware investment.

Core Principles

1. Source of Truth Hierarchy

Data TypeSource of TruthRule
Code & ConfigRemote Repository (GitHub)Local copies are never primary
Hot Data (Active)Designated “Pseudo-NAS” machineOne machine holds master copy
Cold Data (Archives)Strictly read-only on local drivesDon’t modify until NAS arrives

2. Three-Bucket Separation

Never mix these in the same directory:

  • Persistent Data — irreplaceable files (documents, photos, finished assets)
  • Ephemeral Data — Docker containers, build artifacts, node_modules, temp files
  • Configuration — Docker Compose files, dotfiles, scripts (the “DNA” of your setup)

3. Infrastructure as Code

If a machine dies, restore services by cloning a repo and running docker compose up -d.

Universal Directory Structure

Identical on every machine. Avoid paths with spaces.

~/dev/
├── framework/           # Organizational framework repos
│   ├── infrastructure/  # Docker Compose, Ansible, scripts
│   └── dotfiles/        # Shared configs (.zshrc, .gitconfig)
├── active/              # Apps and tools in development
│   ├── client-work/
│   └── internal-tools/
├── archive/             # Finished projects (read-only)
└── lab/                 # Experiments and R&D (safe to delete)

Synchronization Strategy

  • Code: Git. Commit aggressively. Push from one machine, pull on another.
  • Non-code assets: Syncthing across all devices. When NAS arrives, add as Syncthing node — zero downtime migration.
  • Dev environments: DevContainers (VS Code .devcontainer folder) for portable, reproducible toolchains.

Repo Management

Hub Repo

Single repository linking the organization together. Contains documentation, generic scripts, high-level tracking. Use Git submodules sparingly for dependent private repos.

Docker Monorepo

Single infrastructure/ repo for all runtime configs:

/infrastructure
├── /services
│   ├── /traefik       # Reverse proxy
│   ├── /postgres      # Database
│   └── /app-prod      # Production app
├── .env.example        # Template (never commit actual .env)
└── Makefile            # Shortcuts (make up, make logs)

Operational Discipline

  • Clean Home Rule — never store project data on Desktop/Downloads; move to ~/dev/lab or delete
  • Weekly Commit & Prune — every Friday review ~/dev/lab; promote valuable experiments to ~/dev/active or delete
  • Secret Management — never hardcode API keys; use .env files with .gitignore immediately

Graph View

Backlinks