Entrypoints

Some container images ship with an ENTRYPOINT baked in, or package several tools behind a single entrypoint. Bulker’s entrypoint manifest field pins the in-container binary across both Docker and Apptainer so these crates work identically under either engine.

The default behavior

For a manifest entry like:

  - command: samtools
    docker_image: biocontainers/samtools

bulker runs (roughly):

docker run ... biocontainers/samtools samtools "$@"

That is, bulker appends pkg.command after the image so it becomes the in-container command. The same appending happens under Apptainer:

apptainer exec ... samtools.sif samtools "$@"

This default is correct whenever the shim name matches the in-container binary. Use the entrypoint field only when the two differ, or when the image has an ENTRYPOINT you need to override.

The entrypoint field

Set entrypoint: <binary> when:

• The image has an ENTRYPOINT directive you want to override or pin.
• One image packages multiple tools (e.g. linuxserver/yq ships yq, jq, and xq).
• The shim name differs from the in-container binary name (e.g. a R4.0 shim that runs R).

How it resolves

Engine	entrypoint set	entrypoint unset
Docker	--entrypoint=<value> flag; nothing appended after image	pkg.command appended after image
Apptainer	<value> pushed as the exec command	pkg.command pushed as the exec command

Example: multi-tool image

linuxserver/yq ships three binaries. One entry per tool:

  - command: jq
    docker_image: linuxserver/yq
    entrypoint: jq
    docker_args: -i
  - command: xq
    docker_image: linuxserver/yq
    entrypoint: xq
    docker_args: -i
  - command: yq
    docker_image: linuxserver/yq
    entrypoint: yq
    docker_args: -i

Under Docker, each invocation becomes docker run ... --entrypoint=jq linuxserver/yq "$@". Under Apptainer, each becomes apptainer exec ... linuxserver-yq-latest.sif jq "$@".

Example: image with an ENTRYPOINT

If the image already runs the tool via its ENTRYPOINT, set entrypoint to the same binary. This works under both engines — Docker’s --entrypoint=<binary> is a no-op when it matches the image default, and Apptainer gets an explicit command to exec (Apptainer’s exec does not honor Docker ENTRYPOINT directives).

  - command: pdftk
    docker_image: mnuessler/pdftk
    entrypoint: pdftk
    docker_args: -v $(pwd):/work

Interactive shells

bulker exec _<command> (the shell-wrapper form) launches bash inside the container regardless of entrypoint. The --entrypoint flag is not emitted in interactive mode.

Migrating from the old fields

The entrypoint field replaces three deprecated fields and one flag-level workaround. Use this table when updating existing manifests:

Old pattern	New pattern
docker_command: "" + docker_args: --entrypoint jq + apptainer_command: jq	entrypoint: jq
docker_command: ' ' (literal space)	entrypoint: <binary> (pick the intended binary)
docker_command: jq + apptainer_command: jq	entrypoint: jq
singularity_command: jq	entrypoint: jq

Bulker still reads the deprecated fields for one minor version, but logs a warning on every use. They will be removed in the next minor bump.

Why the old scheme was replaced

The previous scheme layered three engine-specific fields (apptainer_command, docker_command, singularity_command) on top of a docker-only --entrypoint flag smuggled through docker_args. Two concrete problems:

• --entrypoint is ignored by Apptainer, so crates relying on it silently misbehaved under Apptainer — sometimes producing zero-byte output files instead of a visible error.
• The ' ' (space) vs "" vs null distinction in docker_command was load-bearing in the legacy Python template and invisible to any YAML editor or linter. A single edit could flip the semantics without warning.

The entrypoint field collapses the four sources of truth into one, with identical meaning across engines.