Hosting an Urbit Planet in docker

I used to run my Urbit planet on my home server inside a terminal window. Not the most efficient method, and whenever my server rebooted or the power in my flat went out (which surprisingly often happens…) my planet would go down until I re-opened the terminal window and ran my start script.

This was a terrible way of managing any application on my home server. I was running docker, but I had installed Docker Desktop which had an absolute abysmal user experience, so I wrote it off for everything other than managing my Linux ISO seed box (since I wanted to be able to back up and easily manage its state).

Then one day at work, a coworker said something along the lines of:

“Oh, Docker Desktop sucks, just use Docker Compose and then some other Web-UI to monitor your containers.”

Which is where I’m at now.

Docker Compose

Tlon offer a docker image for Urbit, but no compose file. Here is one I made to suit my use case:

The service is named after my planet maptyn-nomlec
Port 8088 is the open port on my host for Urbit’s UI
Port 34343 is the port used for Azimuth
I store all my docker data at /mnt/home-server/docker so it’s where I’ve mounted the urbit data folder.

services:
  maptyn-nomlec:
    image: tloncorp/vere:latest
    ports:
      - "8088:80"
      - "34343:34343/udp"
    volumes:
      - "/mnt/home-server/docker/urbit/data:/urbit"

Before running, make sure your Planets key is inside the data folder. The folder structure of this directory is as follows:

mnt/
└── home-server/
    └── docker/
        └── urbit/
            ├── data/
            │   └── maptyn-nomlec.key
            └── docker-compose.yml

From /mnt/home-server/docker/urbit run:

docker-compose up -d

It may take a few moments for your Planet to come online, keep an eye on your containers logs since this image forwards your dojo’s output there.

Once your planet is live, you can run the following command to get your Planet’s access code:

docker container exec <container-name> /bin/get-urbit-code

Docker Web-UI

I use Yacht as my docker Web-UI since it was super easy to stand up & it has some nice QOL features.

I used this compose file I found online:

version: '3'
services:
  yacht:
    container_name: yacht
    restart: unless-stopped
    ports:
      - 8000:8000
    volumes:
      - yacht:/config
      - /var/run/docker.sock:/var/run/docker.sock
      - /mnt/home-server/docker/yacht/compose:/compose
    environment:
      - PUID=0
      - PGID=0
      - COMPOSE_DIR=/compose
    image: selfhostedpro/yacht
volumes:
  yacht:

Proxying

I use Nginx Proxy Manager (NPM) to easily forward URLs to ports on my home server.

I used the following compose file:

version: '3'
services:
  nginx-proxy-manager:
    image: 'jc21/nginx-proxy-manager:latest'
    restart: unless-stopped
    ports:
      - '80:80'
      - '81:81'
      - '443:443'
    volumes:
      - /mnt/home-server/docker/nginx-proxy-manager/data:/data
      - /mnt/home-server/docker/nginx-proxy-manager/letsencrypt:/etc/letsencrypt

Creating a shared network

Since Nginx Proxy Manager (NPM) and Urbit are in separate containers, I can’t actually use NPM to forward to Urbit. However, I can create a shared virtual network inside Docker for them to communicate on.

docker network create proxy-manager
docker network connect proxy-manager urbit-container-name
docker network connect proxy-manager nginx-proxy-manager-container-name

Once these commands have been run, you should be able to view your Urbit container in Yacht and see that there are now two networks attached: urbit-default and proxy-manager.

Connecting the two

Navigate to Nginx Proxy Manager. Once you’re signed in to Nginx Proxy Manager, I recommend using their tools to generate an SSL certificate for your domain.

Once you have an SSL certificate inside Nginx Proxy Manager, you can create a Proxy Host. For “Forwarded Hostname / IP” enter your Urbit docker containers name and for “Forwarded Port” enter 80. Since Both Urbit and Nginx Proxy Manager are on the same virtual network you reference internal ports here, not the ones forwarded to your host.

Ensure you’ve configured your domain to point to your home server!

Before you can access your Planet at the URL you need to configure it to use SSL, navigate to it locally, sign in and open your Planet’s terminal and run the following (replacing urbit.example.com with your domain):

:acme &path /com/example/urbit

Once your Planet has created a certificate, you should be able to finally access your Planet at your domain!

In Closing

This is a much more stable way of managing your Planet. If set up correctly, this could also be used to orchestrate any number of Planets or Moons on one machine with unique URLs.

If you have any questions, please reach out either via email or on Urbit. I run a group at ~maptyn-nomlec/pfych. You can also start a DM with me via Talk at ~maptyn-nomlec