Updates to Docker build and README (#336)

- Updates README (here and in DockerHub)
- Fixes bug that posted README updates to `tloncorp/urbit` instead of
`tloncorp/vere`
- Moves DockerHub deploy tasks in build to separate workflow
- Adds a workflow which allows on-demand GitHub Action to redeploy
Docker image to DockerHub

.github/workflows/develop.yml

@@ -17,7 +17,12 @@ jobs:
   urbit:
     uses: ./.github/workflows/shared.yml
     with:
-      docker: true
       pace: 'edge'
       upload: true
     secrets: inherit
+
+  docker:
+    uses: ./.github/workflows/docker-shared.yml
+    with:
+      pace: 'edge'
+    secrets: inherit

.github/workflows/docker-once.yml

@@ -0,0 +1,11 @@
+name: Deploy to DockerHub once
+
+on:
+  workflow_dispatch
+
+jobs:
+  docker:
+    uses: ./.github/workflows/docker-shared.yml
+    with:
+      pace: 'edge'
+    secrets: inherit

.github/workflows/docker-shared.yml

@@ -0,0 +1,42 @@
+name: docker
+
+on:
+  workflow_call:
+    inputs:
+      pace:
+        description: 'Release pace'
+        type: string
+        default: 'edge'
+        required: false
+
+jobs:
+  urbit:
+    runs-on: ubuntu-22.04
+
+    steps:
+      - uses: actions/checkout@v3
+
+      - uses: docker/[email protected]
+        with:
+          username: ${{ secrets.DOCKERHUB_USERNAME }}
+          password: ${{ secrets.DOCKERHUB_TOKEN }}
+
+      - uses: christian-korneck/update-container-description-action@v1
+        env:
+          DOCKER_USER: ${{ secrets.DOCKERHUB_USERNAME }}
+          DOCKER_PASS: ${{ secrets.DOCKERHUB_TOKEN }}
+        with:
+          destination_container_repo: ${{ secrets.DOCKERHUB_USERNAME }}/vere
+          provider: dockerhub
+          short_description: 'Urbit: a clean-slate OS and network for the 21st century'
+          readme_file: 'docker/README.md'
+
+      - name: Build and push version-tagged Docker image
+        run: bazel run //docker:push_version_x86_64
+
+      - name: Build and push pace-tagged Docker image
+        run: bazel run //docker:push_pace_x86_64
+
+      - name: Build and push latest-tagged Docker image
+        if: ${{ inputs.pace == 'live' }}
+        run: bazel run //docker:push_latest_x86_64

.github/workflows/master.yml

@@ -18,8 +18,13 @@ jobs:
   urbit:
     uses: ./.github/workflows/shared.yml
     with:
-      docker: true
       pace: 'live'
       upload: true
       fake_tests: false
     secrets: inherit
+
+  docker:
+    uses: ./.github/workflows/docker-shared.yml
+    with:
+      pace: 'live'
+    secrets: inherit

.github/workflows/next.yml

@@ -17,7 +17,10 @@ jobs:
   urbit:
     uses: ./.github/workflows/shared.yml
     with:
-      docker: true
       upload: true
       next: ${{ github.ref_name }}
     secrets: inherit
+
+  docker:
+    uses: ./.github/workflows/docker-shared.yml
+    secrets: inherit

.github/workflows/release.yml

@@ -17,7 +17,12 @@ jobs:
   urbit:
     uses: ./.github/workflows/shared.yml
     with:
-      docker: true
       pace: 'soon'
       upload: true
     secrets: inherit
+
+  docker:
+    uses: ./.github/workflows/docker-shared.yml
+    with:
+      pace: 'soon'
+    secrets: inherit

.github/workflows/shared.yml

@@ -3,11 +3,6 @@ name: shared
 on:
   workflow_call:
     inputs:
-      docker:
-        description: 'Build and upload image to Docker Hub'
-        type: boolean
-        default: false
-        required: false
       pace:
         description: 'Release pace'
         type: string
@@ -183,42 +178,6 @@ jobs:
             echo "upload to $target failed.";
           exit $exitcode
 
-
-      #
-      # DOCKER
-      #
-      - uses: docker/[email protected]
-        if: ${{ inputs.docker && matrix.target == 'linux-x86_64' }}
-        with:
-          username: ${{ secrets.DOCKERHUB_USERNAME }}
-          password: ${{ secrets.DOCKERHUB_TOKEN }}
-
-      - uses: christian-korneck/update-container-description-action@v1
-        if: ${{ inputs.docker && matrix.target == 'linux-x86_64' }}
-        env:
-          DOCKER_USER: ${{ secrets.DOCKERHUB_USERNAME }}
-          DOCKER_PASS: ${{ secrets.DOCKERHUB_TOKEN }}
-        with:
-          destination_container_repo: ${{ secrets.DOCKERHUB_USERNAME }}/urbit
-          provider: dockerhub
-          short_description: 'Urbit: a clean-slate OS and network for the 21st century'
-          readme_file: 'docker/README.md'
-
-      - name: Build and push version-tagged Docker image
-        if: ${{ inputs.docker && matrix.target == 'linux-x86_64' }}
-        run: |
-          bazel run //docker:push_version_x86_64
-
-      - name: Build and push pace-tagged Docker image
-        if: ${{ inputs.docker && matrix.target == 'linux-x86_64' }}
-        run: |
-          bazel run //docker:push_pace_x86_64
-
-      - name: Build and push latest-tagged Docker image
-        if: ${{ inputs.docker && matrix.target == 'linux-x86_64' && inputs.pace == 'live' }}
-        run: |
-          bazel run //docker:push_latest_x86_64
-
   upload-version-string:
     name: Upload latest deployed version string to GCP
     runs-on: ubuntu-latest

docker/README.md

@@ -6,65 +6,114 @@ 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.
+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 Urbit for information on [obtaining a keyfile](https://urbit.org/using/install/).
-  * 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](https://urbit.org/docs/glossary/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](https://urbit.org/using/operations/using-your-ship/#moving-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.
-
-In consequence, it is safe to remove the container and start a new container which mounts the same volume, e.g. to upgrade the version of the urbit binary by running a later container version. It is also possible to stop the container and then move the pier away e.g. to a location where you will run it directly with the Urbit binary.
+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](https://urbit.org/getting-started/get-id).
+    - 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](https://urbit.org/docs/glossary/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](https://operators.urbit.org/manual/os/basics#moving-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 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](https://developers.urbit.org/reference/glossary/reset).
 
 ### 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](https://urbit.org/docs/glossary/landscape/) and for [API calls](https://urbit.org/using/integrating-api/) to the ship. Port `34343` is set by default to be used by [Ames](https://urbit.org/docs/glossary/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 achive direct connections regardless.
-
-For this purpose 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. You must pass the name of the start script `/bin/start-urbit` in order to also pass arguments, if this 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.
+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](https://urbit.org/docs/glossary/landscape/) and for
+[API calls](https://developers.urbit.org/guides/additional/http-api-guide) to
+the ship. Port `34343` is set by default to be used by
+[Ames](https://urbit.org/docs/glossary/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 using `--loom=$LOOM_SIZE`. Passing `/bin/start-urbit --loom=32` for example, would setup a 4GB loom. The default loom size is 31 (2GB).
+
+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:
+
+Creating a volume for `~sampel-palnet`:
 ```
 docker volume create sampel-palnet
 ```
 
-Copying key to sampel-palnet's volume (assumes default docker location):
+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:
+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:
+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 the planet, for programmatic use so the container does not need a tty. These scripts can be called using `docker container exec`.
+### 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:
 ```
@@ -78,11 +127,11 @@ $ docker container exec sampel-palnet /bin/reset-urbit-code
 OK
 ```
 
-Once the code has been reset the new code can be obtained from `/bin/get-urbit-code`.
-
 ## 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.
-
-## Development
-The docker image is built by a Nix derivation in the [`nix/pkgs/docker-image/default.nix`](https://github.com/urbit/urbit/tree/master/nix/pkgs/docker-image/default.nix) file under the Urbit git repository.
+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.