We recommend installing Soapbox on a dedicated VPS (virtual private server) running Ubuntu 20.04 LTS. You should get your VPS up and running before starting this guide.
Some popular VPS hosting providers include:
Expect to spend between $10–15 USD/mo, depending on the size of your community and how you choose to configure it.
You should already have a domain name from a registrar like Namecheap.
A record with your registrar pointing to the IP address of your VPS.
Once your VPS is running, you'll need to open a terminal program on your computer. This will allow you to remotely connect to the server so you can run commands and install Soapbox.
Linux and Mac users should have a terminal program pre-installed (it's just called "Terminal"), but Windows users may need to install Cygwin first.
Once the terminal is open, connect to your server with the username and IP address provided by your VPS host. It will likely prompt for a password.
If you see a screen that looks like this, you've succeeded:
Welcome to Ubuntu 20.04.2 LTS (GNU/Linux 5.4.0-65-generic x86_64) * Documentation: https://help.ubuntu.com * Management: https://landscape.canonical.com * Support: https://ubuntu.com/advantage System information as of Wed Apr 28 18:59:27 UTC 2021 System load: 1.86 Processes: 201 Usage of /: 66.1% of 146.15GB Users logged in: 0 Memory usage: 29% IPv4 address for ens18: 10.0.0.100 Swap usage: 4% IPv4 address for ens19: 192.168.1.100 * Pure upstream Kubernetes 1.21, smallest, simplest cluster ops! https://microk8s.io/ 79 updates can be installed immediately. 0 of these updates are security updates. To see these additional updates run: apt list --upgradable Last login: Tue Apr 27 17:28:56 2021 from 126.96.36.199 root@gleasonator:~#
Before installing Soapbox, we have to prepare the system.
Usually a fresh VPS already has outdated software, so run the following commands to update it:
apt update apt upgrade
When prompted (
Y and hit Enter.
Soapbox relies on some additional system software in order to function. Install them with the following command:
apt install git build-essential postgresql postgresql-contrib cmake libmagic-dev imagemagick ffmpeg libimage-exiftool-perl nginx certbot unzip libssl-dev automake autoconf libncurses5-dev
For security reasons, it's best to run Soapbox as a separate user with limited access.
We'll create this user and call it
useradd -r -s /bin/false -m -d /var/lib/pleroma -U pleroma
It's time to install Soapbox itself. Let's get things up and running.
Download the Soapbox source code with git:
git clone -b soapbox-v1.1.1 https://gitlab.com/soapbox-pub/soapbox /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.)
Soapbox uses the Elixir programming language (based on Erlang). It's important we use a specific version of Erlang (23), so we'll use the asdf version manager to install it.
git clone https://github.com/asdf-vm/asdf.git ~/.asdf --branch v0.8.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:
(This will take about 15 minutes. ☕)
Install basic Elixir tools for compilation:
mix local.hex --force mix local.rebar --force
Fetch Elixir dependencies:
Finally, compile Soapbox:
MIX_ENV=prod mix compile
(This will take about 10 minutes. ☕)
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
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):
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'
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 Soapbox server is running, and you just need to make it accessible to the outside world.
The last step is to make your server accessible to the outside world. We'll achieve that by installing Nginx and enabling HTTPS support.
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
<yourdomain> with real values.
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:
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.
Below are some additional steps you can take after you've finished installation.
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'
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/
If you have questions or run into trouble, please create an issue on the Soapbox GitLab.