Make an image creation FAQ

[MrCreosote]

Some of this is already in https://github.com/kbase/cdm-task-service/blob/main/docs/admin_image_setup.md

Other stuff for a FAQ

• test the image locally
  • don't test with an --entrypoint or --command argument as that overrides the dockerfile entrypoint / command, which is what will actually be run

[jplfaria]

A few gotchas from building cdm_kofamscan, cdm_bakta, and cdm_psortb:

Conda-installed binaries are not on PATH for runc exec

Lots of bioconda base images install the tool at /opt/conda/bin/<tool> but conda's bin dir is not on the PATH inherited at runc exec time. PATH at exec is just /usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin. The image's Shell config (e.g. bash -l -c) doesn't help since exec-form ENTRYPOINT bypasses the shell.

Fix: use the absolute path in your Dockerfile.

ENTRYPOINT ["/opt/conda/bin/bakta"]

cdm_bakta 0.1.0 had ENTRYPOINT ["bakta"] and failed at runc create with executable file not found in $PATH.

Tools that only write to stdout need a wrapper

CTS uploads files written to the output_mount_point. If your tool has no --output flag and writes everything to stdout (e.g. PSORTb), the results vanish even though the container exits 0.

Fix: COPY a wrapper script and use it as the entrypoint.

#!/bin/bash
set -e
INPUT="${@: -1}"
BASE=$(basename "$INPUT")
BASE="${BASE%.*}"
exec /usr/local/psortb/bin/psort "$@" > "/out/${BASE}.psortb.tsv"

Building on arm64, running on amd64

If you build with docker build on an Apple Silicon Mac and don't pass --platform, your local image is arm64 only. CTS clusters are amd64. Either build with --platform linux/amd64 or let GitHub Actions handle the build.

For testing a multi-arch image pulled from GHCR on an arm64 host, pass --platform linux/amd64 so Docker pulls the right manifest.

Use the manifest list digest, not the per-arch sub-manifest digest, when registering

buildx produces a manifest list (one entry per architecture) plus per-arch sub-manifests. The digest shown on the GitHub Packages web UI is the manifest list digest. That is the one to use when registering. The per-arch sub-manifest digests work for direct docker pull but registration expects the list.

To grab it programmatically, look in the GHA build log for ##[group]Digest right after Build and push Docker image.

GHCR packages are private by default

First push creates a private package. CTS cannot pull a private image. Switch visibility to public in the org package settings.

Usage note in registration: input files come from the placeholder, not literal paths

Do not write literal filenames in usage notes or in the args you submit. Use the input-files placeholder (tscli.insert_files() for the Python client, or {type: input_files, ...} raw). Otherwise the usage note misleads callers and multi-file jobs only see the first file.

For tools that process one input per invocation, set num_containers = N

Bakta, PSORTb, and KofamScan each take one input at a time. Two options: set num_containers equal to the input count and let CTS spread one file per container, or write a wrapper that loops over inputs in a single container. Per-container parallelism is simpler. The loop variant is more efficient at scale since it avoids repeated refdata mounting.

[MrCreosote]

• Add an example of how to invoke an image locally with mounts for input / output / refdata