Docker and Python build enhancements (#1547)

Misc. Docker and Python improvements

* Add standardized metadata to the Docker image, including the version, commit hash, and build timestamp. This makes it easier to determine what the container was actually built from.
* Cleanup docker/README. Remove old unsupported docker-compose and replace with modern docker compose, add some missing variables, add some aliases, and some formatting tweaks.
* Add and cleanup Python package metadata in setup.py, notably README formatting, and python_version (which helps pip and dependency resolvers like PDM and Poetry).

.github/workflows/docker.yml

@@ -9,24 +9,31 @@ jobs:
       contents: read
     steps:
       - name: Check out the repo
-        uses: actions/checkout@v2
-      - name: Get short SHA
-        id: short
+        uses: actions/checkout@v4
+      - name: Get metadata
+        id: build_metadata
         run: |
           echo "::set-output name=sha::$(git rev-parse --short HEAD)"
           echo "::set-output name=branch::$(echo ${GITHUB_REF#refs/heads/})"
+          echo "::set-output name=mmversion::$(cat VERSION)"
+          echo "::set-output name=buildtime::$(date -I'seconds')"
+          echo "::set-output name=repolowercase::$(echo ${GITHUB_REPOSITORY,,})"
       - name: Log in to GitHub Docker Registry
-        uses: docker/login-action@v1
+        uses: docker/login-action@v3
         with:
           registry: ghcr.io
           username: ${{ github.actor }}
           password: ${{ secrets.GITHUB_TOKEN }}
       - name: Build container image
-        uses: docker/build-push-action@v2
+        uses: docker/build-push-action@v6
         with:
           context: .
           file: docker/Dockerfile
+          build-args: |
+            MM_COMMIT=${{ github.sha }}
+            MM_VERSION=${{ steps.build_metadata.outputs.mmversion }}
+            BUILD_TIME=$${ steps.build_metadata.outputs.buildtime }}
           push: true
           tags: |
-            ghcr.io/${{ github.repository }}/minimega:${{ steps.short.outputs.sha }}
-            ghcr.io/${{ github.repository }}/minimega:${{ steps.short.outputs.branch }}
+            ghcr.io/${{ steps.build_metadata.outputs.repolowercase }}/minimega:${{ steps.build_metadata.outputs.sha }}
+            ghcr.io/${{ steps.build_metadata.outputs.repolowercase }}/minimega:${{ steps.build_metadata.outputs.branch }}

CONTRIBUTORS

@@ -10,6 +10,7 @@ Jeremy Erickson <[email protected]>
 John Floren <[email protected]>
 David Fritz <[email protected]>
 Jason Gao <[email protected]>
+Christopher Goes <[email protected]>
 Casey Glatter <[email protected]>
 Arthur Hernandez <[email protected]>
 Darek Jensen <[email protected]>

docker/Dockerfile

@@ -1,5 +1,10 @@
+# To specify an alternate base image: --build-arg BASE_IMAGE="some/other/image:tag"
+ARG BASE_IMAGE="ubuntu:22.04"
+
+# -- go builder --
 FROM golang:1.18.2 AS gobuilder
 
+ENV DEBIAN_FRONTEND="noninteractive"
 RUN apt-get update && apt-get install -y libpcap-dev
 
 WORKDIR /minimega/
@@ -9,14 +14,34 @@ COPY . .
 RUN ./scripts/all.bash
 
 
-FROM ubuntu:22.04
-
-RUN apt update && apt install -y \
-  dnsmasq iproute2 isc-dhcp-client \
-  libpcap-dev ntfs-3g openssh-client \
-  openvswitch-switch qemu-kvm qemu-utils \
+# -- minimega image --
+FROM ${BASE_IMAGE}
+
+# General image metadata
+# Reference: https://github.com/opencontainers/image-spec/blob/main/annotations.md
+ARG BUILD_TIME
+ARG MM_VERSION
+ARG MM_COMMIT
+LABEL org.opencontainers.image.created="${BUILD_TIME}" \
+  org.opencontainers.image.authors="minimega dev team <[email protected]>" \
+  org.opencontainers.image.documentation="https://www.sandia.gov/minimega/" \
+  org.opencontainers.image.source="https://github.com/sandia-minimega/minimega" \
+  org.opencontainers.image.version="${MM_VERSION}" \
+  org.opencontainers.image.revision="${MM_COMMIT}" \
+  org.opencontainers.image.vendor="Sandia National Laboratories" \
+  org.opencontainers.image.licenses="GPL-3.0-only" \
+  org.opencontainers.image.title="minimega" \
+  org.opencontainers.image.description="minimega is a tool for launching and managing virtual machines"
+
+ENV DEBIAN_FRONTEND="noninteractive"
+
+RUN apt-get update \
+  && apt-get install -y \
+    dnsmasq iproute2 isc-dhcp-client \
+    libpcap-dev ntfs-3g openssh-client \
+    openvswitch-switch qemu-kvm qemu-utils \
   && apt autoremove -y \
-  && apt clean -y\
+  && apt-get clean -y \
   && rm -rf /var/lib/apt/lists/* \
   && rm -rf /var/cache/apt/archives/*
 

docker/README.md

@@ -1,12 +1,13 @@
-# minimega docker
+# minimega Docker
 
-### Install docker
+## Install Docker
+
+Follow the official installation instructions: [Install Docker Engine](https://docs.docker.com/engine/install/)
+
+For development purposes, it maybe helpful to add your user to the `docker` group: `sudo usermod -aG docker $USER`
 
-```bash
-sudo apt-get install docker.io
-```
 
-### Build the minimega docker image
+## Build the minimega Docker image
 
 > NOTE: Currently, only minimega, miniweb, miniccc, minirouter, and protonuke
 > will exist in the minimega docker image. If you need additional binaries, add
@@ -17,9 +18,12 @@ sudo apt-get install docker.io
 
 ```bash
 docker build -t minimega -f docker/Dockerfile .
+
+# Ensure the build was successful
+docker run -it minimega /opt/minimega/bin/minimega --version
 ```
 
-### Start the minimega docker container
+## Start the minimega Docker container
 
 > NOTE: The additional privileges and system mounts (e.g. /dev) are required for
 > the openvswitch process to run inside the container and to allow minimega to
@@ -46,47 +50,45 @@ docker run -d \
   minimega
 ```
 
-The container runs the `start-minimega.sh` script as PID 1, which takes care of
-starting openvswitch, miniweb, and finally minimega. This means the minimega
-logs will be available in the container logs via Docker.
-
----
+The container runs the `start-minimega.sh` script as PID 1, which takes care of starting openvswitch, miniweb, and finally minimega. This means the minimega logs will be available in the container logs via Docker (`docker logs minimega`).
 
-# Using docker-compose
 
-### Install docker-compose
+# Using Docker Compose
 
-```bash
-VERSION=`git ls-remote https://github.com/docker/compose | grep refs/tags | grep -oP "[0-9]+\.[0-9][0-9]+\.[0-9]+$" | sort | tail -n 1`
-sudo curl -ksL "https://github.com/docker/compose/releases/download/${VERSION}/docker-compose-$(uname -s)-$(uname -m)" -o /usr/local/bin/docker-compose
-sudo chmod +x /usr/local/bin/docker-compose
-```
+If you followed the [Docker installation instructions](https://docs.docker.com/engine/install/), then `docker compose` should already be installed. Verify this by running `docker compose version`.  If it's not, then install it: `sudo apt install docker-compose-plugin`
 
-### Start the minimega docker container
+Start the minimega Docker container with Docker Compose:
 
 ```bash
-docker-compose up -d
+cd docker/
+docker compose up -d
+docker compose logs -f  # CTRL+C to stop following logs
 ```
 
----
 
 # Extras
 
-### Convenience aliases
+## Convenience aliases
 
 ```bash
 cat <<EOF >> ~/.bash_aliases
-alias minimega='docker exec -it minimega minimega '
+alias mm='docker exec -it minimega minimega -e'
+alias mminfo='mm .columns name,state,ip,snapshot,cc_active vm info'
+alias mmsum='mm .columns name,state,cc_active,uuid vm info summary'
+alias minimega='docker exec -it minimega minimega'
 alias ovs-vsctl='docker exec -it minimega ovs-vsctl'
 EOF
+
 source ~/.bash_aliases
 ```
 
-### minimega and miniweb configuration
+On Ubuntu, `~/.bash_aliases` should be auto-sourced by `~/.profile` or `~/.bashrc` on login, so the source command is only needed to load them into current session.
+
+## minimega and miniweb configuration
 
 By default, the following values are set for minimega:
 
-```
+```shell
 MM_BASE=/tmp/minimega
 MM_FILEPATH=/tmp/minimega/files
 MM_BROADCAST=255.255.255.255
@@ -95,11 +97,14 @@ MM_DEGREE=2
 MM_CONTEXT=minimega
 MM_LOGLEVEL=info
 MM_LOGFILE=/var/log/minimega.log
+MM_FORCE=true
+MM_RECOVER=false
+MM_CGROUP=/sys/fs/cgroup
 ```
 
 By default, the following values are set for miniweb:
 
-```
+```shell
 MINIWEB_ROOT=/opt/minimega/misc/web
 MINIWEB_HOST=0.0.0.0
 MINIWEB_PORT=9001
@@ -120,7 +125,6 @@ Docker when starting the container or by binding a file to
 
 Additional values can be appended to the minimega command by using:
 
-```
+```shell
 MM_APPEND="-hashfiles -headnode=foo1"
 ```
-

docker/docker-compose.yml

@@ -1,4 +1,3 @@
-version: '3.7'
 services:
   minimega:
     build:

lib/setup.py

@@ -1,4 +1,4 @@
-from distutils.core import setup
+from setuptools import setup
 
 
 with open("README", "r") as readme_file:
@@ -9,14 +9,23 @@
 
 setup(
     name='minimega',
-    description="Python API for minimega",
+    version=version,
     author="minimega dev team",
     author_email="[email protected]",
+    description="Python API for minimega",
     long_description=readme_content,
+    long_description_content_type="text/markdown",
     license="GPLv3",
-    url="https://minimega.org",
-    version=version,
+    url="https://www.sandia.gov/minimega/",
+    project_urls={
+        "homepage": "https://www.sandia.gov/minimega/",
+        "repository": "https://github.com/sandia-minimega/minimega",
+        "changelog": "https://www.sandia.gov/minimega/minimega-2-9-release-notes/",
+        "documentation": "https://www.sandia.gov/minimega/using-minimega/",
+        "issues": "https://github.com/sandia-minimega/minimega/issues",
+    },
     py_modules=["minimega"],
+    python_requires=">=3.6",
     classifiers=[
         "Development Status :: 5 - Production/Stable",
         "Environment :: Console",
@@ -30,6 +39,11 @@
         "Programming Language :: Python",
         "Programming Language :: Python :: 3",
         "Programming Language :: Python :: 3.6",
+        "Programming Language :: Python :: 3.7",
+        "Programming Language :: Python :: 3.8",
+        "Programming Language :: Python :: 3.9",
+        "Programming Language :: Python :: 3.10",
+        "Programming Language :: Python :: Implementation :: CPython",
         "Topic :: Internet",
         "Topic :: Scientific/Engineering",
         "Topic :: System :: Clustering",