Self-hosted storage: browse files in Finder over SMB and give your apps an S3-compatible endpoint. One Mac, one USB hard drive, no router port forwarding.
Second copy, never the only copy. A single old drive can fail without warning. This setup has no redundancy, high availability, or S3 object versioning. Read backup and recovery before storing anything important.
The reference setup uses an M1 MacBook Pro, its charger, a spare Seagate 2.5-inch SATA HDD, a SATA-to-USB adapter, and a UGREEN USB hub. No additional hardware is required by the software. The adapter/hub must reliably power the drive, including spin-up; test a direct USB connection if it disconnects. Ethernet is optional. Secure a bare drive against movement and contact with conductive surfaces.
The Mac runs on AC power with sleep disabled and an approximately 80% charge cap managed separately by AlDente. Keep its vents clear. Closed-lid operation, USB access while locked, and restart recovery must be checked on the actual machine.
| Service | Access | Role |
|---|---|---|
| macOS File Sharing | Tailscale, authenticated SMB | Ordinary files in Finder |
| Garage 2.4.1 | Loopback; public S3 through Cloudflare Tunnel | Private object storage |
| cloudflared | Outbound tunnel | HTTPS without opening router ports |
| tailscaled | Private tailnet | SMB and ordinary SSH administration |
SMB files and S3 objects are separate namespaces on the same HDD. Do not share Garage's block or metadata directories over SMB. Files copied into the SMB folder do not appear in S3; S3 objects do not become editable Finder files.
Native Homebrew Garage is the recommended Mac route: no Linux VM, with launchd startup before user login. Docker Compose is the portable alternative. Choose one; do not run both against the same storage.
- Clone this repository and read architecture and choices.
- Follow macOS setup: prepare the drive, stable mount, separate accounts, Garage, and supervised startup.
- Follow networking: Tailscale, host firewall, SMB, SSH, Cloudflare Tunnel, and no automatic router mappings.
- Create buckets and per-app credentials.
- Configure an independent backup destination and restore procedure.
- Complete the acceptance checks, including another Mac and an off-network S3 client. A passing local test does not prove these checks passed.
The project's reference endpoint is https://bin.gtfol.dev. It is intended as
an authenticated deployment, not a public anonymous upload service. Deployment on
the reference M1 and external-drive acceptance checks are not yet verified.
Use your own domain and accounts when self-hosting; examples use s3.example.com.
Cloudflare's upload limits apply per request; use multipart uploads for larger objects. Its media/large-file delivery policies also apply. This project does not promise unlimited free bandwidth or complete AWS S3 compatibility.
config/ contains non-secret templates, tools/ contains reusable checks and
supervision, tests/ contains synthetic tests, and docs/ contains maintained
setup and operations guides. Runtime state belongs outside the checkout.
No personal files, real test data, disk identifiers, credentials, tunnel identity, tailnet policy exports, logs, scratch code, or session journals belong in Git. See contributing, security, and development checks.
MIT, copyright gtfol, LLC, for this repository's original configuration, tools, and documentation. Garage and other dependencies retain their own licenses; see third-party software.