Self Hosted:Pleroma

From Wiki
Jump to navigation Jump to search

I've decided to start using Pleroma instead of Mastodon, specifically for the lighter footprint. It was after reading this article that I made my decision.

The new instance of Pleroma will live at

Pleroma's documentation isn't the greatest, and I've learned a lot since I've started using Pleroma that's not documented anywhere else[1].


I used Pleroma's Installing on Linux using OTP releases guide.

Setup was pretty straightforward. Once Pleroma was up and running, I made sure to disable registrations and enable invitations. Since I'm not following the develop branch on Pleroma, I'm not sure the invited API in implemented yet, but I can generate invite links on the command-line.

OTP releases keep their configuration at /etc/pleroma/config.exs

config :pleroma, :instance,
    registrations_open: false,
    invites_enabled: true,

I then went through Pleroma's own security hardening guide:


Disabling Chat

To disable chat, add the following to your configuration file[2]:

config :pleroma, :chat,
  enabled: false


Custom Emoji

For the most part, Pleroma's own docs are a good start:

When I was done with Pleroma's docs, all I had was a bunch of emojis on my filesystem. The docs failed to mention that configuration is still required. So in your configuration file[2]:

config :pleroma, :emoji,
  groups: [
    Blobs: "/*.png",


Changing Default Theme

I had a bit of trouble figuring out how to change the default theme of my instance. Fortunately, there's some awfully helpful people on the fediverse to fill in the holes the documentation has.

The first thing I did was create a theme I like. I did this using Pleroma's theme web interface. Then I downloaded the JSON file and threw it on my server. The JSON file should end up in the static/themes directory. On my OTP installation, that was /var/lib/pleroma/static/static/themes/. Note: you may need to create that directory.

Now that I had my theme on the server, I needed to tell Pleroma to use it. You customize Pleroma-FE with Pleroma's BE configuration. My configuration looks somethining like this:

config :pleroma, :frontend_configurations,
  pleroma_fe: %{
    theme: "pleroma-purple"

I also had to create /var/lib/pleroma/static/static/styles.json: (I used Pleroma's default and just added my theme to it.)

You can find pleroma's default here:

Once you add your theme to styles.json, you should see it appear in the themes dropdown in your instance's settings web interface.

Default Post Content Type

config :pleroma, :frontend_configurations,
  pleroma_fe: %{
    postContentType: "text/markdown"

Where postContentType is one of:

  • text/plain - default
  • text/html
  • text/markdown
  • text/bbcode
If you have config :pleroma, :configurable_from_database, true, you'll have to make this change in /etc/pleroma/config.exs, migrate it to your database, then restart your Pleroma instance. There currently isn't a field on the Settings page in admin-fe to modify this setting.


  • I haven't found a way to default the post type for masto-fe that comes bundled with Pleroma OTP.

Instance Panel

Location for OTP installations:

  • /var/lib/pleroma/static/instance/panel.html

The default panel includes some HTML which is below so you can mimic the look:

<div style="margin-left:12px; margin-right:12px;">
    <!-- your code here -->

This is the instance panel on

<div style="margin-left:12px; margin-right:12px;">
    <p><strong>Welcome to Pleroma/!</strong></p>
    <p>This is a private instance. If you know me personally, feel free to
    contact me for an invitation.</p>
    <p><a href="/announcements">Server Announcements</a><br />
    Server Admin: <a href="/AstroBadger">@AstroBadger</a></p>
    <p><a href="/main/all">Pleroma FE</a> | <a href="/web">Mastodon FE</a> | <a href="/about">About</a></p>

MastoFE Mascot

Add something like the following to your /etc/pleroma/config.exs:

config :pleroma, :assets,
  mascots: [
    turtle: %{
      mime_type: "image/png",
      url: "/images/turtle.png"
  default_mascot: :turtle

Then be sure to place turtle.png under /var/lib/pleroma/static/images/.

Terms of Service

Most instances I've seen use the Terms of Service page as an extended instance panel.

Location for OTP installations:

  • /var/lib/pleroma/static/static/terms-of-service.html

Backup/Restore your instance


  1. Stop the Pleroma service.
  2. Go to the working directory of Pleroma (default is /opt/pleroma)
  3. Run sudo -Hu postgres pg_dump -d <pleroma_db> --format-custom -f </path/to/backup_location/pleroma.pgdump>
  4. Copy pleroma.pgdump, /etc/pleroma/config.exs, and the uploads folder to your backup destination. If you have other modifications or customization, copy those changes, too.
  5. Restart the Pleroma service.


  1. Stop the Pleroma service.
  2. Go to the working directory of Pleroma (default is /opt/pleroma)
  3. Copy the adove mentioned files back to their original position.
  4. Run sudo -Hu postgres pg_restore -d <pleroma_db> -v -1 </path/to/backup_location/pleroma.pgdump>
  5. Restart the Pleroma service.

Note Note: I've had issues restoring with the pg_restore command, so instead I've used the following command to restore Pleroma's database:

 sudo -Hu postgres psql -d pleroma < pleroma.pgdump
I've noticed it can take a very long time for postgres to recreate indexes. It might be helpful to tune postgres to your server before restoring the database.[3]
Hosting Multiple Instances on a Single Host

To do To do Write this section.


  1. besides various posts on the fediverse
  2. 2.0 2.1 /etc/pleroma/config.exs or /opt/pleroma/config/prod.secret.exs
  3. I didn't do this, and it took about an hour and a half to restore a 4G database on a fairly beefy server: 4@2.2GHz, 16G RAM, though it was painfully clear postgres wasn't using nearly as many resources as it could have.