.. | ||
BUILD.bazel | ||
get_urbit_code.sh | ||
README.md | ||
reset_urbit_code.sh | ||
start_urbit.sh |
Official Urbit Docker Image
This is the official Docker image for Urbit.
Urbit is a clean-slate OS and network for the 21st century.
Using
To use this image, you should mount a volume with a keyfile, comet file, or
existing pier at /urbit
, and map ports as described below.
Volume Mount
This image expects a volume mounted at /urbit
. This volume should initially
contain one of:
- A keyfile
<shipname>.key
for a galaxy, star, planet, or moon. See the setup instructions for information on obtaining a keyfile.- e.g.
sampel-palnet.key
for the planet~sampel-palnet
.
- e.g.
- 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 piermy-urbit-bot
under your volume.
- e.g. starting with an empty file
- 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 directorysampel-palnet
whose path you pass to./urbit
when starting. Move your pier directory to the volume and then start the container.
- e.g. if your ship is
The first two options result in Urbit attempting to boot either the ship named
by 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.
Therefore, it is safe to remove the Docker container and start a new container which mounts the same volume (e.g. to upgrade the version of the Urbit binary by running a newer image). It is also possible to stop the container and then move the pier out of the Docker volume (e.g. to run it using an Urbit binary directly). If you do this, make sure to delete the Docker volume after you move your pier; if you launch a container using this same pier after moving it and launching it elsewhere, you will likely need to perform a breach.
Ports
The image includes EXPOSE
directives for TCP port 80
and UDP port 34343
.
Port 80
is used for Urbit's HTTP interface for both
Landscape and for
API calls to
the ship. Port 34343
is set by default to be used by
Ames for ship-to-ship communication.
You can either pass the -P
flag to docker to map ports directly to the
corresponding ports on the host, or map them individually with -p
flags. For
local testing the latter is often convenient, for instance to remap port 80
to
an unprivileged port.
For best performance, you must map the Ames UDP port to the same port on the host. If you map to a different port Ames will not be able to make direct connections and your network performance may suffer somewhat. Note that using the same port is required for direct connections but is not by itself sufficient for them. If you are behind a NAT router or the host is not on a public IP address (or you are firewalled), you may not achieve direct connections regardless.
For this reason, you can force Ames to use a custom port.
/bin/start-urbit --port=$AMES_PORT
can be passed as an argument to the
docker start
command. Passing /bin/start-urbit --port=13436
for example,
would use port 13436
. Note that you must pass the full script command
/bin/start-urbit
in order to also pass arguments. If the script is omitted,
your container will not start.
You can also set the http port using --http-port=$HTTP_PORT
. Passing
/bin/start-urbit --http-port=8085
for example, would use port 8085
. The
default http port is 8080
.
Variable Loom Size
You can also set a variable loom size (Urbit memory size) using
--loom=$LOOM_SIZE
. Passing /bin/start-urbit --loom=32
for example, would set
up a 4GiB loom (2^32 bytes = 4GiB
). The default loom size is 31
(2GiB).
Examples
Creating a volume for ~sampel-palnet
:
docker volume create sampel-palnet
Copying key to ~sampel-palnet
's volume (assumes default Docker location):
sudo cp ~/sampel-palnet.key /var/lib/docker/volumes/sampel-palnet/_data/sampel-palnet.key
Using that volume and launching ~sampel-palnet
on host port 8080
with Ames
talking on the default host port 34343
:
docker run -d -p 8080:80 -p 34343:34343/udp --name sampel-palnet \
--mount type=volume,source=sampel-palnet,destination=/urbit \
tloncorp/vere
Using host port 8088
with Ames talking on host port 23232
:
docker run -d -p 8088:80 -p 23232:23232/udp --name sampel-palnet \
--mount type=volume,source=sampel-palnet,destination=/urbit \
tloncorp/vere /bin/start-urbit --port=23232
Getting and resetting the Landscape +code
This docker image includes tools for retrieving and resetting the Landscape
login code belonging to a ship, for programmatic use so the container does not
need a tty. These scripts can be called using docker container exec
.
Getting the code:
$ docker container exec sampel-palnet /bin/get-urbit-code
sampel-sampel-sampel-sampel
Resetting the code:
$ docker container exec sampel-palnet /bin/reset-urbit-code
OK
Extending
You likely do not want to extend this image. External applications which interact with Urbit do so primarily via an HTTP API, which should be exposed as described above. For containerized applications using Urbit, it is more appropriate to use a container orchestration service such as Docker Compose or Kubernetes to run Urbit alongside other containers which will interface with its API.