How to run Oasis, a Secure Scuttlebutt client, on a remote server

published: 2021-11-13

This tutorial assumes you already have a functioning Node.js and Caddy installation.

Install Oasis.

git clone https://github.com/fraction/oasis.git
cd oasis
npm install

Test the installation by running node . (yes, including the period).

If the output stops after a few lines and isn't an obvious Node error, hit Control and C at the same time to exit; you're ready for the systemd file.
If you get an error about port 3000 already being in use, use the command node . --port PORTNUMBER instead, where PORTNUMBER is any open port you want.

If your instance immediately throws an error about ssb.friends.get:

git checkout 4e8f7426a4eb1d95f6e55cf894a3168f523f8af8
rm -rf node_modules
npm install

Prepare the systemd daemon file.

Edit /lib/systemd/system/oasis.service as root with your favorite text editor. Paste the following:

[Unit]
Description=Oasis client for Secure Scuttlebutt
After=network.target

[Service]
User=YourUsername
Group=YourUsername
ExecStart=/path/to/your/node/binary . --port 8787
WorkingDirectory=/path/to/where/you/cloned/oasis/
TimeoutStopSec=5s
LimitNOFILE=1048576
PrivateTmp=true
ProtectSystem=full

[Install]
WantedBy=multi-user.target

Replace /path/to/your/node/binary with whatever comes up when you run which node. You may need to change this if you update Node.

Edit your Caddyfile. (This will probably also require root.)

yourdomain.tld {
	reverse_proxy 127.0.0.1:PORTNUMBER {
		header_up Host 127.0.0.1
		header_up Referer http://localhost
	}
	basicauth * {
		AnyUsernameYouWant EXTREMELYLONGCADDYHASHHERE
	}
}

EXTREMELYLONGCADDYHASHHERE is used instead of an actual password so you don't have cleartext credentials hanging around. Generate this with caddy hash-password. Make sure you save your actual password in a password manager, as you can't reverse a hash!

The header_up lines are there to trick Oasis into thinking it is running on a local machine, as it (very aggressively) wants to be. Normally this would be true, as Secure Scuttlebutt is peer-to-peer and intended to be run on a personal device that may see intermittent internet connectivity. However, if you're looking at this tutorial, you probably want to host a public peer as an actually functioning alternative to a pub or room.

Get everything running.

sudo systemctl daemon-reload
sudo systemctl restart caddy
sudo systemctl start oasis && sudo systemctl enable oasis