Added support for building a local docker image

Signed-off-by: Andreas Maier <[email protected]>

.dockerignore

@@ -0,0 +1,33 @@
+# Note: /dist/ is needed in the docker build to access the distribution archive
+
+# User specific configuration files
+/myconfig/
+
+# Make targets
+/*.done
+/done/*.done
+
+# Git stuff not needed in Dockerfile
+/.git
+/.gitignore
+
+# Make build
+/build/
+/*.egg-info/
+/AUTHORS
+/ChangeLog
+/MANIFEST
+
+# Make test
+__pycache__/
+/.pytest_cache/
+/htmlcov/
+/.coverage
+
+# Make builddoc
+/build_docs/
+
+# Other
+*.swp
+.DS_Store
+/try/

Dockerfile

@@ -0,0 +1,77 @@
+# Dockerfile for zhmccli project
+#
+# This image runs the zhmc command.
+#
+# Example docker command to run the zhmc command using a locally built version of this image:
+#
+#   docker run --rm zhmc ...
+
+FROM python:3.12-alpine as builder
+
+# Path name of binary distribution archive of zhmccli package
+ARG bdist_file
+RUN : "${bdist_file:?Build argument bdist_file is required}"
+
+# Install some packages onto this minimal Alpine image:
+# - git - in case the Python requirements use git+https links
+# - gcc musl-dev - in case Python wheels based on C need to be built (e.g. for rpds)
+RUN apk add git gcc musl-dev
+
+# Make sure the installed Python commands are found
+ENV PATH=/root/.local/bin:$PATH
+
+# Install the Python package of this project
+COPY ${bdist_file} /tmp/${bdist_file}
+RUN pip install --user /tmp/${bdist_file}
+
+# Show the installed Linux packages
+RUN echo "Installed Linux packages:" \
+  && apk info -v
+
+# Show the installed Python packages
+RUN echo "Installed Python packages:" \
+  && pip list
+
+# Display files in 'rpds' Python package (verifying that it can be imported)
+RUN echo "Files in rpds Python package:" \
+  && python -c "import rpds, os, sys; rpds_dir=os.path.dirname(rpds.__file__); print(rpds_dir); sys.stdout.flush(); os.system(f'ls -al {rpds_dir}')"
+
+# The Python 'rpds' package (used by 'jsonschema') has a shared library that is
+# built during its installation, and thus depends on APIs of the system and
+# the C library of the builder OS used in the first stage of this Dockerfile.
+# Therefore, the OS used in the final stage needs to be compatible with the
+# builder OS. We use the same OS image to make sure.
+FROM python:3.12-alpine
+
+# Version of the zhmccli package
+ARG package_version
+RUN : "${package_version:?Build argument package_version is required}"
+
+# Image build date in ISO-8601 format
+ARG build_date
+RUN : "${build_date:?Build argument build_date is required}"
+
+# Git commit ID of the zhmccli repo used to build the image
+ARG git_commit
+RUN : "${git_commit:?Build argument git_commit is required}"
+
+# Set image metadata
+LABEL org.opencontainers.image.title="A CLI for the IBM Z HMC"
+LABEL org.opencontainers.image.version="${package_version}"
+LABEL org.opencontainers.image.authors="Juergen Leopold, Andreas Maier"
+LABEL org.opencontainers.image.created="${build_date}"
+LABEL org.opencontainers.image.url="https://github.com/zhmcclient/zhmccli"
+LABEL org.opencontainers.image.documentation="https://zhmccli.readthedocs.io"
+LABEL org.opencontainers.image.source="https://github.com/zhmcclient/zhmccli"
+LABEL org.opencontainers.image.licenses="Apache Software License 2.0"
+LABEL org.opencontainers.image.revision="${git_commit}"
+
+# Copy the installed Python packages from the builder image
+COPY --from=builder /root/.local /root/.local
+
+# Make sure the installed Python commands are found
+ENV PATH=/root/.local/bin:$PATH
+
+EXPOSE 9291
+ENTRYPOINT ["zhmc"]
+CMD ["--help"]

Makefile

@@ -112,6 +112,10 @@ package_name := zhmccli
 # version indicator by 1.
 package_version := $(shell $(PYTHON_CMD) -m setuptools_scm)
 
+# Docker image
+docker_image_name := zhmc
+docker_image_tag := latest
+
 # Python versions
 python_version := $(shell $(PYTHON_CMD) -c "import sys; sys.stdout.write('{v[0]}.{v[1]}.{v[2]}'.format(v=sys.version_info))")
 python_mn_version := $(shell $(PYTHON_CMD) -c "import sys; sys.stdout.write('{v[0]}.{v[1]}'.format(v=sys.version_info))")
@@ -257,6 +261,7 @@ help:
 	@echo "  release_publish - Publish to PyPI when releasing a version (requires VERSION and optionally BRANCH to be set)"
 	@echo "  start_branch - Create a start branch when starting a new version (requires VERSION and optionally BRANCH to be set)"
 	@echo "  start_tag - Create a start tag when starting a new version (requires VERSION and optionally BRANCH to be set)"
+	@echo "  docker     - Build local Docker image $(docker_image_name):$(docker_image_tag)"
 	@echo "  end2end    - Run end2end tests (adds to coverage results)"
 	@echo "  end2end_show - Show HMCs defined for end2end tests"
 	@echo '  authors    - Generate AUTHORS.md file from git log'
@@ -459,6 +464,7 @@ clean:
 	-$(call RMDIR_R_FUNC,.ruff_cache)
 	-$(call RM_FUNC,MANIFEST MANIFEST.in AUTHORS ChangeLog .coverage)
 	-$(call RMDIR_FUNC,build .cache $(package_name).egg-info .eggs)
+	docker image prune --force
 	@echo 'Done: Cleaned out all temporary files.'
 	@echo "Makefile: $@ done."
 
@@ -554,6 +560,10 @@ start_tag:
 all: install develop check_reqs check ruff pylint test build builddoc safety bandit
 	@echo "Makefile: $@ done."
 
+.PHONY: docker
+docker: $(done_dir)/docker_$(pymn)_$(PACKAGE_LEVEL).done
+	@echo "Makefile: $@ done."
+
 $(sdist_file): $(done_dir)/develop_$(pymn)_$(PACKAGE_LEVEL).done pyproject.toml $(dist_dependent_files)
 	@echo "Makefile: Building the source distribution archive: $(sdist_file)"
 	-$(call RM_FUNC,MANIFEST MANIFEST.in)
@@ -566,6 +576,15 @@ $(bdist_file) $(version_file): $(done_dir)/develop_$(pymn)_$(PACKAGE_LEVEL).done
 	$(PYTHON_CMD) -m build --wheel --outdir $(dist_dir) -C--universal .
 	@echo "Makefile: Done building the wheel distribution archive: $(bdist_file)"
 
+$(done_dir)/docker_$(pymn)_$(PACKAGE_LEVEL).done: $(done_dir)/develop_$(pymn)_$(PACKAGE_LEVEL).done Dockerfile .dockerignore $(bdist_file)
+	@echo "Makefile: Building Docker image $(docker_image_name):$(docker_image_tag)"
+	-$(call RM_FUNC,$@)
+	docker build --tag $(docker_image_name):$(docker_image_tag) --build-arg bdist_file=$(bdist_file) --build-arg package_version=$(subst +,.,$(package_version)) --build-arg build_date="$(shell date -Iseconds)" --build-arg git_commit="$(shell git rev-parse HEAD)" .
+	docker run --rm $(docker_image_name):$(docker_image_tag) --version
+	docker image list --filter reference=$(docker_image_name)
+	@echo "Makefile: Done building Docker image"
+	echo "done" >$@
+
 $(done_dir)/pylint_$(pymn)_$(PACKAGE_LEVEL).done: $(done_dir)/develop_$(pymn)_$(PACKAGE_LEVEL).done Makefile $(pylint_rc_file) $(check_py_files)
 	@echo "Makefile: Running Pylint"
 	-$(call RM_FUNC,$@)

changes/627.feature.rst

@@ -0,0 +1 @@
+Added support for building a local docker image.

docs/intro.rst

@@ -135,6 +135,39 @@ installed correctly by invoking:
     1.11.0
 
 
+Running in a Docker container
+-----------------------------
+
+If you want to run the zhmc command in a Docker container instead of installing
+it into a Python environment, you can create the container as follows, using
+the Dockerfile provided in the Git repository.
+
+* Clone the Git repository and switch to the clone's root directory:
+
+  .. code-block:: bash
+
+      $ git clone https://github.com/zhmcclient/zhmccli
+      $ cd zhmccli
+
+* Build a local Docker image as follows:
+
+  .. code-block:: bash
+
+      $ make docker
+
+  This builds a container image named ``zhmc:latest`` in your local Docker
+  environment.
+
+* Run the local Docker image as follows to get help for the zhmc command:
+
+  .. code-block:: bash
+
+      $ docker run --rm zhmc
+
+When running it in the container, the zhmc command cannot be used in
+:ref:`interactive mode`.
+
+
 .. _`Setting up the HMC`:
 
 Setting up the HMC