On this page
← writing

How I built Choud, a Google Drive that lives on one spare laptop

· 6 min read · self-hosting · C++ · FastAPI · architecture · Android

Part of Choud

Choud is a self-hosted Google Drive alternative. It runs on one spare Linux machine at home, keeps your files on your own disk, and reaches your phone and laptops over Tailscale or your home network. The idea started around 28 or 29 August 2026 and I worked on it until about 10 or 11 October, roughly six weeks. This is how it got built, from the repository itself: github.com/chinchoooo/Choud.

I built it because I was tired of paying for storage while I had perfectly good hardware lying around the house. Instead of renting space in someone else's cloud, I wanted to turn what I already owned into a server.

The server is a Lenovo laptop with a 1 TB drive and 16 GB of RAM, running Linux Mint and always plugged into power. It is wired over Ethernet for the best performance, but it works over Wi-Fi too.

The one rule: understandable from end to end#

The first commit is from 18 September 2026, a few weeks after the idea, and the first real document I wrote was not code, it was the philosophy in docs/architecture.md: build a system that is understandable from end to end. The same file lists what the project must not become: no Kubernetes, no microservices, no Kafka, no distributed anything. It allows exactly one deliberate exception, Meilisearch as a single optional service for searching inside file contents, and says the core must keep working when it is absent.

That rule shaped every later decision. When I was unsure about a feature, the test was whether one person could still hold the whole system in their head afterwards.

Architecture: a control plane and a data plane#

Browser · Android app · Desktop client
                 | HTTP (Tailscale or LAN)
                 v
      Python API (FastAPI) ---- PostgreSQL (metadata, search index)
                 | internal network only
                 v
      C++ engine (data plane) -- your disk (bytes, by hash)

Python owns the API, accounts, permissions, versions, sharing and search. The C++ engine owns the bytes: hashing, content-addressed storage, deduplication and chunk assembly. It is never exposed to the network, only the backend talks to it, and its HTTP API stays deliberately small and unauthenticated for that reason. The browser app is React, the phone app is Kotlin, and a desktop client in Python syncs folders.

Python and C++ talk over a plain local HTTP API instead of FFI. The process boundary keeps each side testable on its own, and it means the engine can be restarted or replaced without touching the API. The two containers share a Docker volume, so requests pass paths on that volume instead of pushing file bytes through HTTP twice.

Why C++ for the engine at all? Because it is the part where bytes, hashing and disk behaviour matter. File contents never touch PostgreSQL; they sit on disk under their content hash, so uploading the same file twice stores it once. Every upload is hash-checked, and a missing chunk or a hash mismatch fails before anything reaches the object store.

Uploads that survive a bad connection#

Uploads are chunked and resumable: if the connection drops, only the missing chunks are resent. The engine writes chunks under a temporary upload id, finalizes only when chunks 0..N-1 are all present and the hash matches, and cleans up abandoned uploads. A test (ChunkManagerTest.DuplicateContentAcrossUploadsIsDeduplicated) pins down that two chunked uploads of identical content are stored once.

The rule I wrote at the top of AGENTS.md was never silently destroy data. Unsure: keep it, return an error, log it. That is why overwrites become versions, deletes go to a trash, and the desktop sync writes conflict copies instead of overwriting anything.

What broke#

The repo has a troubleshooting file, docs/errors.md, made of problems I actually hit when I first deployed to a real server. A few I remember best:

  • A migration that could not record itself. Alembic's own alembic_version table has a 32-character column, and my migration names were descriptive, like 0002_add_folders_and_files_tables. The migration failed partway, and because it ran as one transaction everything rolled back, which made the "table does not exist" errors on the next run look worse than they were. The fix was to create the tracking table myself with a wider column first.
  • The web app loaded but every API call failed with ERR_CONNECTION_REFUSED to localhost:8000. The frontend's API address defaulted to localhost, which only means the server when you browse from the server itself; from my laptop it meant my laptop. The fix was a relative path through Caddy's /api/* proxy, and the trap inside the fix was a Compose default (${VAR:-default}) that treats an empty value the same as unset and silently put localhost back.
  • A multi-gigabyte upload failing after a long wait with a 502. The engine call had timed out. The timeout became a setting, ENGINE_DATA_TIMEOUT_SECONDS, defaulting to 1800 seconds.
  • Windows line endings in shell scripts (/bin/bash^M: bad interpreter), which a .gitattributes rule now prevents, with a preflight script that reports any file that slipped through.

Most of these became startup checks. The server now refuses to boot with a placeholder JWT_SECRET, for example, instead of running insecurely.

Version 0.5.0 was about one problem: opening your photos over a 100 to 200 ms link is slow because of round trips, not bandwidth. Forty thumbnails fetched one by one cost forty trips. The phone app now keeps the whole library in a local database with delta sync, paints blurry ThumbHash placeholders at once (about 25 bytes per photo), fetches 24 thumbnails per request, serves WebP thumbnails on stable immutable URLs, and reuses one HTTP client. scripts/netcheck.sh found the other half of the problem on my own server: Wi-Fi power saving on the laptop, which made a same-room ping 90 ms instead of 3 ms.

Did it hold up? Benchmarks, honestly#

I ran the same style of tests that cloud-storage reviews publish, on the home server (the laptop above, 4 logical CPUs, client on the same machine with line speeds simulated), one run each. After the speed fixes (non-blocking uploads, three chunks in flight, no double read, hard links for downloads), a 500 MB upload took 3:31 against Google Drive's published 3:33, which I read as level, not faster. A 5 GB mixed folder of 1,045 files uploaded at 83.8% of the line against Drive's 92%, still about 40 seconds slower, because each small upload costs roughly 65 ms of server work including the flush to disk that keeps files safe through a power cut. That is a deliberate trade. The 5 GB download came out slower on the second run, and the doc reports it instead of hiding it. These are single runs, so the comparison is indicative.

Deployment#

Docker Compose runs the backend, engine, PostgreSQL and a Caddy reverse proxy; migrations run automatically at start. A laptop server with Tailscale is the target setup, and one script, scripts/enable-public-links.sh, makes share links work from anywhere through Tailscale Funnel or a Cloudflare Tunnel, with a pause switch, without exposing the rest of the drive. Nightly backups are verified, and CI runs lint and tests for the server, web app, engine, desktop client and Android app.

What I learned#

  • Writing the non-goals down early saved more time than any feature.
  • A clean process boundary beats clever integration when one person maintains everything.
  • Test the failure cases, not only the happy path: corrupt object, interrupted upload, bad token, someone else's file, conflicting edit.
  • Publish the numbers that do not flatter you.

Choud is MIT licensed and the roadmap in docs/roadmap.md records every phase's decisions and traps.