22 guides · synced daily from GitHub
Penombre docs
A self-hosted drive. Upload, sync, share, trash, recover. SQLite by default: one container, one volume, no database server to babysit.
Introduction
A self-hosted drive. All the convenience of cloud storage, on hardware you own, with a bill of exactly zero.
Contributing
Unit tests preload test.setup.ts (see bunfig.toml), which mocks $app//#lib/server/ and the Drizzle db object; they need no database or Redis. bunfig.toml also sets rerunEach = 3 to catch flaky tests, and enforces coverage thresholds.
Getting started
Install, first boot, first look.
Getting Started
Spin up a Penombre instance in minutes with Docker Compose.
Showcase
Every screenshot below is generated by driving a real instance with Playwright (bun run screenshots) against a library seeded with one dummy file of each supported kind — an image, a video, a track, a PDF, a spreadsheet, a deck, some code, a 3D model and an archive. There is no demo instance to keep alive, and no hand-retouched marketing shot: if a screen stops rendering, the run fails rather than publishing it.
Simple Mode
Run Penombre as a bare shared file browser instead of a multi-user drive.
Self-hosting
Configure, deploy and put it behind HTTPS.
Environment variables
Configure your Penombre instance with environment variables.
Deployment
Deploy Penombre to production with Docker.
Reverse Proxy
Expose Penombre behind a reverse proxy with HTTPS.
Storage
Where Penombre keeps your files.
Encryption
Penombre can seal file bytes at rest with a key you hold, but start with disk-level encryption on DATADIR: for a stolen or decommissioned drive it covers strictly more, because it also covers the database. Application-level encryption then adds one thing disk encryption cannot: file bytes that stay sealed when they are copied off the server.
Mounted volumes
A volume is a directory mounted alongside the main drive. It appears in the sidebar as its own entry, is browsable and searchable like any other folder, and is reconciled with what is actually on disk.
Worker
Penombre offloads CPU- and I/O-heavy byte work to a small Go process rather than doing it inline in the app's request handlers.
Troubleshooting
Solutions to common Penombre issues.
Using Penombre
Files, media, documents and sharing.
Uploads
Uploading is deliberately boring: pick files, they land in the folder you are browsing. Two things about it are worth knowing.
Media and notes
Images, video and audio get more than a download link.
Documents, sheets and presentations
Penombre can create and edit three kinds of document in the browser, from the New button in the sidebar.
Sharing
Penombre shares a file or folder two ways, and the Share dialog has a tab for each:
Shared drives
A shared drive belongs to a group instead of a person. Everyone on it opens the same tree, uploads into the same folders, and sees the same trash — unlike sharing, where an item stays in its owner's drive and other people are given a door to it.
Notifications
The bell in the header tells you when someone else did something to your things. It is deliberately narrow: only events involving another person appear, so your own uploads, renames and deletions never ring it. Those are in your activity log instead.
Administration
Accounts, sign-in methods and instance settings.
Admin panel
Accounts with the admin role get an extra section at /admin, reachable from the user menu. It is hidden entirely when auth is bypassed — nobody signs in under bypass, so the shared owner being an admin is an accident of seeding rather than a person who should reach user management.
Authentication
Configure authentication methods for your Penombre instance. Penombre supports multiple authentication methods powered by Better Auth.
Internals
How the code fits together.