Akkoma Install Notes

The last couple of months have been fun! I have been building and tearing down different Fediverse instances to learn. Here’s some notes that I took while building an Akkoma instance.

Using Managed PostgreSQL

The instance is build in a VPS in Azure. I built a couple that used a local PostgreSQL database as described by the OTP installation instructions. But, with this instance being one that I am aiming to keep, I wanted to build it and have it use a Azure managed PostgreSQL database instead.

The install process is the same from the OTP installation instructions. Where it deviates is after the /tmp/setup_db.psql file is generated. That happens in this step in the instructions:

su akkoma -s $SHELL -lc "./bin/pleroma_ctl instance gen --output /etc/akkoma/config.exs --output-psql /tmp/setup_db.psql"

After that step is run, open up the /tmp/setup_db.psql file and delete the first line, which adds the akkoma user.

You’ll need to use psql to connect to your managed PostgreSQL database at this point and create the user and also give it CREATEDB permission.

With Azure managed PostgreSQL, SSL is required to connect, so I edited the /etc/akkoma/config.exs and added “ssl: true”:

config :pleroma, Pleroma.Repo,
  adapter: Ecto.Adapters.Postgres,
  username: "akkoma",
  password: "MySecretPassword",
  database: "akkoma_prod",
  hostname: "localhost"
  ssl: true

After adding the user and getting the /etc/akkoma/config.exs edited (if necessary), you can do the rest of the database setup like this:

psql -f /tmp/setup_db.psql -h HOSTNAME -U akkoma -W

The rest of the OTP installation instructions can be followed after getting the database setup.

Personal Tweaks

Instance Tweaks

Added these to the config :pleroma, :instance, section in /etc/akkoma/config.exs:

I set the remote post retention to 90 days since I don’t see myself ever looking back father than that (or even that far).

remote_post_retention_days: 90


cleanup_attachments: true

Flipped this to false since it’s my single-user instance:

registrations_open: false

Turn on Media Proxy

Flipped enabled for media proxy to true in the section config :pleroma, :media_proxy,

Install Mastodon Front End

Install Mastodon-FE (run from /opt/akkoma/). The Mastodon frontend will be at https://yourdomain/web

./bin/pleroma_ctl frontend install mastodon-fe --ref akkoma


I did this because I wanted to limit what is shown on my site to just what I posted, but based on this post from an Akkoma dev, this will help to prevent shenanigans also.

Adding this one to /etc/akkoma/config.exs will block unauthenticated users from seeing everything on my site (including my posts) which I wanted to avoid:

:instance, :public = false

Instead, the more surgical option was adding this to /etc/akkoma/config.exs:

 config :pleroma, :restrict_unauthenticated,
  timelines: %{local: false, federated: true},
  profiles: %{local: false, remote: true},
  activities: %{local: false, remote: true}

Everything local will be available to the public, everything federated/remote will be blocked unless API calls are authenticated.


Mainly notes for myself about customization:

favicon is a PNG here:


Instance logo is a PNG that goes here:


Instance thumbnail is a JPEG that goes here:


Boilerplate Terms of Service that I placed in /var/lib/akkoma/static/static/terms-of-service.html. This shows up when a visitor lands on the About page.


<b>621industries.com</b> is mookie's personal akkoma instance where he will often post about random things, but mostly about movies, tv, running and tech.
mookie's blog and movie reviews can be found at <a href="https://ultramookie.com">ultramookie.com</a>.
<b>Contact</b>: info@621industries.com


Overall network status for mookie's properties can be found at:
<a href="https://status.ultramookie.com">status.ultramookie.com</a>

<h2>Server Rules</h2>
        <li>Don't be an asshole</li>
        <li>Sexually explicit or violent media must be marked as sensitive when posting</li>
        <li>No racism, sexism, homophobia, transphobia, xenophobia, or casteism</li>
        <li>No incitement of violence or promotion of violent ideologies</li>
        <li>No harassment, dogpiling or doxxing of other users</li>
        <li>Do not share intentionally false or misleading information</li>

System Resources

I’ve noticed that beap.smp will take as much RAM as it can. When I was running with 1GB and a local PostgreSQL, things ran fine and memory usage was around 85-90% with a swap file enabled.

Currently, running on a 2GB VPS with a swap file enabled and no PostgreSQL running locally, memory usage is around 90-95%. beam.smp is using 75% of total memory.

Monitoring and Metrics

Systems metrics are collected and viewed at New Relic.

External monitoring, heartbeats and status page are done with Better Uptime.

Internal monitoring is done with monit.

Dead man’s switch monitoring is using healthchecks.io.

Alerting and paging is done through Pushover.