Knowledgebase

Update system packages​

apt update && apt upgrade -y

Install system dependencies​

apt install git curl build-essential postgresql postgresql-contrib cmake libmagic-dev imagemagick ffmpeg libimage-exiftool-perl nginx certbot unzip libssl-dev automake autoconf libncurses5-dev

Create the Pleroma user​

For security reasons, it’s best to run Rebased as a separate user with limited access.

We’ll create this user and call it pleroma:

useradd -r -s /bin/false -m -d /var/lib/pleroma -U pleroma

Install Rebased​

It’s time to install Rebased, the backend for Soapbox. Let’s get things up and running.

Download the Rebased source code with git:

git clone -b develop https://gitlab.com/soapbox-pub/rebased /opt/pleroma

chown -R pleroma:pleroma /opt/pleroma

Enter the source code directory, and become the pleroma user:

cd /opt/pleroma
sudo -Hu pleroma bash

Install Elixir​

Install asdf:

git clone https://github.com/asdf-vm/asdf.git ~/.asdf --branch v0.10.0
echo ". $HOME/.asdf/asdf.sh" >> ~/.bashrc
echo ". $HOME/.asdf/completions/asdf.bash" >> ~/.bashrc
exec bash
asdf plugin-add erlang
asdf plugin-add elixir

Finally, install Erlang/Elixir:

asdf install

Compiling Rebased​

Install basic Elixir tools for compilation:

mix local.hex --force
mix local.rebar --force

Fetch Elixir dependencies:

mix deps.get

Finally, compile Soapbox:

MIX_ENV=prod mix compile

Generate the configuration​

It’s time to pre-configure our instance. The following command will set up some basics such as your domain name:

MIX_ENV=prod mix pleroma.instance gen

If you’re happy with it, rename the generated file so it gets loaded at runtime:

mv config/generated_config.exs config/prod.secret.exs

Exit back to the root user (for the remainder of this document):

exit

Provision the database​

The previous section also created a file called config/setup_db.psql, which you can use to create the database.

Execute the SQL file as the postgres user:

sudo -Hu postgres psql -f config/setup_db.psql

Now run the database migration as the pleroma user:

sudo -Hu pleroma bash -i -c 'MIX_ENV=prod mix ecto.migrate'

Start Rebased​

Copy the systemd service and start Soapbox:

cp /opt/pleroma/installation/pleroma.service /etc/systemd/system/pleroma.service
systemctl enable --now pleroma.service

You’re very close to being done.

Getting Online​

Requesting a Let’s Encrypt Certificate

Stop Nginx before requesting the certificate:

systemctl stop nginx

Use certbot to request a certificate with TLS SNI validation in standalone mode. Replace example.com with your domain name:

certbot certonly --standalone -d example.com

As Let’s Encrypt certificates have a validity of 90 days, a cron-job can be used to renew them and restart nginx automatically.

Create a new file and open it in a text editor like nano:

nano /etc/cron.daily/letsencrypt-renew

Copy the following content into the file, save it and exit nano:

#!/usr/bin/env bash
certbot renew
systemctl reload nginx

Allow execution of the script and restart the cron daemon. It will run the script daily:

chmod +x /etc/cron.daily/letsencrypt-renew
systemctl restart cron

Configuring Nginx​

Copy the example nginx configuration and activate it:

cp /opt/pleroma/installation/pleroma.nginx /etc/nginx/sites-available/pleroma.nginx
ln -s /etc/nginx/sites-available/pleroma.nginx /etc/nginx/sites-enabled/pleroma.nginx

You must edit this file:

nano /etc/nginx/sites-enabled/pleroma.nginx

Change all occurrences of example.tld with your site’s domain name. Use Ctrl+X, Y, Enter to save.

Finally, enable and start nginx:

systemctl enable --now nginx.service

Install Soapbox​

It’s finally time to install Soapbox itself! First, get the latest build.

curl -L https://gitlab.com/soapbox-pub/soapbox/-/jobs/artifacts/develop/download?job=build-production -o soapbox.zip

Next, unzip it.

busybox unzip soapbox.zip -o -d /opt/pleroma/instance

Post-installation

Below are some additional steps you can take after you’ve finished installation.

Create your first user

If your instance is up and running, you can create your first user with administrative rights with the following task:

cd /opt/pleroma
sudo -Hu pleroma bash -i -c 'MIX_ENV=prod mix pleroma.user new username your@emailaddress --admin'

Congrats, you’re done! Check your site in a browser and it should be online.

To upgrade Rebased (the backend), shell into your server

Stop the Pleroma service as root

systemctl stop pleroma

Go to the working directory of Pleroma

cd /opt/pleroma

sudo -Hu pleroma bash

git pull origin develop

Pull in any new dependencies

MIX_ENV=prod mix deps.get

This task performs database migrations, if there were any.

MIX_ENV=prod mix ecto.migrate

Exit to root

exit

Start the Pleroma service

systemctl start pleroma

To upgrade Soapbox (frontend), shell into your server and run-run the install commands

curl -O https://dl.soapbox.pub/main/soapbox.zip

busybox unzip soapbox.zip -o -d /opt/pleroma/instance/static