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

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.

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 d
    
  exit

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 talk 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 d
    
  exit

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

On a droplet with IP address 123.45.67.890


  # CONNECT TO THE DROPLET
    
    ssh 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


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