From 99a0fc9768cb7ebc5fdeb8a982eb0a0c6e1e36e6 Mon Sep 17 00:00:00 2001
From: Adam Moussa <166072409+amoussa1229@users.noreply.github.com>
Date: Fri, 5 Jun 2026 15:54:22 -0400
Subject: [PATCH] docs: update README for unmanaged data volume, SFTP, cached
 AMI (#6)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Storage architecture changed 2026-06-05 (volume imported by ID, not
CFN-managed) — the old Expanding Storage procedure no longer worked.
---
 README.md | 20 +++++++++++---------
 1 file changed, 11 insertions(+), 9 deletions(-)

diff --git a/README.md b/README.md
index 0c2c433..2a32989 100644
--- a/README.md
+++ b/README.md
@@ -4,13 +4,16 @@ Personal file share server on AWS — Samba for macOS Finder integration and Fil
 
 ## Architecture
 
-- **EC2** — `t4g.small` (ARM64, Amazon Linux 2023) in the private subnet
+- **EC2** — `t4g.small` (ARM64, Amazon Linux 2023) in the private subnet. The AMI is cached in the committed `cdk.context.json` (`cachedInContext: true`), so deploys never pick up a new AL2023 release implicitly — an AMI change forces instance replacement and must be deliberate (`cdk context --reset <ami key> && cdk synth`).
 - **Samba** — SMB file share at `/data/share`, optimized for macOS (`vfs_fruit`)
 - **FileBrowser** — Web UI on port 8080, backed by the same `/data/share` directory
-- **EBS** — 500 GiB gp3 data volume (separate from root), encrypted
-- **DLM** — Daily EBS snapshots, 30-day retention
+- **SFTP** — password auth for user `adam` (`ForceCommand internal-sftp`, same password as SMB); used by Hazel for automated uploads
+- **EBS data volume** — `vol-04d951cccacc435b5`, 500 GiB gp3 encrypted, mounted at `/data`. **Unmanaged import**: the stack references it by ID (`Volume.fromVolumeAttributes` + `CfnVolumeAttachment`), so CloudFormation can attach it but can never create, replace, or delete it — the data survives instance replacement and even stack deletion. UserData waits for the attachment, then mounts the existing filesystem; a `blkid` guard ensures a disk that already has a filesystem is never formatted.
+- **DLM** — Daily EBS snapshots at 06:00 UTC, 30-day retention (targets the `file-share-backup=true` tag, set directly on the volume)
 - **SSM** — Session Manager for instance access (no SSH key)
 
+> **History:** the data volume was originally an inline `blockDevice`, which destroyed data on instance replacement (2026-05-27 incident), then a stack-managed standalone volume, which was orphaned when an uncommitted deploy got reverted by CD (2026-06-05 incident). The unmanaged-import design ends that failure class.
+
 ## Access
 
 Requires VPN connection to the office network (10.10.0.0/16).
@@ -52,12 +55,11 @@ The stack outputs the instance's private IP for SMB and FileBrowser access.
 
 ## Expanding Storage
 
-The 500 GiB data volume can be expanded without downtime:
+The data volume is **not managed by CloudFormation** (imported by ID), so changing a size in `lib/file-share-stack.ts` has no effect. Expand it directly — no downtime:
 
-1. Modify the volume size in `lib/file-share-stack.ts`
-2. Deploy: `npx cdk deploy`
-3. SSH into the instance via SSM and resize the filesystem:
+1. `aws ec2 modify-volume --volume-id vol-04d951cccacc435b5 --size <new-GiB>`
+2. Wait for the modification to leave `modifying`: `aws ec2 describe-volumes-modifications --volume-ids vol-04d951cccacc435b5`
+3. Resize the filesystem via an SSM session:
    ```bash
-   sudo growpart /dev/xvdf 1  # if partitioned
-   sudo resize2fs /dev/xvdf
+   sudo resize2fs /dev/nvme1n1   # xvdf surfaces as nvme1n1 on Nitro instances
    ```