containers-usage.md

Containers Usage

Use this guide to run container workflows in this repository, including image build/lint commands, runtime selection (Docker vs Podman), and container-backed quality checks.

Table of contents

• Containers Usage
  • Table of contents
  • Scope
  • How to use this guide
  • Overview
  • How containers are used in this project
    • 1) Runtime layer (Docker and Podman)
    • 2) Build/lint orchestration
    • 3) Container fallback for quality checks
  • Configuration
    • Prerequisites
    • Task-first quick start
    • Make targets reference
    • Important variables
    • Dockerfile.effective behaviour
  • Quality and safety controls
  • Troubleshooting
    • docker: command not found
    • Lint/build cannot find Dockerfile
    • Build works but tags are unexpected
    • Forced container mode for quality checks
    • Podman/Docker runtime mismatch
  • Operational command reference
  • Configuration map
  • Related files
  • Further reading

Scope

This guide covers container usage that is implemented directly in this repository:

• make-driven Docker image workflows from scripts/docker/docker.mk
• Docker helper functions from scripts/docker/docker.lib.sh
• Dockerfile linting via scripts/docker/dockerfile-linter.sh
• Container fallback used by quality scripts under scripts/quality/*.sh

It does not define a Development Container (.devcontainer/) setup for this repository.

How to use this guide

1. Start with Prerequisites to confirm runtime/tooling health.
2. Use Task-first quick start for common workflows.
3. Use Make targets reference and Important variables for custom usage.
4. Use Troubleshooting when commands fail locally or in CI.

Overview

Container support in this repository has two main roles:

1. Build and lint Docker images through reusable make targets and shell functions.
2. Run quality tooling in containers when native binaries are unavailable (or when forced via FORCE_USE_DOCKER=true).

Tip

On macOS, setup installs Podman (and Podman Desktop) by default. Docker Desktop is optional via INSTALL_DOCKER=true during app installation.

How containers are used in this project

1) Runtime layer (Docker and Podman)

• The repository uses docker ... commands in scripts.
• dot_functions provides a compatibility function: if Docker CLI is missing and Podman is installed, docker transparently delegates to podman.
• This keeps scripts and guides consistent while allowing either runtime.

2) Build/lint orchestration

• The root Makefile includes scripts/init.mk, which includes scripts/docker/docker.mk.
• Main targets are:
  • docker-bake-dockerfile
  • docker-lint
  • docker-build
  • docker-run
  • docker-push
  • docker-test-suite-run
• Docker build logic is implemented in scripts/docker/docker.lib.sh.

3) Container fallback for quality checks

Quality scripts can run tools natively or in Docker containers:

• check-file-format.sh (editorconfig-checker)
• check-markdown-format.sh (markdownlint-cli)
• check-markdown-links.sh (lychee)
• check-shell-lint.sh (shellcheck)
• scan-secrets.sh (gitleaks)

Pinned tool image versions are read from .tool-versions (Docker section).

Configuration

Prerequisites

Confirm your runtime and repository toolchain first.

docker --version
docker info > /dev/null
make --version

If you use Podman instead of Docker CLI:

podman --version
podman info > /dev/null

Minimum repository prerequisites for image workflows:

• A directory containing Dockerfile
• Optional VERSION file (for multi-tag builds)
• Access to .tool-versions when relying on pinned base/tool image versions

Task-first quick start

If you want to...	Run...	What it does
Generate an effective Dockerfile	make docker-bake-dockerfile dir=scripts/docker/tests	Creates Dockerfile.effective (+ metadata and version substitutions).
Lint the generated Dockerfile	make docker-lint dir=scripts/docker/tests	Runs hadolint via native binary or container fallback.
Build an image	make docker-build dir=scripts/docker/tests docker_image=repository-template/docker-test docker_title="Repository Template Docker Test"	Builds image and applies version tags from .version plus latest.
Run an image	make docker-run dir=scripts/docker/tests docker_image=repository-template/docker-test DOCKER_CMD="python --version"	Runs the built image with optional command override.
Push an image	make docker-push dir=scripts/docker/tests docker_image=repository-template/docker-test	Pushes all effective tags and latest.
Run Docker module tests	make docker-test-suite-run	Executes scripts/docker/tests/docker.test.sh.
Force quality tools to use containers	FORCE_USE_DOCKER=true make lint	Runs wrapper scripts in Docker instead of native tools.

Make targets reference

Target	Purpose	Notes
docker-bake-dockerfile	Create Dockerfile.effective	Uses dir or docker_dir (defaults to . in target help).
docker-lint	Lint Dockerfile with hadolint	Depends on docker-bake-dockerfile.
docker-build	Build Docker image	Depends on docker-lint.
docker-run	Run image locally	Uses effective image tag resolution.
docker-push	Push image tags	Pushes all effective tags and latest.
clean	Includes Docker clean-up step	Docker clean runs through clean:: extension in docker.mk.
docker-shellscript-lint	Lint scripts in scripts/docker	Uses shell lint wrapper.
docker-test-suite-run	Run Docker module tests	Validates helper functions and version logic.

Important variables

Variable	Used by	Meaning
DOCKER_IMAGE / docker_image	Docker make targets	Target image name (for example ghcr.io/org/repo).
DOCKER_TITLE / docker_title	Docker build flow	OCI metadata title/description defaults.
dir / docker_dir	Docker make targets	Path to image directory containing Dockerfile.
DOCKER_CMD	docker-run	Optional command executed in container.
BUILD_DATETIME	version/templating functions	Timestamp used when rendering VERSION placeholders.
FORCE_USE_DOCKER	quality + linter wrappers	Forces container execution even if native CLI exists.
TOOL_VERSIONS	Docker helper functions	Optional override path for versions file.

Dockerfile.effective behaviour

docker-bake-dockerfile and docker-build generate Dockerfile.effective before lint/build.

During this step, the tooling:

1. Copies Dockerfile to Dockerfile.effective.
2. Copies Dockerfile.dockerignore to Dockerfile.effective.dockerignore (if present).
3. Replaces FROM <image>:latest with pinned versions from .tool-versions where available.
4. Renders VERSION placeholders into .version (supports $yyyy, $mm, $dd, $HH, $MM, $SS, $hash).
5. Appends OCI metadata labels from scripts/docker/Dockerfile.metadata.

Quality and safety controls

• Hadolint configuration is defined in scripts/config/hadolint.yaml.
• Generated Dockerfiles have # hadolint ignore=DL3007 removed, so latest usage is still enforced on effective output.
• Quality scripts use pinned tool images from .tool-versions where declared.
• docker-build passes Git and build metadata via build args (branch, commit, date, version).

Troubleshooting

docker: command not found

• If Docker CLI is not installed, ensure Podman is installed and your shell has loaded dot_functions.
• Open a new shell and retry docker --version.

Lint/build cannot find Dockerfile

• Pass an explicit image directory:

  make docker-lint dir=path/to/image
  make docker-build dir=path/to/image docker_image=ghcr.io/org/repo

Build works but tags are unexpected

• Check VERSION content and generated .version:

  make version-create-effective-file dir=scripts/docker/tests
  cat scripts/docker/tests/.version

Forced container mode for quality checks

• Use:

  FORCE_USE_DOCKER=true make lint

Podman/Docker runtime mismatch

• Verify the active engine:

  docker info
  podman info

Operational command reference

• Build helper test image:

  make docker-build dir=scripts/docker/tests docker_image=repository-template/docker-test docker_title="Repository Template Docker Test"

• Lint Dockerfile:

  make docker-lint dir=scripts/docker/tests

• Run image command:

  make docker-run dir=scripts/docker/tests docker_image=repository-template/docker-test DOCKER_CMD="python --version"

• Push image:

  make docker-push dir=scripts/docker/tests docker_image=repository-template/docker-test

• Run Docker module tests:

  make docker-test-suite-run

• Lint all Docker module shell scripts:

  make docker-shellscript-lint

Configuration map

Area	Location	Purpose
Docker make module	scripts/docker/docker.mk	Public make targets and wrapper target _docker.
Docker helper library	scripts/docker/docker.lib.sh	Build, run, push, clean, versioning, and image pinning logic.
Dockerfile linter wrapper	scripts/docker/dockerfile-linter.sh	Native-or-container hadolint execution.
Metadata template	scripts/docker/Dockerfile.metadata	OCI labels appended to Dockerfile.effective.
Hadolint config	scripts/config/hadolint.yaml	Lint policy and trusted registries.
Tool/image version pins	.tool-versions	Runtime tools and Docker image versions used by wrappers.
Runtime compatibility helper	dot_functions	Fallback docker() function delegating to Podman.
macOS runtime install script	assets/31-install-developer-apps.macos.sh	Installs Podman by default; Docker Desktop optional.

Related files

• Makefile
• scripts/init.mk
• scripts/docker/docker.mk
• scripts/docker/docker.lib.sh
• scripts/docker/dockerfile-linter.sh
• scripts/docker/tests/docker.test.sh
• scripts/config/hadolint.yaml
• .tool-versions
• dot_functions

Further reading

• CLI usage
• Git usage
• Visual Studio Code usage
• Development Containers