hello world: Urbit edition
Install, boot, and run your Urbit planet on a $10 cloud server
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 URBITsudo 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 KEYFILEctrl-d
shred -vzn 3 magmyr-darlex.key
rm magmyr-darlex.key
# CREATE SCREENscreen -S urbit-planet
# RE-START THE PLANET./urbit magmyr-darlex
# GENERATE LANDSCAPE PASSCODE+code
# DETACH & DISCONNECTctrl-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.