Urbit Operators
  • Urbit OS

    • Basics
    • Updates
    • Configuring S3 Storage
    • Shell
    • Filesystem
    • Star and Galaxy Operations
    • Ship Troubleshooting
    • Dojo Tools
    • Urbit ID

      • Overview
      • Using Bridge
      • Proxies
      • HD Wallet (Master Ticket)
      • Bridge Troubleshooting
      • Creating an Invite Pool
      • Guide to Factory Resets
      • Layer 2 for planets
      • Layer 2 for stars
      • Running Urbit

        • Runtime Reference
        • Cloud Hosting
        • Self-hosting S3 Storage with MinIO
        • Coturn Operator Guide
        Urbit Operators
        • Urbit OS

          • Basics
          • Updates
          • Configuring S3 Storage
          • Shell
          • Filesystem
          • Star and Galaxy Operations
          • Ship Troubleshooting
          • Dojo Tools
          • Urbit ID

            • Overview
            • Using Bridge
            • Proxies
            • HD Wallet (Master Ticket)
            • Bridge Troubleshooting
            • Creating an Invite Pool
            • Guide to Factory Resets
            • Layer 2 for planets
            • Layer 2 for stars
            • Running Urbit

              • Runtime Reference
              • Cloud Hosting
              • Self-hosting S3 Storage with MinIO
              • Coturn Operator Guide
              Operator's Manual/Running Urbit

              Cloud Hosting

              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:

              do screenshot

              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/linux-x86_64/latest | tar xzk --transform='s/.*/urbit/g' -C /home/urbit/
              chown urbit:urbit /home/urbit/urbit
              # install tmux
              apt -y update
              apt install -y 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. Prepare for upload

              Note

              This step is necessary if you already have a ship running locally and want to move it to the cloud. If you don't, you can skip this step.

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

              3. 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 with your own and the IP address with that of your droplet):

              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.

              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.

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

              Run the following to allow the runtime to bind ports 80 and 443:

              sudo setcap 'cap_net_bind_service=+ep' riclen-tinlyr/.run

              Now you can start your ship up with the following:

              ./riclen-tinlyr/.run -p 34543

              After a few moments it'll show the Dojo prompt like ~riclen-tinlyr:dojo>.

              6. Get a domain

              To make accessing the web interface convenient, you should request an arvo.network domain name. To do so, run the following command in the Dojo, replacing the IP address with your droplet's:

              -dns-address [%if .161.35.148.247]

              This will request a subdomain of your ship like riclen-tinlyr.arvo.network.

              The domain should be registered almost instantly, but sometimes it takes a while for it to propagate to other DNS servers. You might therefore see the following:

              > -dns-address [%if .161.35.148.247]
              dns: request for DNS sent to ~deg
              dns: awaiting response from ~deg
              http: fail (13, 504): unknown node or service
              http: fail (14, 504): unknown node or service
              http: fail (15, 504): unknown node or service
              http: fail (16, 504): unknown node or service
              http: fail (17, 504): unknown node or service
              dns: unable to access via riclen-tinlyr.arvo.network
              XX confirm port 80
              XX check via nslookup
              0

              If that happens, wait five or ten minutes and then try again. You should eventually see:

              > -dns-address [%if .161.35.148.247]
              dns: request for DNS sent to ~deg
              dns: awaiting response from ~deg
              [%key iter=0 width=2.047]
              [%key iter=1 width=2.047]
              [%key iter=2 width=2.047]
              [%key iter=3 width=2.047]
              acme: requesting an https certificate for riclen-tinlyr.arvo.network
              dns: confirmed access via riclen-tinlyr.arvo.network
              0
              acme: received https certificate for riclen-tinlyr.arvo.network
              http: restarting servers to apply configuration
              http: web interface live on https://localhost:443
              http: web interface live on http://localhost:80
              http: loopback live on http://localhost:12321

              That means the domain has been registered and an SSL certificate has been installed, so you can access the web interface securely with HTTPS.

              7. Log in to Landscape

              In order to login to the web interface, you need to get the web login code. Run the following in the Dojo:

              +code

              It'll spit out something like ropnys-batwyd-nossyt-mapwet. That's your web login code, you can copy that and save it in a password manager or similar. Note that the web login code is separate from the master ticket.

              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.arvo.network. You should see the Landscape login screen:

              landscape login screen

              Enter the web login code 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.

              8. Disconnect

              You can now disconnect from the tmux session by hitting CTRL+b d (that is, you hit CTRL+b, release it, and then hit d). You'll be taken back to the ordinary shell, but the ship will still be 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.

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