From 751e6474851de581aa74c8ceae9f59c852b95d01 Mon Sep 17 00:00:00 2001
From: DaystromMoira <skyerangerdelta+1@pldyn.net>
Date: Tue, 11 Aug 2026 11:50:49 +0000
Subject: [PATCH] docs(infra): add storage topology

---
 infrastructure/storage.md | 49 +++++++++++++++++++++++++++++++++++++++
 1 file changed, 49 insertions(+)
 create mode 100644 infrastructure/storage.md

diff --git a/infrastructure/storage.md b/infrastructure/storage.md
new file mode 100644
index 0000000..f1e4286
--- /dev/null
+++ b/infrastructure/storage.md
@@ -0,0 +1,49 @@
+# Storage
+
+**Last updated:** 2026-08-11
+
+## Overview
+
+Shared storage is provided by a QNAP NAS over NFS. All Docker Swarm nodes
+mount the same NFS export, giving stacks a consistent data path regardless of
+which node a container lands on.
+
+## NAS
+
+| Field | Value |
+|-------|-------|
+| Hardware | QNAP NAS |
+| IP | 192.168.50.212 |
+| NFS export | `/DockerSwarmData` |
+
+## Mount Points (Swarm nodes)
+
+| Mount point | Purpose |
+|-------------|---------|
+| `/mnt/DockerSwarmData/` | Root of all shared Swarm data |
+| `/mnt/DockerSwarmData/Projects/` | Dev project source trees |
+
+Docker Swarm stack data (volumes, configs, persistent state) lives under
+`/mnt/DockerSwarmData/`.
+
+## Sharp Edges
+
+### NFS bind mounts can hide container-built assets
+
+When a service generates files inside the container at startup (e.g. an app
+that seeds a config dir), an NFS bind mount will shadow the container's
+image-layer content with whatever is on the NAS — which may be empty on first
+deploy.
+
+**Mitigation:** Prefer Docker named volumes when the image owns initial
+content. Use bind mounts only for data that already exists on the NAS or is
+explicitly managed outside the container.
+
+### SQLite on NFS is a footgun
+
+NFS does not reliably implement POSIX file locking. SQLite depends on file
+locks for write serialisation. Running SQLite (or any lock-dependent embedded
+DB) on an NFS mount under concurrent writes **will cause corruption**.
+
+**Mitigation:** Run SQLite databases on local node storage, or replace with a
+network-capable database (Postgres, MySQL) on `memory-archives`.