5.0.0 / 2023-11-03

- Upgraded to Python 3.12

- Upgraded to Ansible 8.5.0

- Renamed the `run` script to `kineticcafe-ansible` and fixed several issues:

  - Bash 4 or later is required for associative array support. Ensured that
    this would be respected on macOS by using `/usr/bin/env bash` instead of
    `/bin/bash`.

  - Updated the script to use the current version of the image.

  - Fixed various issues with file and directory mounts. Many more mountable
    files (`--become-password-file`, etc.) are supported than
    `--vault-password-file`. Note that not _all_ possible file parameters are
    supported, such as `--module-paths` or `--extra-vars @file`. Pull requests
    for supporting these would be considered.

  - Fixed an overzealous application of `--ask-vault-password`, even for
    commands that could not use it.

  - Changed the `sh` subcommand to execute `bash` and added `bash` as a known
    subcommand.

  - Added support for deriving the entry point from `basename $0`.

- Updated the Docker image to use HEREDOC.

  - Added `less`, `nano`, and `vim-nox` packages.

- Added an `install` script to install `kineticcafe-ansible` and optional
  symlinks.

Author: halostatue

.github/workflows/build-test-image.yml

@@ -25,6 +25,6 @@ jobs:
           push: false
           tags: kineticcafe/ansible:test
 
-      - run: ./run --version
+      - run: ./kineticcafe-ansible --version
         env:
           IMAGE: kineticcafe/ansible:test

Changelog.md

@@ -1,5 +1,40 @@
 # [ghcr.io/]kineticcafe/ansible Changelog
 
+## 5.0.0 / 2023-11-03
+
+- Upgraded to Python 3.12
+
+- Upgraded to Ansible 8.5.0
+
+- Renamed the `run` script to `kineticcafe-ansible` and fixed several issues:
+
+  - Bash 4 or later is required for associative array support. Ensured that
+    this would be respected on macOS by using `/usr/bin/env bash` instead of
+    `/bin/bash`.
+
+  - Updated the script to use the current version of the image.
+
+  - Fixed various issues with file and directory mounts. Many more mountable
+    files (`--become-password-file`, etc.) are supported than
+    `--vault-password-file`. Note that not _all_ possible file parameters are
+    supported, such as `--module-paths` or `--extra-vars @file`. Pull requests
+    for supporting these would be considered.
+
+  - Fixed an overzealous application of `--ask-vault-password`, even for
+    commands that could not use it.
+
+  - Changed the `sh` subcommand to execute `bash` and added `bash` as a known
+    subcommand.
+
+  - Added support for deriving the entry point from `basename $0`.
+
+- Updated the Docker image to use HEREDOC.
+
+  - Added `less`, `nano`, and `vim-nox` packages.
+
+- Added an `install` script to install `kineticcafe-ansible` and optional
+  symlinks.
+
 ## 4.0.0 / 2023-08-04
 
 - Upgraded to Ansible 8.2.0

Dockerfile

@@ -1,20 +1,28 @@
-FROM python:3.12-slim-bullseye AS builder
+# syntax=docker/dockerfile:1
+
+FROM python:3.12-slim-bookworm AS builder
 
 ENV LC_ALL=C.UTF-8 \
     LANG=C.UTF-8 \
     EDITOR=nano
 
-RUN apt-get -qqy update \
-      && apt-get -qqy upgrade \
-      && apt-get -qqy --no-install-recommends install \
-            build-essential \
-            python-dev \
-            libffi-dev \
-            rustc \
-      && adduser --disabled-password --gecos '' ansible \
-      && python3 -m pip install pip --upgrade \
-      && mkdir -p /opt/ansible \
-      && chown -R ansible:ansible /opt/ansible
+RUN <<BUILD_SETUP
+set -eux
+
+apt-get -y update
+apt-get -y upgrade
+apt-get -y --no-install-recommends install \
+    build-essential  \
+    python3-dev \
+    libffi-dev  \
+    rustc
+
+adduser --disabled-password --gecos '' ansible
+python3 -m pip install pip --upgrade
+
+mkdir -p /opt/ansible
+chown -R ansible:ansible /opt/ansible
+BUILD_SETUP
 
 USER ansible
 
@@ -26,16 +34,30 @@ WORKDIR /opt/ansible
 
 ADD pyproject.toml pdm.lock /opt/ansible/
 
-RUN python3 -m pip install --user pdm \
-      && /home/ansible/.local/bin/pdm sync --clean --production --no-editable
+RUN <<BUILD_PROJECT
+set -eux
+
+python3 -m pip install --user pdm
+/home/ansible/.local/bin/pdm sync --clean --production --no-editable
+BUILD_PROJECT
+
+FROM python:3.12-slim-bookworm AS runtime
+
+RUN <<SETUP
+set -eux
+
+apt-get -y update
+apt-get -y upgrade
+apt-get -y --no-install-recommends install \
+  less \
+  nano \
+  vim-nox
 
-FROM python:3.12-slim-bullseye AS runtime
+adduser --disabled-password --gecos '' ansible
 
-RUN apt-get -qqy update \
-      && apt-get -qqy upgrade \
-      && adduser --disabled-password --gecos '' ansible \
-      && mkdir -p /opt/ansible \
-      && chown -R ansible:ansible /opt/ansible
+mkdir -p /opt/ansible
+chown -R ansible:ansible /opt/ansible
+SETUP
 
 COPY --chown=ansible:ansible --from=builder /opt/ansible /opt/ansible
 

README.md

@@ -4,14 +4,14 @@ This is a simple Docker container that contains [Ansible][]. It has been created
 so that it's easier to work with `ansible-playbook` without going through the
 effort of installing it on various systems.
 
-The image is based on Debian Bullseye (slim) and includes:
+The image is based on Debian Bookworm (slim) and includes:
 
-- Ansible 7 (7.7.0 or later)
-- Python 3.11
+- Ansible 8.5.0
+- Python 3.12
 
 These images can be pulled either from Docker Hub
-(`kineticcafe/sqitch-pgtap:2.1`) or the GitHub Container Registry
-(`ghcr.io/kineticcafe/sqitch-pgtap:2.1`).
+(`kineticcafe/ansible:5.0`) or the GitHub Container Registry
+(`ghcr.io/kineticcafe/ansible:5.0`).
 
 ## Support
 
@@ -20,24 +20,52 @@ Tests have been made on Ubuntu 18 and macOS 13 (Apple Silicon).
 Because of recent changes to cryptographic packages in Python, support for
 linux/arm/v7 has been dropped.
 
-## `run` script Commands
+## `kineticcafe-ansible` script Commands
 
-The `run` script is recommended for running everything as it manages environment
-variable configuration for each run. The `run` script will pull from
-`ghcr.io/kineticcafe/ansible:3.1` by default; this can be overridden by
-using `$IMAGE`:
+The `kineticcafe-ansible` script is recommended for running everything as it
+manages environment variable configuration for each run. The
+`kineticcafe-ansible` script will pull from `ghcr.io/kineticcafe/ansible:5.0` by
+default; this can be overridden by using `$IMAGE`:
 
 ```sh
-$ IMAGE=kineticcafe/ansible:latest ./run --version
+$ IMAGE=kineticcafe/ansible:latest ./kineticcafe-ansible --version
 ```
 
+### Installing `kinetic-ansible`
+
+`kinetic-ansible` can be installed with symlinks using the `install` script:
+
+```sh
+curl -sSL --fail \
+  https://raw.githubusercontent.com/KineticCafe/docker-ansible/main/install |
+  bash -s -- ~/.local/bin
+```
+
+Replace `~/.local/bin` with your preferred binary directory.
+
+By default, it will download `kinetic-ansible` from GitHub and install it in the
+provided `TARGET` and make symbolic links for the following Ansible commands:
+`ansible`, `ansible-community`, `ansible-config`, `ansible-connection`,
+`ansible-console`, `ansible-doc`, `ansible-galaxy`, `ansible-inventory`,
+`ansible-playbook`, `ansible-pull`, `ansible-test`, and `ansible-vault`.
+Symbolic link creation will not overwrite files or symbolic links to locations
+_other_ than `TARGET/kinetic-ansible`.
+
+`--no-symlinks` (`-S`) may be specified to skip symbolic link creation entirely.
+
+`--force` (`-f`) may be specified to install `kinetic-ansible` even if it already
+exists, and to overwrite files and non-`TARGET/kinetic-ansible` symbolic links.
+
+`--verbose` (`-v`) will turn on trace output of commands.
+
 ## Maintenance/Upgrade Instructions
 
 1. Install [pdm][]: `pipx install pdm`.
 
 2. Edit the `Dockerfile` to update the Python version, if required.
 
-3. Edit the `pyproject.toml` to change the dependencies, if required.
+3. Edit the `pyproject.toml` to change the dependencies and update the
+   `project.version`.
 
 4. Run `pdm update`.
 

install

@@ -0,0 +1,144 @@
+#! /usr/bin/env bash
+
+readonly url=https://raw.githubusercontent.com/KineticCafe/docker-ansible/main/kineticcafe-ansible
+declare script
+script="$(basename "${url}")"
+readonly script
+
+declare -a symlinked_commands
+symlinked_commands=(
+  ansible ansible-community ansible-config
+  ansible-connection ansible-console ansible-doc
+  ansible-galaxy ansible-inventory ansible-playbook
+  ansible-pull ansible-test ansible-vault
+)
+readonly symlinked_commands
+
+# equivalent to readlink -f
+canonicalize() {
+  local t
+  t="$1"
+
+  cd "$(dirname "${t}")" || return 1
+  t="$(basename "${t}")"
+
+  while [[ -L "${t}" ]]; do
+    t="$(readlink "${t}")"
+    cd "$(dirname "${t}")" || return 1
+    t="$(basename "${t}")"
+  done
+
+  echo "$(pwd -P)/${t}"
+}
+
+usage() {
+  cat <<USAGE
+usage: $(basename "$0") [--no-symlinks|-S] [--force|-f] [--verbose|-v] TARGET
+       $(basename "$0") --help | -h | -?
+
+Installs the ${script} script to TARGET. Installation will be skipped
+if the TARGET/${script} already exists and --force is not supplied.
+
+Unless --no-symlinks is provided, it will also attempt to install symlinks for
+Ansible commands:
+
+  ansible              ansible-community   ansible-config
+  ansible-connection   ansible-console     ansible-doc
+  ansible-galaxy       ansible-inventory   ansible-playbook
+  ansible-pull         ansible-test        ansible-vault
+
+Symlink installation will be skipped if the file already exists and is not
+already a symlink to TARGET/${script} and --force is not supplied.
+USAGE
+}
+
+maybe-verbose() {
+  if "${verbose}"; then
+    set -x && "${@}" && set +x
+  else
+    "${@}"
+  fi
+}
+
+declare force install_symlinks no_download target target_script verbose
+force=false
+install_symlinks=true
+no_download=false
+verbose=false
+
+while (($#)); do
+  case "$1" in
+  --force | -f) force=true ;;
+  --verbose | -v) verbose=true ;;
+  --no-download) no_download=true ;;
+  --no-symlinks | -S) install_symlinks=false ;;
+  --help | -h | -?)
+    usage
+    exit 0
+    ;;
+  *)
+    if [[ ! -d "$1" ]]; then
+      printf >&2 "error: '%s' is not a directory\n\n" "$1"
+      usage >&2
+      exit 1
+    fi
+
+    if [[ -n "${target}" ]]; then
+      printf >&2 "warning: target '%s' is being replaced with '%s'" \
+        "$target" "$1"
+    fi
+
+    target="$1"
+    ;;
+  esac
+
+  shift
+done
+
+if [[ -z "${target}" ]]; then
+  printf >&2 "error: no TARGET provided\n\n"
+  usage >&2
+  exit 1
+fi
+
+target_script="${target}/${script}"
+
+download-script() {
+  if ! curl -sSL --fail "${url}" -o "${target_script}"; then
+    echo >&2 "error: could not download ${url} into ${target_script}."
+    exit 1
+  fi
+}
+
+if "${no_download}"; then
+  if ! [[ -x "${target_script}" ]]; then
+    echo >&2 "error: ${target_script} does not exist and no download is set."
+  fi
+elif [[ -x "${target_script}" ]]; then
+  if ! "${force}"; then
+    echo >&2 "error: ${target_script} already exists."
+    exit 1
+  fi
+
+  maybe-verbose download-script
+
+  [[ -x "${target_script}" ]] || maybe-verbose chmod +x "${target_script}"
+fi
+
+"${install_symlinks}" || exit 0
+
+declare symlinked_command target_command canonical_target
+
+for symlinked_command in "${symlinked_commands[@]}"; do
+  target_command="${target}/${symlinked_command}"
+
+  if [[ -f "${target_command}" ]]; then
+    canonical_target="$(canonicalize "${target_command}")"
+
+    if [[ "${canonical_target}" != "${target_script}" ]]; then
+      "${force}" || continue
+    fi
+  fi
+
+  maybe-verbose ln -sf "${target_script}" "${target_command}"
+done