Self-hosting should take five minutes

“Open source” and “actually runnable by a normal human” are not the same thing. Plenty of repos are technically public and practically impossible to deploy — a maze of undocumented env vars, a required managed database, three services that must boot in the right order.

We have one rule at oss.codes: a fresh clone should be running in five minutes. Here’s how we get there.

One command to develop

git clone https://github.com/oss-codes/postalform
cd postalform && make dev

That’s the whole thing. make dev installs, seeds, and starts. If it needs more than one command, it needs a better Makefile.

Sane defaults, zero required config

The app boots with SQLite and a local file store out of the box. Postgres and S3 are options, not prerequisites. A .env.example ships with every value pre-filled for local use, and the app fails loudly with a copy-paste fix when something’s genuinely missing.

One command to deploy

Every repo ships a Dockerfile that builds a single image. No sidecars, no orchestration required for the happy path:

docker run -p 8080:8080 ghcr.io/oss-codes/postalform

Scale it later if you want. Most people never need to.

Docs that assume nothing

The README answers three questions in order: what is this, how do I run it locally, and how do I put it on the internet. No “see the wiki.” No prerequisite tribal knowledge.

Why five minutes is the bar

The gap between “cloned” and “running” is where interest goes to die. Every extra step sheds people who would have contributed, self-hosted, or told a friend. Five minutes isn’t a vanity metric — it’s the difference between a project people use and a project people star and forget.

Time your own setup sometime. If it’s over five minutes, that’s your next issue.