Install Pleroma From Scratch

This guide attempts to define a secure, high quality Pleroma install. This assumes a completely bare machine, ideally as defined in the pre-server setup. If your machine is not bare, then you need to take care with every step.

DNS

For the purposes of this guide, we will assume a domain name of example.net so adjust the instructions according to your chosen domain. Assuming you have already purchased a domain name, we need to add two domains, one for the main site and one for media attachments, to your provider's DNS control panel.

Add the following two domains to your DNS pointing at your machine's IP: example.net and media.example.net. The other subdomain can have any name but just call it media dot-whatever.

Web Server Part 1

We are going to use Nginx, but you could just as easily use Caddy (very simple) or Apache.

Install Nginx: apt update && apt install -y nginx

Replace /etc/nginx/sites-enabled/default with the following:

server {
    listen 80 default_server;
    listen [::]:80 default_server;
    server_name  _;

    root   /var/www/html;

    location / {
        return 301 https://$host$request_uri;
    }

    location ^~ /.well-known/acme-challenge/ {
        default_type "text/plain";
    }
}

Verify the configuration is correct by running: nginx -t if there is no output, then there were no errors.
Reload the config using systemctl reload nginx you will not see anything yet, this is preparation.

TLS Certificate

This is a mandatory step as a TLS (SSL) certificate is required for running a server. This process will get us a free certificate and set up a cron to renew it automatically. You could use a SystemD timer for this, but the tool we're using (acme.sh) expects cron so for simplicity we're doing that. Later this guide may be updated to use a timer.

Install cron: apt install -y cron
Install acme: wget -O - https://get.acme.sh | sh -s email=myemail@example.net substituting your real email. Note that your email CANNOT have a + in it.
Reload your shell config so that the next commands will run: source ~/.bashrc

Get a TLS certificate for your server, exchanging your domains from the test ones:

SERVER=example.net

acme.sh --issue \
  -d ${SERVER} \
  -d media.${SERVER} \
  -w /var/www/html \
  --renew-hook '/usr/bin/systemctl reload nginx'

acme.sh \
        --install-cert \
        -d ${SERVER} \
        --cert-file /etc/ssl/certs/${SERVER}.cer \
        --fullchain-file /etc/ssl/certs/${SERVER}-fullchain.cer \
        --key-file /etc/ssl/private/${SERVER}.key --reloadcmd "/bin/systemctl reload nginx"

Web Server Part 2

Now we will finish up the web server component. I always do this before setting up Pleroma itself in case there are connectivity issues.

Copy my file pleroma.nginx to your server into /etc/nginx/sites-available/pleroma and edit the server_name of each entry to be your domain and media domain as appropriate, and modify the ssl key and certificate entries with your primary domain name.
Link the Nginx config: ln -s /etc/nginx/sites-available/pleroma /etc/nginx/sites-enabled/pleroma
Test the config: nginx -t if no output, no errors.
Reload the nginx config: systemctl reload nginx
In your browser, test your domain. You should get a 502 error. This is okay, Pleroma isn't installed yet, we are just verifying that the web server was set up correctly.

Pleroma User

Create a user for Pleroma: useradd -m -r -d /var/lib/pleroma -s /bin/bash pleroma

(We will disable login after we are done setting up.)

Create the location for the Pleroma install:

mkdir /opt/pleroma
chown pleroma: /opt/pleroma

Install Pleroma Dependencies

We are using the language management tool asdf to install Erlang and Elixir. This has the advantage that it's more up to date than the packaged versions. We are going to use Elixir 1.17 and OTP 26 as these are latest confirmed working.

We are also going to install every dependency for Pleroma itself.

Install language dependencies:

apt install -y build-essential autoconf m4 libncurses5-dev \
  libwxgtk3.2-dev libwxgtk-webview3.2-dev libgl1-mesa-dev \
  libglu1-mesa-dev libpng-dev libssh-dev unixodbc-dev xsltproc \
  libxml2-utils libncurses-dev automake unzip \
  --no-install-recommends

Install pleroma dependencies:

apt install git postgresql postgresql-contrib \
  cmake libmagic-dev exiftool

Log in as pleroma user: sudo su - pleroma
Install the tool "asdf": git clone https://github.com/asdf-vm/asdf.git ~/.asdf --branch v0.14.1

Install Erlang plugin for asdf:

asdf plugin add erlang https://github.com/asdf-vm/asdf-erlang.git && \
  echo 'source $HOME/.asdf/asdf.sh' >> $HOME/.bashrc`

Install Erlang:

export KERL_CONFIGURE_OPTIONS="--disable-debug --without-javac"
asdf install erlang 26.2.5.3 && \
  asdf global erlang 26.2.5.3

Install Elixir plugin for asdf: asdf plugin-add elixir https://github.com/asdf-vm/asdf-elixir.git

Install Elixir:

asdf install elixir 1.17.2-otp-26 && \
  asdf global elixir 1.17.2-otp-26

Run this command to ensure that Elixir is installed properly: iex --version

now Elixir is available on the system.

Download and configure Pleroma

Note that we are still logged in as the pleroma user.

These instructions are mostly copied from the official guide.

Clone pleroma from git: git clone -b stable https://git.pleroma.social/pleroma/pleroma /opt/pleroma
Install Pleroma's project dependencies: cd /opt/pleroma && mix deps.get
Generate config: MIX_ENV=prod mix pleroma.instance gen answer yes if asked to install rebar3. There will be a long compile time. Then, answer questions about your domain. Say yes to stripping GPS location for uploads. Also, deduplicate files, Everything else, enter the default.
Move the new config into place: mv config/{generated_config.exs,prod.secret.exs}

Modify the config to use mediaproxy. Look for this part and modify it as below, substituting your media domain:

config :pleroma, :media_proxy,
  enabled: true,
  redirect_on_failure: false,
  base_url: "https://media.example.net"

Modify the config to host images on the media domain. Find the line at the bottom like:

config :pleroma, Pleroma.Upload, filters: [Pleroma.Upload.Filter.Exiftool.StripLocation, Pleroma.Upload.Filter.Dedupe]

and replace it with:

config :pleroma, Pleroma.Upload,
  uploader: Pleroma.Uploaders.Local,
  base_url: "https://media.example.net/media/",
  filters: [Pleroma.Upload.Filter.Exiftool.StripLocation, Pleroma.Upload.Filter.Dedupe]

Note that the base_url on the second entry has /media/ appended to it.

Create VM args for starting Pleroma in location /opt/pleroma/vm.args

-name pleroma@localhost
-setcookie ooShi0jeisa7
-env ERL_MAX_PORTS 65536

Make the admin user, changing mradmin user and other settings to whatever you want them to be:

MIX_ENV=prod mix pleroma.user \
  new mradmin no@example.net \
  --name "Long User Name" \
  --moderator --admin -y

A password reset URL will be generated. Use it to reset your password and log in.

Database Setup

Exit from the pleroma user: exit
Configure the Pleroma database: sudo -Hu postgres psql -f /opt/pleroma/config/setup_db.psql
Run the database migrations: sudo -Hu pleroma bash -ic 'MIX_ENV=prod mix ecto.migrate'
Install Systemd service file: cp /opt/pleroma/installation/pleroma.service /etc/systemd/system/pleroma.service
Enable the service file: systemctl enable pleroma.service

Enable and Start Pleroma

Copy my pleroma.service file to /etc/systemd/system/pleroma.service
Enable and start it: systemctl enable pleroma && systemctl start --no-block pleroma && journalctl -u pleroma -f look for errors.
Navigate to your domain name in a browser and watch the logs. Hopefully everything worked.