Zach Alberico

Urbit In The Cloud

June 6, 2020

What is this guide?

The goal of this guide is to have clear and easy to follow best practices for deploying your urbit to a server you control in the cloud. This guide uses Digital Ocean as the cloud provider because DO focuses on this kind of use case (individual devs running something for themselves) and it's what I personally use.

Most Urbit users start out running their ship on their laptop in order to play with it, but this means when your laptop is offline your urbit is offline too (and can't get updates or keep hosting a group). You can also only access your urbit from that one laptop. In order to access your urbit from anywhere and any device, you need it running on a computer that's always online and accessible from your other devices. The way to do this is hosting it somewhere.

If you want a hosted urbit, but don't want to manage it yourself you can sign up for hosting on tlon.network. If you want to host your urbit on a spare computer that's always online on your home network check out Native Planet and their software that makes this easy (using tailscale is another option for this approach). For everyone else, running on Digital Ocean is a good option and this guide wil help you do that.

This guide assumes you're running macOS or linux on your local machine.

Create a Digital Ocean droplet

Create an account on Digital Ocean.
Create a droplet with the following settings:
Region: Choose the closest to you
Image: Ubuntu (Latest Version)
Plan: Basic
Size: $24 (4GB/2CPU)
Authentication: SSH keys, add a New SSH Key following the instructions DO gives you.
How many Droplets: 1
Choose a hostname: This will be the hostname of the box you ssh into (can be whatever you want, I used my planet name).
Add tags: None
Project: It'll select your default.
Backups: Optional (it costs a little extra, but I have it enabled for peace of mind).

Getting your own domain

Your own domain will make accessing your urbit a lot easier (it'll also allow you to secure things with a Let's Encrypt cert). Domains are relatively inexpensive and since this guide is about best practices I'm making it a required step.

There are a lot of domain name registrars you can use, this guide suggests gandi.net because that's the one I use. From there you can search for and register a domain that you like.

Configuring your domain for your Digital Ocean droplet

Once you've registered your domain you'll need to configure it to use Digital Ocean for DNS. The following steps are done on the Gandi website.

Click Domain on the left panel
Click the domain you're going to use
Click "Gandi's LiveDNS" under Nameservers in the Domain configuration section of the overview page
Click Change
Click External
Add the Digital Ocean nameservers:
- ns1.digitalocean.com
- ns2.digitalocean.com
- ns3.digitalocean.com
Save the change.
It can take 12-24 hours for this change to propagate.
Now that you've updated the DNS records you can add the domain to your droplet.
Back on the DO site, click Networking from the left panel and then enter the domain you registered.
Click on that domain and add an A record that directs to the IP of your droplet (found on your droplet's page).

Creating your non-root user

With our domain in place we're now ready to actually log into the box and start to configure the server itself.

Since we don't yet have a user we'll need to log in as root:
```
$ ssh root@your_server_ip
```
If you set a passphrase on your ssh key, you'll be asked for it. If not, you should automatically be logged in.
Create a new user, in our example we'll use sammy (to match the DO docs), but you should use your own username:
```
# adduser sammy
```
Enter a strong password for your user. The questions adduser asks you don't matter, hit enter to skip them.
Give your new user sudo access:
```
# usermod -aG sudo sammy
```
Next we need to enable external access to our new user by moving the ssh key over from root (and setting proper permissions on it).
Be careful to note the lack of trailing slash in the command below after /.ssh:
```
# rsync --archive --chown=sammy:sammy ~/.ssh /home/sammy
```
Test this connection with ssh sammy@your_server_ip from your local machine in a new terminal window.
To test that your domain is working try ssh sammy@your_domain from a new terminal on your local machine.
You should now be able to use this user going forward with sudo when necessary.

Setting up a basic firewall

Continuing to follow the DO docs we're going to configure the ufw firewall.

The below command shows us the applications available to be easily configured with firewall rules by ufw.
```
$ sudo ufw app list
```
Next we'll configure ufw to allow connections via ssh when the firewall is enabled.
```
$ sudo ufw allow OpenSSH
```
This command will allow UDP connections on a port that we'll later tell your urbit to use for Ames (the Urbit to Urbit communication protocol)
```
$ sudo ufw allow 32123/udp
```
Next we'll turn on the firewall.
```
$ sudo ufw enable
```
To see the current the current firewall status use the following.
```
$ sudo ufw status
```

Installing Nginx

Nginx is a webserver we're going to use as a reverse proxy. All incoming traffic to our Digital Ocean droplet will pass through Nginx and from there to your urbit. This allows us to lock everything else down and secure just that entry point.

First we need to update available packages and install Nginx.
```
$ sudo apt update
$ sudo apt install nginx
```
Now that we've installed Nginx we have to update the firewall settings:
```
$ sudo ufw allow 'Nginx Full'
```
You can verify this change with:
```
$ sudo ufw status
```
Nginx should automatically be started after installation, you can confirm this with:
```
$ systemctl status nginx
```
You can also confirm that it's up by going to your droplet's IP address, you should see a "Welcome to nginx!" message.
You can start/stop/restart Nginx with commands like the following:
```
$ sudo systemctl restart nginx
```
You can also reload config without restarting with:
```
$ sudo systemctl reload nginx
```

Configuring Nginx

Now we're going to configure Nginx so it serves up your urbit traffic securely.

Navigate to the sites-available directory:
```
$ cd /etc/nginx/sites-available
```
Create a new file for your domain:
```
$ sudo vim your_domain
```

Add the following config (putting your domain in the your_domain location, your_domain should be of the form example.com without www or https.):

server {
 server_name your_domain;

 location / {
     proxy_pass http://localhost:8080;
     proxy_set_header Forwarded for=$remote_addr;
     proxy_set_header Connection '';
     proxy_http_version 1.1;
     chunked_transfer_encoding off;
     proxy_buffering off;
     proxy_cache off;
 }
}

Next we're going to create a symlink to enable this in sites-enabled for Nginx:

$ sudo ln -s /etc/nginx/sites-available/your_domain /etc/nginx/sites-enabled/your_domain

Now reload the Nginx config:
```
$ sudo nginx -s reload
```

Configuring Let's Encrypt secure certificate

Now that we've got the Nginx reverse proxy installed we're going to get a Let's Encrypt SSL cert for it and configure it to automatically renew.

First we're going to install the certbot package:
```
$ sudo apt install python3-certbot-nginx
```
Next we're going to request a cert from certbot:
```
$ sudo certbot --nginx -d your_domain
```

Note: If this fails it may be because your DNS change has not propagated which can take 12-24 hours.

You'll have to agree to the TOS and then it'll run a test to verify that you control the domain you're requesting a cert for.
Certbot will then ask if you want to redirect all traffic to HTTPS. You should select yes for this (option 2).
Certbot will automatically update your Nginx config with the settings it needs. It'll also automatically renew before cert expiration.
You can now verify your site is working properly by going to https://your_domain, you should see a secure certificate.
To confirm that certbot will renew properly you can run the following command:
```
$ sudo certbot renew --dry-run
```

Installing Urbit

Finally we're ready to install Urbit on your very own server. This part is actually pretty easy, if you haven't installed Urbit locally then the instructions are the exact same as the ones in the Urbit getting started guide. If you have a local ship already we'll send your local ship up.

WARN: Since Urbit is p2p you never want to run two copies of your ship simultaneously or ever start up an old copy. This is because other nodes that interact with each of your copies will be confused by which one is the most up to date. If you end up accidentally doing this you'll have to do a 'personal breach' (or factory reset) described in the Urbit docs to fix things.
The first thing you're going to want to do is shut down your local ship, either with control-d or |exit in dojo.

Now we're going to tar up your local ship and send it to your server, from your local machine's urbit directory:

$ tar -zcvf <ship_dir_name>.tar.gz <ship_dir_name>
$ scp <ship_dir_name>.tar.gz  your_user@your_domain:/home/your_user

Back on your server let's untar your ship and start it up with the Ames port we allowed through the firewall:
```
$ ssh your_user@your_domain
$ tar -zxvf <ship_dir_name>.tar.gz
$ ./<ship_dir_name>/.run -p 32123
```
NOTE: If you're moving your ship from macOS to linux then .run will fail because you need to dock the linux binary instead of the macOS binary. To do that, you'll want to download the linux binary from the getting started guide and follow the instructions linked in Step 5 on that page to dock the linux binary.
Your ship should now be sailing on the digital ocean. Check https://your_domain, if everything is working properly you should see a login page.
Log in with the code from +code in dojo like normal and you should see all of your applications.

Leaving your urbit running in a Screen session

Finally, to leave your urbit running after you disconnect we can leave it in a Screen session. This is just a way to leave applications running in the background and then reconnect to them later. Alternatively, the same can be done with tmux.

First start with your ship stopped, then run the following:
```
$ screen -S urbit
```
This will start a screen session, we can now start up your urbit ship in this session from your urbit directory:
```
$ ./<ship_dir_name>/.run -p 32123
```
Then we can disconnect from the screen session and leave the ship running with control-a d
To get back into the screen session:
```
$ screen -r
```
There are more screen commands for interacting with sessions that are easy to find on the internet.

Links and Misc.

A lot of the above documentation comes from combining existing resources from Digital Ocean and Urbit into a single guide. The main piece here that I had to figure out myself was the specific Nginx config required to get Urbit to work properly.

Nginx is also pretty powerful and configurable. You can do things like have your urbit on an existing server under a subdomain. That kind of thing is left as an exercise for the reader.

On iOS you can save a website to your homescreen as an icon. If you do this for your urbit domain it's a little like having it as an app.

For the docs that made up this guide see the following links.