|
| 1 | +# conex-helper |
| 2 | + |
| 3 | +[`python:3-alpine`](https://hub.docker.com/_/python/)-based dockerization of a utility program which helps manage the `backplane/conex` github repo |
| 4 | + |
| 5 | +## Usage |
| 6 | + |
| 7 | +The program has three primary subcommands: `update-readme`, `update-workflow`, and `metadata`. |
| 8 | + |
| 9 | +### general help text |
| 10 | + |
| 11 | +``` |
| 12 | +usage: main.py [-h] [--debug] [--dhuser DHUSER] command ... |
| 13 | +
|
| 14 | +utility for maintaining the github.com/backplane/conex repo |
| 15 | +
|
| 16 | +positional arguments: |
| 17 | + command |
| 18 | + update-readme update the central readme from the readme files in the container subdirectories |
| 19 | + update-workflow |
| 20 | + update the github actions workflow file 'docker.yml' with the current list of container subdirectories |
| 21 | + metadata called during the container build github action to write workflow outputs that get used in later build steps |
| 22 | +
|
| 23 | +options: |
| 24 | + -h, --help show this help message and exit |
| 25 | + --debug enable debug output (default: False) |
| 26 | + --dhuser DHUSER the docker hub repo path to use when linking to images (default: backplane) |
| 27 | +``` |
| 28 | + |
| 29 | +### `update-readme` subcommand |
| 30 | + |
| 31 | +This subcommand is used to update the central `README.md` from the `README.md` files in the container subdirectories. |
| 32 | + |
| 33 | +``` |
| 34 | +usage: main.py update-readme [-h] [-i HEADER] readme subdir_readmes [subdir_readmes ...] |
| 35 | +
|
| 36 | +positional arguments: |
| 37 | + readme the path to the markdown file to update |
| 38 | + subdir_readmes the source README.md files to build from |
| 39 | +
|
| 40 | +options: |
| 41 | + -h, --help show this help message and exit |
| 42 | + -i HEADER, --header HEADER |
| 43 | + header file(s) to include at the beginning of the output (default: []) |
| 44 | +
|
| 45 | +``` |
| 46 | + |
| 47 | +### `update-workflow` subcommand |
| 48 | + |
| 49 | +This subcommand is used to update the github actions workflow file `docker.yml` with the current list of container subdirectories. |
| 50 | + |
| 51 | +``` |
| 52 | +usage: main.py update-workflow [-h] [--workflowfile WORKFLOWFILE] [--basedir BASEDIR] [-l] |
| 53 | +
|
| 54 | +options: |
| 55 | + -h, --help show this help message and exit |
| 56 | + --workflowfile WORKFLOWFILE |
| 57 | + the path to the workflow file to update (in-place) (default: .github/workflows/docker.yml) |
| 58 | + --basedir BASEDIR the path the repo base (default: .) |
| 59 | + -l, --list don't make any changes; instead print the container list from the current action file (default: False) |
| 60 | +
|
| 61 | +``` |
| 62 | + |
| 63 | +### `metadata` subcommand |
| 64 | + |
| 65 | +This subcommand is called during the docker build github action to write workflow outputs that get used in later build steps. |
| 66 | + |
| 67 | +This includes comparing the perishable checksum of the current build context to the perishable checksum label on the corresponding image already on docker hub. This allows builds to be skipped if nothing has changed in the build context. |
| 68 | + |
| 69 | +``` |
| 70 | +usage: main.py metadata [-h] [--forcedbuilds FORCEDBUILDS] [--repo REPO] [--psumlabel PSUMLABEL] [--platforms PLATFORMS] [--platforms-override-file PLATFORMS_OVERRIDE_FILE] [--licenses LICENSES] |
| 71 | + [--licenses-override-file LICENSES_OVERRIDE_FILE] |
| 72 | + contextname |
| 73 | +
|
| 74 | +positional arguments: |
| 75 | + contextname the name of the directory containing the Docker build context |
| 76 | +
|
| 77 | +options: |
| 78 | + -h, --help show this help message and exit |
| 79 | + --forcedbuilds FORCEDBUILDS |
| 80 | + comma-separated list of container contexts to build, without regard to the context's perishable checksum (default: ) |
| 81 | + --repo REPO the image repo, as given to the 'docker pull' command (default: None) |
| 82 | + --psumlabel PSUMLABEL |
| 83 | + the namespaced perishable sum label name to apply to the image (default: be.backplane.image.context_psum) |
| 84 | + --platforms PLATFORMS |
| 85 | + the default list of platforms to build for (default: linux/amd64,linux/arm64,linux/arm/v7) |
| 86 | + --platforms-override-file PLATFORMS_OVERRIDE_FILE |
| 87 | + the name of a file inside the context directory which lists platforms to build for (default: .build_platforms.txt) |
| 88 | + --licenses LICENSES the default SPDX License Expression for the primary image content (default: Various Open Source) |
| 89 | + --licenses-override-file LICENSES_OVERRIDE_FILE |
| 90 | + the name of a file inside the context directory which lists SPDX License Expressions for the primary image content (default: LICENSES.txt) |
| 91 | +
|
| 92 | +``` |
| 93 | + |
| 94 | +### Interactive Use |
| 95 | + |
| 96 | +The following shell function can assist in running this image interactively: |
| 97 | + |
| 98 | +```sh |
| 99 | + |
| 100 | +conex_helper() { |
| 101 | + docker run \ |
| 102 | + --rm \ |
| 103 | + --interactive \ |
| 104 | + --tty \ |
| 105 | + --volume "$(pwd):/work" \ |
| 106 | + "backplane/conex-helper" \ |
| 107 | + "$@" |
| 108 | +} |
| 109 | +``` |
0 commit comments