How to run your Urbit ship on Linux easily

published Apr 28, 2021

A super easy guide to running your Urbit.

This guide assumes that you have run your Urbit already at least once, that you have a pier folder, and that you have requested the UI's access password with +code on the interactive Dojo terminal.  It also assumes that your firewall configuration allows communication on the Urbit ports.

So you want to run your Urbit ship on your machine.  OK — we'll get you there.

Deploy the Urbit binaries somewhere

In our example, the Urbit binaries will have been extracted to /usr/local/bin.  Make sure they are all owned by root, executable, and read-only for group and user (chown root:root ; chmod 755 ).

Create a systemd service for Urbit

Here is what you must put in /etc/systemd/system/urbit.service:

[Unit]
Description=Urbit
ConditionPathIsDirectory=/home// [Service] ExecStart=/usr/local/bin/urbit -t -p 34123 /home// Type=exec User= [Install] WantedBy=multi-user.target

Make sure to replace the italicized text with the relevant things.  Also note we are fixing the %ames port to 34123 in this example, but you can pick whatever port you want.  Furthermore, note that we are disabling the interactive Dojo with the -t parameter — don't worry, you can use the Dojo via Landscape.

Start Urbit

Having done this, you will run the following commands as root:

systemctl --system daemon-reload
systemctl enable --now urbit.service

That's really all you need to do.  From now on, every time your machine starts, Urbit will be running automatically.  In fact, right now, your Urbit should now be running and accessible via a browser at http://localhost:8080/.  Use your previously-obtained +code to log in.

How to troubleshoot

To check what's going on, or to troubleshoot problems with your Urbit, you can run the following command (in italics).  Sample output is shown below:

[root@yourbox ~]# journalctl -b -a -u urbit.service
Apr 28 00:31:19 urbit systemd[617]: Starting Urbit... Apr 28 00:31:19 urbit urbit[1050]: ~ Apr 28 00:31:19 urbit systemd[617]: Started Urbit. Apr 28 00:31:19 urbit urbit[1051]: loom: mapped 2048MB Apr 28 00:31:26 urbit urbit[1051]: boot: protected loom Apr 28 00:31:26 urbit urbit[1051]: live: loaded: MB/567.623.680 Apr 28 00:31:26 urbit urbit[1051]: boot: installed 287 jets Apr 28 00:31:26 urbit urbit[1050]: urbit 1.2 Apr 28 00:31:26 urbit urbit[1050]: boot: home is /home// Apr 28 00:31:26 urbit urbit[1050]: loom: mapped 2048MB Apr 28 00:31:26 urbit urbit[1050]: lite: arvo formula 79925cca Apr 28 00:31:26 urbit urbit[1050]: lite: core 59f6958 Apr 28 00:31:26 urbit urbit[1050]: lite: final state 59f6958 Apr 28 00:31:26 urbit urbit[1050]: ---------------- playback starting ---------------- Apr 28 00:31:26 urbit urbit[1050]: pier: replaying events 2217799-2217843 Apr 28 00:31:26 urbit urbit[1050]: pier: (2217843): play: done Apr 28 00:31:26 urbit urbit[1050]: ---------------- playback complete ---------------- Apr 28 00:31:26 urbit urbit[1050]: vere: checking version compatibility Apr 28 00:32:21 urbit urbit[1050]: ames: live on 34123

Further work

Homework for the reader: how to run Urbit as a different user name.