Upgrading Urbit binary from 1.9 to 1.10

Saturday, August 6, 2022

Upgrading Urbit on your Linux server has finally become ridiculously easy, with two quick caveats.

An upgrade for the Urbit binary, version 1.10, was released last week.

Version 1.9 was the most recent release before this upgrade, and it’s the one which we documented previously. I wish it were called 1.09, but I haven’t come out as Prince of the Earth yet and for reasons out of our immediate scope won’t be permitted to do so until Charles of Wales is crowned King.

Version 1.9 was in part unique for its incorporation of a simplified upgrade process thanks to a new, built-in upgrade mechanism, so this version marks the first time we get to try it out.

Update Instructions

Quick, clear, and simple instructions for upgrading via the new method have been very nicely documented by the Galactic Tribune. Have a look; it’s an extremely simple, three-step process.

Two one-time caveats to these instructions, however – specific to the update from 1.9 to 1.10 – merit additional documentation.

Pace

The new upgrade mechanism supports release channels (like “Stable” vs “Dev”) called paces, and the version we previously installed happens to have been released on the “wrong” pace.

Before running the commands from the instructions linked immediately above, simply open the file called “pace” inside the hidden subdirectory “.bin” inside your pier folder (the folder designating your planet name on your Linux system). In the pace file, replace the word “once” with “live”.

Alternatively worded, you can execute this in the Linux command line as follows:

echo "live" > /path/to/your-planet/.bin/pace 

Binary Location

The new upgrade process prepares your pier for the update and installs the new binary. It does not necessarily, however, replace the specific Linux binary file that you’re used to running. Once you figure this out, you shouldn’t have to deal with it again; the new upgrade process will be almost ridiculously simple and you shouldn’t need anything other than what the Galactic Tribune has provided.

If you followed verbatim the official documentation for your original installation as I had, you are likely used to running a binary file named “urbit” located in the same directory as your pier folder (i.e. parallel to the pier folder, not inside it).

If your upgrade was successful, that file is now outdated and can be deleted or backed up. This will be the same regardless as to whether you ran the “next” command on the original “.run” binary as advised or ran it on your original “urbit” binary. In either case, the latter file is untouched.

As demonstrated by the Galactic Tribune, the “.run” file inside your pier folder is now your new, upgraded binary.

Moving forward, you can simply run Urbit directly from this binary file. In our case, however, we wanted a quick way to retain functionality of our existing environmental scripts. We opted to create a symbolic link named “urbit” in the location of the original binary, pointing to updated one.

If you want to do the same, assuming your original urbit binary and pier folder were located next to each other inside an “urbit” folder in your home directory, you would execute the following:

ln -s ~/urbit/pier-name/.run ~/urbit/urbit

Don’t forget that Linux interprets relative paths literally in symbolic links, so be sure to use absolute paths as I have above.

Conclusion

The new upgrade feature is impressively simple and efficient. If for any reason you need to use the old method, those instructions are included as well.

The pace problem should not come up again for most users. And if you created a symbolic link as we did, you will not need to create it again when the .run binary is upgraded in the future.

Live long and prosper.