move env vars around; clean up documentation

Author: niquerio

Dockerfile

@@ -1,11 +1,21 @@
+################################################################################
+# BASE                                                                         #
+################################################################################
 FROM python:3.11-slim-bookworm as base
 
 ARG POETRY_VERSION=1.8.3
 ARG UID=1000
 ARG GID=1000
 
+# Where python should look for packages and modules when using import
 ENV PYTHONPATH="/app"
 
+# Ensure the stdout and stderr streams are sent straight to terminal
+ENV PYTHONUNBUFFERED=1 
+
+# Extend the socket timeout. Default would be 15s
+ENV  PIP_DEFAULT_TIMEOUT=100 
+
 RUN groupadd -g ${GID} -o app
 RUN useradd -m -d /app -u ${UID} -g ${GID} -o -s /bin/bash app
 
@@ -16,55 +26,61 @@ WORKDIR /app
 
 CMD ["tail", "-f", "/dev/null"]
 
-# Both build and development need poetry, so it is its own step.
+################################################################################
+# POETRY
+################################################################################
+#
+# Both BUILD and DEVELOPMENT need poetry
+# 
 FROM base AS poetry
 
 RUN pip install poetry==${POETRY_VERSION}
 
-# Use this page as a reference for python and poetry environment variables:
-# https://docs.python.org/3/using/cmdline.html#envvar-PYTHONUNBUFFERED Ensure
-# the stdout and stderr streams are sent straight to terminal, then you can see
-# the output of your application
-
-ENV PYTHONUNBUFFERED=1\
-    # Avoid the generation of .pyc files during package install
-    # Disable pip's cache, then reduce the size of the image
-    PIP_NO_CACHE_DIR=off \
-    # Save runtime because it is not look for updating pip version
-    PIP_DISABLE_PIP_VERSION_CHECK=on \
-    PIP_DEFAULT_TIMEOUT=100 \
-    # Disable poetry interaction
-    POETRY_NO_INTERACTION=1 \
-    POETRY_VIRTUALENVS_CREATE=1 \
-    POETRY_VIRTUALENVS_IN_PROJECT=1 \
-    POETRY_CACHE_DIR=/tmp/poetry_cache
+# Ensure that the virtual environment directory is in the project. This path
+# will be be `/app/.venv/`
+ENV  POETRY_VIRTUALENVS_IN_PROJECT=1 
 
+# Create the virtual environment if it does not already exist
+ENV  POETRY_VIRTUALENVS_CREATE=1 
 
+################################################################################
+# BUILD                                                                        #
+################################################################################
+#
+# This step uses poetry to generate a requirements.txt file for PRODUCTION
+#
 FROM poetry AS build
 
-# Just copy the files needed to install the dependencies
+# README.md is needed so that poetry command will work.
 COPY pyproject.toml poetry.lock README.md ./
 
-#Use poetry to create a requirements.txt file. Dont include development dependencies
 RUN poetry export --without dev -f requirements.txt --output requirements.txt
 
-
-# We want poetry on in development
+################################################################################
+# DEVELOPMENT                                                                  #
+################################################################################
+#
+# In development we want poetry in the container, so it inherits from the POETRY
+# step.  This step is the place to install development-only sytem dependencies
+#
 FROM poetry AS development
 
-# Install development system dependencies
 # RUN apt-get update -yqq && apt-get install -yqq --no-install-recommends \
 #   wget\
 
-# Switch to the non-root user "user"
 USER app
 
-
-# We don't want poetry on in production, so we copy the needed files form the build stage
+################################################################################
+# PRODUCTION                                                                   #
+################################################################################
 FROM base AS production
-# Switch to the non-root user "user"
-# RUN mkdir -p /venv && chown ${UID}:${GID} /venv
 
+# Setting this to 'off' actually turns off the cache. This is set to decrease
+# the size of the image.
+ENV  PIP_NO_CACHE_DIR=off 
+
+# Speed up pip usage by not checking for the version
+ENV  PIP_DISABLE_PIP_VERSION_CHECK=on 
 
 COPY --chown=${UID}:${GID} . /app
 COPY --chown=${UID}:${GID} --from=build "/app/requirements.txt" /app/requirements.txt