Installing Soapbox
Ready to run your own server? You can install it from scratch on a Linux machine, or pay for managed hosting.
- Managed hosting - you pay someone to install and manage the server. Great for novices and busy people.
- Self-hosting - you install and manage your own server. Preferred if you want total freedom and control.
Option 1: Managed hosting by Btrf.ly
Btrf.ly (pronounced Butterfly) provides managed hosting for Soapbox servers. This is the easiest way to get started, as you can ignore pretty much the whole rest of this install guide and go through their checkout process instead.
Get started with Btrf.lyThis is an affiliate link.
Option 2: Installing on a VPS
We recommend installing Soapbox on a dedicated VPS (virtual private server) running Ubuntu 22.04 LTS. You should get your VPS up and running before starting this guide.
Some popular VPS hosting providers include:
- DigitalOcean[affiliate link] — easy to use
- Hetzner Cloud — cheap
- BuyVM — supports free speech
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. Create an A record with your registrar pointing to the IP address of your VPS.
1. Shelling in
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.
ssh root@123.456.789
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 98.198.61.119
root@gleasonator:~#
2. System setup
Before installing Soapbox, we have to prepare the system.
2.a. 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.
2.b. 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
2.c. 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
3. Install Rebased
It’s time to install Rebased, the backend for Soapbox. Let’s get things up and running.
3.a. 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.)
3.b. 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. ☕)
3.c. 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. ☕)
3.d. 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
3.e. 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'
3.f. 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.
4. 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.
4.a. 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.
4.b. 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.
5. 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!
6. 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'
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 run-run the install commands.
curl -O https://dl.soapbox.pub/main/soapbox.zip
busybox unzip soapbox.zip -o -d /opt/pleroma/instance/static
Questions
If you have questions or run into trouble, please create an issue on the Soapbox GitLab.