# 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.

1. 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`

2. 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.

3. 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.

4. Get everything running.

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

CC BY-NC-SA 4.0 © Vane Vander