docs(infra): add storage topology

2026-08-11 11:50:49 +00:00
parent dd1e7acaf7
commit 751e647485
1 changed files with 49 additions and 0 deletions
@@ -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`.