akkoma is a really cool and good^{[citation needed]} fedi software, but it can be incredibly confusing to maintain and update, and updating is often not an option. i believe that at least some of these hassles and headaches can be sidestepped entirely by setting up your initial installation more methodically, and over the course of administraing 8 instances and working on akkoma’s frontend and backend, i’ve honed down a technique that makes editing configuration files easy, safe and portable, is less vulnerable to data loss, and only takes me around 20 minutes to set up.

this is not a complete guide! the official installation docs are for the most part usable. this is just a collection of deviations from the main path.

min-maxing :configurable_from_database

akkoma has two ways to be configured: the config/prod.secret.exs file, and the optional database configuration. for all intents and purposes, database configuration should be considered useless at best. it’s harder to parse, harder to edit, and if you forget to back up your database it’s also harder to retrieve.

however, the only current way to interactively add emoji to your instance is through admin-fe, and for admin-fe to behave we need to enable :configurable_from_database. the solution, therefore, is to write all of our config on file, enable admin-fe, then not touch anything ever.

config :pleroma, configurable_from_database: true

hosting images on a subdomain (if you don’t trust your users)

i honestly don’t know how this hasn’t made its way to the main installation docs. media uploads on the same domain as the instance itself have enabled exploits and vulnerabilities more than once before.

if you run a private instance, you don’t have to worry about it. if you use MediaProxy, you absolutely do.

Pleroma.Upload, :uploader, :base_url: "https://media.example.org"

actually, just follow everything on the hardening guide. they’re sane defaults that aren’t default for some reason.

enable static-fe

ok this one’s kind of an ego thing.

to summarize, static-fe was Horrible, so when akkoma forked we turned it off by default. but then I MADE IT GOOD AGAIN. you should enable it to make me proud.

config :pleroma, :static_fe, enabled: true

tuning log noise

by default akkoma spits info and above to ExSyslogger (journalctl, /var/log/messages, etc.). this can be a bit noisy. luckily, akkoma lets us provide different log levels for headless vs. console:

config :logger,
  backends: [:console, {ExSyslogger, :ex_syslogger}]
config :logger, :console, level: :debug
config :logger, :ex_syslogger, level: :warn, ident: "akkoma example.org"