FAMILY S3 Storage Integration & Blueprint

FINAL PLAN (approved 2026-08 session). Implementation tracked in /home/sam/home_network/custom_tools/family_home_lab/plan.md. Supersedes the generic blueprint below.

Final architecture

Item	Decision
Engine	Fresh Garage v1.x container inside the family-home-lab Docker Compose stack
Host	`.13` nixos-desktop (always-on server)
Compose location	`/home/sam/Docker/Containers/family-home-lab/`
Data location	`/mnt/data/family-home-lab/garage-data/` + `/mnt/data/family-home-lab/garage-meta/` — new subdirs only. The Takeout landing zone (`01_keep`, `02_review`, `03_delete`, `takeout`, `.thumbs`) is never touched or reformatted
Ports	`3900` (S3 API), `3902` (web) — old test instance `garage-garage-1` retired first to free these
Region	`homelab`
Buckets	`sam`, `jo`, `harry`, `finn`, `shared-media`
Access	Portal (FastAPI) uses boto3, S3v4 signatures, endpoint `.13:3900`
Backups	`/mnt/data/family-home-lab/` added to .13's existing Borg job → rsync→.35→.23 chain

Migration steps

Sanity-check old test instance data: sudo du -sh /var/lib/docker/volumes/garage_garage_data/_data/*
Stop & remove old garage-garage-1 (compose at /home/sam/deployment/garage/)
Deploy new Garage in family-home-lab stack with data dirs on /mnt/data
Create buckets + per-user S3 access keys via garage admin CLI
Verify portal upload/download round-trip
Add path to Borg backup sources

Consumers

Family console portal (console.home.lab) — uploads/downloads per-user buckets
Media tools (Photopea/video/audio containers) — bind-mount or rclone-mount bucket paths
DeepSeek Harness instances (FAMILY DeepSeek Harness (dsh) Home Lab Setup) — optional workspace persistence in user buckets

Original generic blueprint (reference only)

This document details the architectural expansion of the self-hosted AI and multimedia workspace. It introduces a pure open-source, local S3 object storage tier using Garage (Rust-based), replacing legacy volume mappings with decoupled web APIs to unify storage across network nodes.

Garage engine config (final form)

metadata_dir = "/var/lib/garage/meta"   # → mapped to /mnt/data/family-home-lab/garage-meta
data_dir = "/var/lib/garage/data"       # → mapped to /mnt/data/family-home-lab/garage-data
db_engine = "sqlite"
replication_factor = 1
rpc_bind_addr = "[::]:3901"

[s3_api]
s3_region = "homelab"
api_bind_addr = "[::]:3900"

[s3_web]
bind_addr = "[::]:3902"
root_domain = "web.s3.home.lab"

Caddy routing (.35)

s3.home.lab {
    reverse_proxy 192.168.20.13:3900
}

Full original compose example

expand

version: '3.8'
services:
  studio-s3:
    image: dxflrs/garage:v1.0.0
    container_name: studio_garage_s3
    restart: unless-stopped
    ports:
      - "3900:3900"
      - "3901:3901"
    volumes:
      - ./garage/garage.toml:/etc/garage.toml
      - /mnt/data/family-home-lab/garage-meta:/var/lib/garage/meta
      - /mnt/data/family-home-lab/garage-data:/var/lib/garage/data
    environment:
      - GARAGE_RPC_SECRET=<generate-fresh>

3.3 KiB Raw Blame History