hello world: Urbit edition

Install, boot, and run your Urbit planet on a $10 cloud server

urbit live
5 min readJun 3, 2019
Photo by SpaceX on Unsplash

Updated for the latest Urbit release: v0.10.7

Current as of June 28, 2020 — release notes

Urbit planet user guides

These guides assume that you already own an Urbit planet and have downloaded its keyfile from Bridge. Looking for a planet? There are over a million planets available to purchase instantly on our planet market.

As always, if you encounter any issues refer to Urbit’s documentation and pepper us with questions in our Telegram group.

Each guide builds on the one before it.

Create a Digital Ocean droplet

Select these options:

  • Image: Ubuntu 18.04 x64
  • Plan: Standard
  • Size: $10/mo (2 GB / 1 CPU)
  • Backups: none
  • Block storage: none
  • Datacenter region: any (Choose the one nearest to your location)
  • Additional options: none
  • SSH keys: none*
  • Hostname: any string (We suggest using your planet’s name, e.g. “magmyr-darlex”)

*We HIGHLY recommend that you configure an SSH key to authenticate with your droplet. In this post we are bending the rules in the name of “hello world”.

Install, boot, and disconnect

Step 0: Connect to the droplet

ssh root@<droplet ip address> 

Don't include the angle brackets, i.e. ssh root@123.45.67.890

If you don’t have an SSH key configured, you will first be prompted to enter the droplet’s root password that was emailed to you. That will be followed by another prompt to create your own password.

Step 1: Configure the droplet and install Urbit

Copy/paste the following command list into the console all at once.

sudo apt-get update
mkdir temp
curl -o temp/archive.tgz -O https://bootstrap.urbit.org/urbit-v0.10.7-linux64.tgz
tar xzf temp/archive.tgz -C temp/
rm temp/archive.tgz
chown -R root:root temp/urbit-v0.10.7-linux64/
mv temp/urbit-v0.10.7-linux64/* ./
rm -rf temp/
sudo fallocate -l 2G /swapfile
sudo chmod 600 /swapfile
sudo mkswap /swapfile
sudo swapon /swapfile
sudo cp /etc/fstab /etc/fstab.bak
echo '/swapfile none swap sw 0 0' | sudo tee -a /etc/fstab

Step 2: Upload your keyfile to the droplet

Open a new console tab and run the following command on your local machine.

scp <local path to keyfile> root@<droplet ip address>:

Once the keyfile is uploaded switch back to your original console tab.

If you don’t have an SSH key configured you will be prompted to enter the droplet’s root password that you created in Step 0.

Step 3: Boot your planet

./urbit -w <planet name> -k <keyfile>

Don’t include the tilde in your planet’s name, i.e. magmyr-darlex

Typical boot time on one of these little servers is about ten minutes. The boot is complete when the prompt shows dojo: <planet name>:dojo>

Step 4: Mount the filesystem

|mount %

Urbit’s filesystem is quite interesting. Read more here.

Step 5: Shut down your planet

ctrl-d

Tap the 'control' and 'd' keys at the same time

Step 6: Securely delete your keyfile

The keyfile is NOT needed to re-start your planet once it's been successfully booted.

shred -vzn 3 <keyfile>rm <keyfile>

Step 7: Disconnect from your droplet

exit

Create a screen and re-start your planet

Step 0: Connect to your droplet

ssh root@<droplet ip address>

Step 1: Create a screen

screen -S <name of the screen>

Running your planet in a screen will allow it to continue running after you disconnect from the droplet. The screen’s name can be any string. We usually name our planets’ screens urbit.

Step 2: Re-start your planet

./urbit <planet name>

Step 3: Detach from the screen

ctrl-a d

Tap 'control' and 'a' at the same time, then tap 'd'

Step 4: Disconnect from your droplet

exit

Say hi to ~dopzod

Step 0: Connect to your droplet

ssh root@<droplet ip address>

Step 1: Re-attach to the screen

screen -r <name of the screen>

If you can’t remember the name you gave the screen, run the command screen -ls to view a list of active screens.

Step 2: Say hi

|hi ~dopzod
# Successful response:

hi ~dopzod successful
; ~dopzod is your neighbor

Step 3: Detach from the screen and disconnect from your droplet

ctrl-a dexit

Generate a passcode and access Landscape

Step 0: Connect and re-attach

ssh root@<droplet ip address>screen -r <name of the screen>

Step 1: Generate a passcode

Verify that your current prompt is dojo>. If chat-cli/ is selected simply toggle back by tapping ctrl-x.

+code

Step 2: Login to Landscape

Enter your droplet’s IP address into a browser to access your planet’s Landscape instance. Paste the value generated in Step 1 into Landscape’s passcode field.

After logging in, select the ~dopzod/urbit-help thread and join the conversation!

Step 3: Detach and disconnect

ctrl-a dexit

A to Z: boot, run, and administer ~magmyr-darlex

On a droplet with IP address 123.45.67.890

# CONNECT TO THE DROPLETssh root@123.45.67.890
# CONFIGURE THE DROPLET & INSTALL URBIT
sudo apt-get update
mkdir temp
curl -o temp/archive.tgz -O https://bootstrap.urbit.org/urbit-v0.10.7-linux64.tgz
tar xzf temp/archive.tgz -C temp/
rm temp/archive.tgz
chown -R root:root temp/urbit-v0.10.7-linux64/
mv temp/urbit-v0.10.7-linux64/* ./
rm -rf temp/
sudo fallocate -l 2G /swapfile
sudo chmod 600 /swapfile
sudo mkswap /swapfile
sudo swapon /swapfile
sudo cp /etc/fstab /etc/fstab.bak
echo '/swapfile none swap sw 0 0' | sudo tee -a /etc/fstab

# UPLOAD KEYFILE **run this command on your local machine**
scp ~/Downloads/magmyr-darlex.key root@123.45.67.890:
# BOOT THE PLANET
./urbit -w magmyr-darlex -k magmyr-darlex.key
# MOUNT THE FILESYSTEM
|mount %
# SHUT DOWN THE PLANET & DELETE KEYFILE
ctrl-d
shred -vzn 3 magmyr-darlex.key
rm magmyr-darlex.key

# CREATE SCREEN
screen -S urbit-planet
# RE-START THE PLANET
./urbit magmyr-darlex
# GENERATE LANDSCAPE PASSCODE
+code
# DETACH & DISCONNECT
ctrl-a d
exit

Now you can get an Urbit instance running and talking, but your planet does much, MUCH more. Keep hacking and come talk shop with us in ~dopzod/urbit-help.

--

--

urbit live

Urbit frontiersmen hellbent on improving the digital experience. Creators of Urbit’s largest planet exchange and first network explorer. https://urbit.live