SPHERE DRIVE

Self-hosted · home project · 2026

Sphere Drive

A private file store and personal knowledge wiki for our household. It runs on a home server, works only on the home network, and was designed, built and deployed from scratch, one pull request at a time.

FastAPISQLite Jinja2 + HTMXAlpine.js Ubuntu 24.04 · systemdLAN-only
2rooms behind one login
188docs in the wiki
35topics in 7 categories
27pull requests, v1 → v2
Sphere Drive wiki: a library tree on the left, a lesson on LLM internals in the middle, and a Related panel listing docs that share tags on the right.
The wiki: library tree, the doc you're reading, and what it connects to

The idea

One login, two rooms

We wanted a NAS-like place for household files that we owned outright. I also wanted a home for the project notes, lessons and diagrams I write while learning. Neither should live on a cloud service, so both run on the hardware we already had.

Room 1

Shared

A read/write file store for the household.

  • Upload by drag-and-drop, make folders, download, delete
  • Any file type can be stored
  • PDF, PNG, JPEG and text open in the browser
  • 500 MB per-file upload limit

Room 2

Wiki

A knowledge base of Markdown, HTML, images and PDFs.

  • Organized as Category / Topic / doc, each doc with a type
  • Markdown is editable in the app, and pictures and Mermaid diagrams render inline
  • Every Topic has a hub page, which can be arranged into a dashboard
  • Links, embeds and shared tags connect docs across Topics

The wiki room

Built for reading first

The redesign started from two complaints about version 1: text was hard to read, and navigation labels wrapped onto a second line. The fix became a design system called Orbital Glass: 17px body text in a 720px column, a single-line library tree, and floating glass panels with one lavender accent that marks where you are.

01 · TOPIC HUBS

Every Topic gets a front page

A hub gathers its Topic's docs and groups them by type (lessons, references, specs), with diagrams as thumbnails at the bottom. The library tree uses the same grouping, collapsed until you need it.

Connected Topics lists other Topics that share a tag, so learning notes lead to the hardware projects that use them.

The Fundamentals Topic hub: a summary, two lesson cards, two diagram thumbnails, and a Connected Topics panel listing hardware projects that share the hardware tag.
Fundamentals hub · docs by type · Connected Topics via shared tags
02 · DASHBOARDS

Hubs that rearrange into boards

Any hub can switch to Arrange mode, where you drag and resize panels on a 12-column grid. A panel can show a doc, a diagram, a PDF, the hub summary or the Topic's Related links.

The layout is saved to a small JSON sidecar next to the hub, so it moves with the Topic folder. Adding or deleting docs never reshuffles the board.

The Fundamentals hub arranged as a board, with a full-width diagram panel titled Bits to notation and meaning.
An arranged board · vendored Gridstack, loaded only when a board is shown
03 · DIAGRAMS AS TEXT

Mermaid in Markdown

Write a ```mermaid fence and it renders as a themed diagram. The library downloads only when a page needs it, and it runs in strict security mode.

Pictures work the same way. ![alt](name.png) looks in the doc's own Topic first, then searches the whole wiki, so moving a doc never breaks its images.

A lesson on binary, bytes and hex with a rendered Mermaid flowchart showing how physical bits branch into notation and meaning.
A lesson with an inline Mermaid diagram
04 · ANY KIND OF DOC

Pictures, PDFs and HTML are first-class docs

Images, SVGs and PDFs sit in the tree like any note. Each one has a type, tags and a place on its hub, all stored in a .meta sidecar. HTML docs are shown read-only inside a sandboxed iframe.

An image doc, the ADS1115 pinout, shown on an iPad-sized screen with its type and tag chips.
Image doc · on iPad
A PDF schematic for a Pico 2 carrier board shown in the built-in PDF viewer.
PDF schematic · built-in viewer
An HTML lesson on retrieval-augmented generation shown inside a sandboxed frame, marked read only.
HTML lesson · sandboxed, read-only
05 · WRITE

Edit in place

Markdown docs open in a plain editor with a small toolbar: headings, code fences, [[wikilinks]] and Image, which also accepts paste and drag-and-drop. Preview renders through the same sanitizer as the reading view.

The Markdown editor open on a pytest guide, with a formatting toolbar and Cancel, Preview and Save buttons.
Markdown editor · front-matter style type and tags
06 · FIND

Search as you type, browse by tag

Search covers file names and Markdown text, and each hit shows a highlighted snippet. Tags are outlined chips (types are filled), and clicking a tag lists every doc that carries it, across every Category.

Search results for multiplexer, three hits with the match highlighted in each snippet.
Live search · results arrive as you type
The arduino tag page listing six docs from hardware projects and learning topics.
Tag view · one tag, every Topic
07 · FILE

Upload mapping

Choose a folder of notes, then map each file to a Category, Topic, type and tags. Apply to all sets the defaults, and any row can override them. Suggested tag chips come from the Topic you picked.

Files without a Topic land in Unsorted, where you can sort them later. You can also create a new Topic right in the picker.

The Upload staging screen: an Apply to all row set to Learning Hardware and Chips, Protocols and Buses, lesson, with suggested tag chips, and staged files below.
Staging four notes into Protocols & Buses

The shared room

Plain, fast file storage

The Shared room deliberately does less: browse folders, drop files in, open the common types in the browser, and download the rest. Same login, same look. (The files shown are sample data.)

The Shared files page with a drop zone and a table of folders and files showing type, size and modified date.
Root folder · drop zone, View for PDF/TXT, download for the rest
A subfolder named Lisbon 2026 with an itinerary, boarding passes and a tram map.
A subfolder with a breadcrumb trail

Under the hood

Small stack, sharp edges filed off

Pages are rendered on the server, HTMX swaps the parts that change, and Alpine.js adds the few interactive pieces. There's no build step and no front-end framework. Files live on disk as ordinary folders, and SQLite holds only accounts and sessions.

Security

Path-traversal guard on every path

The biggest risk for a file server. Every user-supplied path is resolved and checked against its room's root, so .., absolute paths and symlinks pointing outside are all rejected.

Security

Sanitized Markdown, sandboxed HTML

Rendered Markdown passes through an nh3 allow-list before it reaches the page. Uploaded HTML never runs in the app's origin; it's shown in a sandboxed iframe.

Security

LAN-only plus login

The router keeps the app off the internet, and a username/password login guards every route. Uploads have size caps per type, and secrets stay in an untracked .env.

Performance

Load only what the page needs

Fonts are self-hosted, so nothing is fetched from the internet. Mermaid and Gridstack are vendored and fetched only on pages that use them. Templates and CSS are served from disk, so most updates go live without a restart.

Data

Files you can walk away with

The wiki is just folders of .md, images and PDFs. Types, tags and board layouts live in small sidecar files beside each doc, so a plain copy of the folder is a complete backup.

Process

Spec → plan → PR → deploy

Each feature started as a written design and plan, landed as a reviewed pull request, was tested by hand in the browser, and was deployed with small rsync scripts.

How it grew

From v1 to Orbital Glass

Version 1 used a Star Trek LCARS theme and came together in a couple of days. Version 2 rebuilt the structure and the look around how the wiki was actually being used.

  1. v1 built and deployedTwo rooms, login, upload, Markdown rendering, LCARS theme. Running on the home server the next day.
  2. The wiki becomes a workspaceIn-app Markdown editing, search, tags, wikilinks, and a batch mapper for loading folders of notes.
  3. v2 framework rebuildCategory → Topic structure with doc types and Trash. A one-time migration moved 119 docs into 29 Topics. The Orbital Glass design system replaces LCARS.
  4. Richer docs and connectionsImages, PDFs and Mermaid as first-class docs, an nh3 sanitizer, and the Related panel.
  5. Topic dashboardsDrag-and-resize boards saved as layout sidecars. Library tree grouped by type.
  6. Simpler accessDevice pinning replaced with LAN-only plus login so the iPads just work, plus a home-screen icon.