The goal of this guide is to have clear and easy to follow best practices for deploying an Urbit node to a server you control in the cloud. Deploying in the cloud allows you to access your Urbit from any device.

Most Urbit users start out running their ship locally on one machine in order to play with it, but this means when your machine is offline your Urbit node is offline too (and can't get updates). You can also only access your Urbit from that one machine.

This guide uses Digital Ocean as the cloud provider, but others can be used. If using another provider, the setup script provided and other server configuration instructions may need to be modified or done manually.

1. Create a Droplet

Create an account on Digital Ocean. Once you make an account, choose "Deploy a virtual machine".

You should see the page below where you can create your Droplet, aka Virtual Machine:

Fill out the options like so:

Image

Ubuntu 22.04 x64

Plan

• Shared CPU: Basic
• CPU options: Regular with SSD
• 2GB / 1 CPU ($12/mo)

You can choose a more powerful option if you'd like but the $12 option should be sufficient. Note Urbit needs 2GB of memory; it's possible to choose a cheaper option and run it with less memory by using swap but it will impact performance.

Add block storage

The $12 plan includes 50GB which should be sufficient for quite some time, so you can skip this.

Datacenter region

Choose the region closest to you.

VPC Network

Leave this as default.

Authentication

In the "Authentication" field, select "SSH keys" and hit "New SSH Key". Run the following command in the terminal on your local machine, replacing riclen-tinlyr with the name of your ship (sans the leading ~):

SHIP="riclen-tinlyr" bash -c 'ssh-keygen -q -N "" -C $SHIP -f ~/.ssh/$SHIP && cat ~/.ssh/$SHIP.pub'

It should spit out a long string of letters and numbers beginning with ssh-rsa and ending with your ship name. Copy the whole thing and paste it into the "SSH key content" field on Digital Ocean. In the "Name" field, enter your ship name.

Additional options

Click "User data" and paste the script below into the field provided. This will automatically configure the server and install necessary software.

#!/bin/bash

# configure swap
fallocate -l 2G /swapfile
chmod 600 /swapfile
mkswap /swapfile
swapon /swapfile
echo "/swapfile swap swap defaults 0 0" >> /etc/fstab

# setup firewall
ufw allow OpenSSH
ufw allow www
ufw allow https
ufw allow 34543/udp
ufw enable

# create and configure user
useradd -s /bin/bash -d /home/urbit -m -G sudo urbit
passwd -d urbit
echo "urbit ALL=(ALL) NOPASSWD:ALL" >> /etc/sudoers

# configure ssh keys for user
mkdir -p /home/urbit/.ssh
chmod 700 /home/urbit/.ssh
cp /root/.ssh/authorized_keys /home/urbit/.ssh/authorized_keys
chmod 600 /home/urbit/.ssh/authorized_keys
chown -R urbit:urbit /home/urbit/.ssh

# configure sshd
mkdir -p /etc/ssh/sshd_config.d
cat > /etc/ssh/sshd_config.d/override.conf <<EOF
PermitRootLogin no
PubkeyAuthentication yes
PasswordAuthentication no
EOF

# fetch and extract urbit binary
curl -L https://urbit.org/install/linux64/latest | tar xzk --strip=1 -C /home/urbit/
chown urbit:urbit /home/urbit/urbit

# install necessary packages
apt install -y debian-keyring debian-archive-keyring apt-transport-https
curl -1sLf 'https://dl.cloudsmith.io/public/caddy/stable/gpg.key' | gpg --dearmor -o /usr/share/keyrings/caddy-stable-archive-keyring.gpg
curl -1sLf 'https://dl.cloudsmith.io/public/caddy/stable/debian.deb.txt' | tee /etc/apt/sources.list.d/caddy-stable.list
apt -y update
apt install -y caddy tmux

# reboot
systemctl reboot

How many Droplets?

1

Choose a hostname

This will be the name the server calls itself locally, you can put in whatever you want. Your planet name is a good choice.

Add tags

Leave empty.

Select project

Leave as the default.

Create Droplet

Hit this button to create the droplet.

2. Get domain

To access your ship easily from any device, it's necessary to have a domain name. You can either buy one from a domain registrar like gandi.net, Namecheap, etc, or you can get a free subdomain from a site like freedns.afraid.org.

In this guide, we'll walk through the second free option, but if you'd prefer your own, you just need to add an A Record pointing to your droplet's public IP address.

Go to freedns.afraid.org and sign up. Once done, log in and select the "Subdomains" option in the menu on the left. Choose to add a new one, and you'll be presented with a screen like so:

You can put anything in the "Subdomain" field, but typically you'd put your planet name. You can choose whichever domain option you'd like. In the "Destination" field, you'll need to put the public IP address of your droplet, which you can get from the dashboard on Digital Ocean.

Once you hit "Save", the configuration is complete:

3. Prepare for upload

• If you're running from the command line
• If you're using Port

In the Dojo, use either "CTRL + D" or |exit to shut down your ship.

Archive your pier by running tar cvzf riclen-tinlyr.tar.gz ~/path/to/your/pier (substitute your own ship name and pier location).

4. Connect to the server

To make connecting simple, you can add an alias to ~/.ssh/config on your local machine. Open ~/.ssh/config in an editor (you may need to create it if the file doesn't exist), and add the following to the bottom of the file (replacing the ship name and IP address with your own):

Host riclen-tinlyr
  HostName 161.35.148.247
  User urbit
  IdentityFile ~/.ssh/riclen-tinlyr
  IdentitiesOnly yes

• If you have an existing pier
• If you have a key file

Copy the archived pier to the server with the following (substituting your ship name and Host):

scp riclen-tinlyr.tar.gz riclen-tinlyr:

It may take a while to upload if your pier is large and/or your internet is slow.

Finish server configuration

Once you've either uploaded your pier or uploaded your key file as the case may be, you can connect to your server:

ssh riclen-tinlyr

You'll be taken to the shell on your server. In order to complete the domain name setup, you need to edit the config file of the caddy reverse-proxy web-server. Run the following two commands in the droplet's shell (replacing the domain with the one you chose previously):

echo -e "riclen-tinlyr.crabdance.com \n  reverse_proxy 127.0.0.1:8080" | sudo tee /etc/caddy/Caddyfile > /dev/null
sudo systemctl restart caddy

5. Boot your ship

• If you have an existing pier
• If you have a key file

In the previous section you ssh'd into the server and configured Caddy. In the same ssh session, extract the pier archive you previously uploaded, then delete the archive:

tar xvzf riclen-tinlyr.tar.gz && rm riclen-tinlyr.tar.gz

You'll now have a folder called riclen-tinlyr, which is your pier. Urbit is best run in a tmux or screen session so it's easy to keep it running when you disconnect. In this case we'll use tmux, which has already been installed by the setup script.

Run tmux:

tmux

You should now be in tmux. First, dock your ship:

./urbit dock riclen-tinlyr

That will copy the urbit runtime inside the pier, so you can now delete the separate binary:

rm urbit

Now you can boot your ship, specifying the Ames UDP port which was configured in the firewall by the setup script:

./riclen-tinlyr/.run --http-port 8080 -p 34543

It'll take a few moments to boot, and then your ship should be running like normal and you'll be at the usual Dojo prompt. If you haven't previously noted your web login code, you'll need to run +code in the Dojo and copy it. Then, you can disconnect from the tmux session by hitting CTRL+b d (that is, you hit CTRL+b, release it, and then hit d). This will disconnect you from tmux and take you back to the usual shell, but it'll keep running in the background. If you want to get back to the Dojo again, you can reattach the tmux session with:

tmux a

Finally, you can disconnect from the ssh session completely by hitting CTRL+d.

6. Log in to Landscape

The server configuration should now be complete, and you can access Landscape in the browser. Navigate to the domain you configured previously, in this case riclen-tinlyr.crabdance.com. You should see the Landscape login screen:

Before logging in, check that the URL in the browser begins with https, and that it has a lock icon or similar next to it. This means Caddy has successfully configured its SSL certificates. If there's no lock and you're at http://... (without the s), Caddy has not yet setup the certificates. You may need to give it some time and try again. Otherwise, enter the web login code you previously got with the +code command in the Dojo, and you'll be taken to your ship's homescreen.

Your ship is now running in the cloud, and you can access it from any device by visiting its URL.

7. Cleanup

If you booted a new ship by uploading a key file, it's a good idea to now delete the key file on your local machine.

If you uploaded an existing pier, you should delete the old copy of both the pier directory and the .tar.gz archive on your local machine. You might be tempted to keep one of these as a backup, but note that you must never again boot the old copy on the live network. Doing so will create unfixable networking problems and require you to perform a factory reset through Bridge, wiping your ship's data. We therefore don't recommend you keep duplicates of your pier lying around.