Documentation
Start here
Documentation is written the way the software is built: one page per job, no page pretending a decision is easier than it is. If something is not certified yet, it says so on the page where it matters.
Guides
-
Getting started
Build the binary, run
Read the guideinit, put a reverse proxy in front, and make the first federated post. -
Production deployment
The two profiles, host requirements, platform conventions, monitoring, backups and runbooks.
Read the guide -
littleMesh
Federation with no public address: nodes, lighthouses, the gateway, the directory, and the trust model.
Read the guide -
Static blogs
Turn selected public posts into a plain static site with permalinks and an Atom feed.
Read the guide -
Theming
Design tokens, the eleven built-in themes, per-account custom CSS, and contributing a theme.
Read the guide -
Security
How to report a vulnerability, what is supported, and the littleMesh trust model in full.
Read the policy -
Feature reference
Everything the server does, including the parts that are deliberately missing.
Read the reference -
Frequently asked
Who it is for, how it compares, and where to get the source.
Read the answers
The configuration file
One annotated TOML file holds everything. littlefedi init writes a
working version of it and comments out what you skipped, so the file doubles as
a reference for what you did not enable.
| Section | Covers |
|---|---|
| top level | local_domain, web_domain, low_power, background_maintenance |
[db] | SQLite path or PostgreSQL DSN, pool sizing |
[queue], [streaming] | Delivery workers, retry behaviour, streaming backend |
[http] | Listener, proxy_uri, trusted_proxies |
[media], [media.s3] | Local or S3 storage, size limits, remote cache policy |
[instance] | Name, descriptions, rules, moderation contact, terms |
[federation] | Relays, signing options, sign_with_oip |
[mesh], [lighthouse], [directory] | littleMesh node, relay and directory roles |
[web] | Public local timeline, catch-up, interface options |
[auth], [rate_limits] | Registrations, approval, verified email, MFA, limits |
[housekeeping], [backup], [cache] | Retention sweeps, built-in backups, cache sizing |
[blog] | Static blog generation |
[smtp], [push] | Outgoing mail and Web Push |
[observability] | Metrics, profiler, log detail |
Secrets do not belong in the TOML. Put them in a root-owned environment file
next to it, with mode 0640:
LITTLEFEDI_AUTH_MFA_ENCRYPTION_KEY=<openssl rand -base64 32>
LITTLEFEDI_MEDIA_PROXY_SECRET=<openssl rand -hex 32>
LITTLEFEDI_SMTP_PASSWORD=<SMTP password>
Every configuration key has an environment-variable equivalent with the
LITTLEFEDI_ prefix, which is what makes that split possible.
The command line
The same binary is the server and the administration tool. Run any command with
--help for its full option list.
| Command | What it does |
|---|---|
littlefedi | Runs the server with the given --config |
init | Interactive setup: instance or lighthouse, domains, proxy, littleMesh, instance profile |
post | Publishes standard input or a Markdown file, with visibility and blog options |
admin | Accounts, invitations, approval, suspension, domain blocks, relays, media, blogs, audit |
backup | backup now and backup restore |
mesh | id, peers, ping, publish |
self-destruct | Retires an instance deliberately, instead of leaving debris on every peer |
printf 'Hello\n' | ./littlefedi --config littlefedi.toml post
./littlefedi --config littlefedi.toml post --username alice \
--markdown --visibility private post.md
./littlefedi --config littlefedi.toml admin create-user --username alice --admin
./littlefedi --config littlefedi.toml admin refresh-actors
./littlefedi --config littlefedi.toml backup now --mediaAbout the source
Get the source archive and its SHA-256 checksum from the downloads directory. Each archive includes the build instructions, configuration examples, service files and licence notices.
Extract the archive and follow the installation guide. littleFedi is beta software; keep a backup before upgrading an existing instance.