Steps to Urbit on Docker Desktop for Windows

steps-to-urbit-on-docker-desktop-for-windows.md

Why Docker Desktop?

• It can start urbit automatically in the background each time you login to windows
• Has a gui to turn urbit on/off if you don't want it running all the time
• Sets up port forwarding to your host device's ip, which plain wsl makes difficult. So you can access landscape from other devices on your lan, or forward ports to your router to get external access
• Automatic updates to the urbit binary

See https://subject.network/posts/urbit-windows-docker/ for an enhanced take on this guide, with screenshots and more.

How to Install Docker

winget is an easy and non-interactive way to install Docker Desktop, which will eventually be a standard part of Windows installs but isn't yet.

So you may need to first upgrade to a preview version of Microsoft App Installer before you can use winget https://github.com/microsoft/winget-cli/releases/download/v-0.2.10191-preview/Microsoft.DesktopAppInstaller_8wekyb3d8bbwe.appxbundle

Open a command window and run the following command:

winget install docker

Once it finishes, reboot Windows.

Docker Desktop should start automatically after you log back in.

If you didn't previously have WSL2 installed, Docker Desktop will complain "WSL 2 installation is incomplete" and you will need to install Microsoft's Linux kernel package https://wslstorestorage.blob.core.windows.net/wslblob/wsl_update_x64.msi and then restart Docker Desktop.

Open a Windows command window and run:

docker volume create urbit

Open up File Explorer and navigate to

\\wsl$\docker-desktop-data\version-pack-data\community\docker\volumes\urbit\_data

What should you put in the volumes\urbit\_data folder?

• A keyfile <shipname>.key for a galaxy, star, planet, or moon. See the setup instructions for Urbit for information on obtaining a keyfile.
  • e.g. sampel-palnet.key for the planet sampel-palnet.
• An empty file with the extension .comet. This will cause Urbit to boot a comet in a pier named for the .comet file (less the extension).
  • e.g. starting with an empty file my-urbit-bot.comet will result in Urbit booting a comet into the pier my-urbit-bot under your volume.
• An existing pier as a directory <shipname>. You can migrate an existing ship to a new docker container in this way by placing its pier under the volume.
  • e.g. if your ship is sampel-palnet then you likely have a directory sampel-palnet whose path you pass to ./urbit when starting. Move your pier directory to the volume and then start the container.

The first two options result in Urbit attempting to boot either the ship named by the name of the keyfile, or a comet. In both cases, after that boot is successful, the .key or .comet file will be removed from the volume and the pier will take its place.

Get urbit running

Back in the windows command prompt:

docker run -p 80:80 -it --restart always --mount type=volume,source=urbit,destination=/urbit --name urbit tloncorp/urbit

You can detach from a container and leave it running using the CTRL-p CTRL-q key sequence.

You can find landscape at http://localhost

Here are some commands that might be useful to re-attach to the docker container, or start it again:

docker attach urbit

docker start -ai urbit

If you go into Docker Desktop settings and check the box Start Docker Desktop when you log in then Urbit should start and run in the background everytime you login to windows.

Automatic updates

Use watchtower to automatically install new versions of the urbit binary:

docker run -d --restart always --name watchtower -v /var/run/docker.sock:/var/run/docker.sock containrrr/watchtower

Possible Errors

If the container log shows an error like this one:

vere: checking version compatibility
unix: stopping process 8, live in sampel-palnet...
unix: process 8 seems unkillable!
Assertion '0' failed in vere/io/unix.c:1321

bail: oops
bailing out
/bin/start-urbit: line 42:     7 Aborted                 urbit $ttyflag -p 34343 $dirname

it should resolve when starting the Urbit container again. It happened because Urbit wasn't cleanly shutdown. If you really wanted to prevent that you could add a group policy script to run when your user logsoff, which would attach to the container and send the shutdown signal to Urbit.

If for some reason Urbit fails to start repeatedly with that error, then visit \\wsl$\docker-desktop-data\version-pack-data\community\docker\volumes\urbit\_data\sampel-palnet and delete the .vere.lock file.

This is excellent.. Thank you!