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.
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
8088is the open port on my host for Urbit’s UI
34343is the port used for Azimuth
- I store all my docker data at
/mnt/home-server/dockerso it’s where I’ve mounted the urbit data folder.
services: maptyn-nomlec: image: tloncorp/urbit 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
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
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:
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:
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!
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