Installing Soapbox

make sure to be the root user

sudo su

System setup

Before installing Soapbox, we have to prepare the system.

Install updates

Usually a fresh VPS already has outdated software, so run the following commands to update it:

apt update

apt upgrade

When prompted ([Y/n]) type Y and hit Enter.

Install system dependencies

Soapbox relies on some additional system software in order to function. Install them with the following command:

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 fasttext

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.

Downloading the source code

Download the Rebased source code with git:

git clone 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

(You should be the pleroma user in /opt/pleroma for the remainder of this section.)

Install Elixir

Rebased uses the Elixir programming language (based on Erlang). It’s important we use a specific version of Erlang (24), so we’ll use the asdf version manager to install it.

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

(This will take about 15 minutes. ☕)

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

(This will take about 10 minutes. ☕)

Generate the configuration

It’s time to preconfigure 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

Provision the database

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

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

exit

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

If you’ve made it this far, congrats! You’re very close to being done. Your Rebased server is running, and you just need to make it accessible to the outside world.

Getting online

The last step is to make your server accessible to the outside world. We’ll achieve that by installing Nginx and enabling HTTPS support.

HTTPS

We’ll use certbot to get an SSL certificate.

First, shut off Nginx:

systemctl stop nginx

Now you can get the certificate:

mkdir -p /var/lib/letsencrypt/

certbot certonly --email your@emailaddress -d yourdomain --standalone

Replace your@emailaddress and yourdomain with real values.

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

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

Install Soapbox

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

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

Next, unzip it.

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

Refresh your website. That’s it!

Post-istallation

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'

Renewing SSL

If you need to renew the certificate in the future, uncomment the relevant location block in the nginx config and run:

certbot certonly --email your@emailaddress -d yourdomain --webroot -w /var/lib/letsencrypt/

Upgrading

To upgrade Rebased (the backend), shell into your server and issue the following commands.

sudo -Hu pleroma bash

cd /opt/pleroma

git pull origin main

asdf install

mix deps.get

MIX_ENV=prod mix ecto.migrate

exit

systemctl restart pleroma

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

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

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