Merge pull request #5 from obeone:code_documentation

docs: improve comments, docstrings, and user guidance throughout codebase

Author: obeone

.github/workflows/build-and-publish.yaml

@@ -16,7 +16,7 @@ jobs:
     permissions:
       contents: read
       packages: write
-      id-token: write # For cosign
+      id-token: write # Permission for cosign signing
 
     steps:
       - name: Checkout code
@@ -30,24 +30,29 @@ jobs:
 
       - name: Determine tags
         run: |
+          # Initialize tags with latest tags for GitHub Container Registry and Docker Hub
           TAGS="ghcr.io/obeone/multi-registry-cache:latest,docker.io/obeoneorg/multi-registry-cache:latest"
 
+          # If this is a release event, add version-specific tags
           if [[ "${{ github.event_name }}" == "release" ]]; then
             VERSION=${{ github.event.release.tag_name }}
             VERSION=${VERSION#v} # Remove 'v' prefix if present
             MAJOR=$(echo $VERSION | cut -d. -f1)
             MINOR=$(echo $VERSION | cut -d. -f2)
             PATCH=$(echo $VERSION | cut -d. -f3)
 
+            # Add version tags for GitHub Container Registry
             TAGS="$TAGS,ghcr.io/obeone/multi-registry-cache:v$VERSION,ghcr.io/obeone/multi-registry-cache:$VERSION"
             TAGS="$TAGS,ghcr.io/obeone/multi-registry-cache:v$MAJOR.$MINOR,ghcr.io/obeone/multi-registry-cache:$MAJOR.$MINOR"
             TAGS="$TAGS,ghcr.io/obeone/multi-registry-cache:v$MAJOR,ghcr.io/obeone/multi-registry-cache:$MAJOR"
 
+            # Add version tags for Docker Hub
             TAGS="$TAGS,docker.io/obeoneorg/multi-registry-cache:v$VERSION,docker.io/obeoneorg/multi-registry-cache:$VERSION"
             TAGS="$TAGS,docker.io/obeoneorg/multi-registry-cache:v$MAJOR.$MINOR,docker.io/obeoneorg/multi-registry-cache:$MAJOR.$MINOR"
             TAGS="$TAGS,docker.io/obeoneorg/multi-registry-cache:v$MAJOR,docker.io/obeoneorg/multi-registry-cache:$MAJOR"
           fi
 
+          # Export tags as environment variable for later steps
           echo "DOCKER_TAGS=$TAGS" >> $GITHUB_ENV
 
       - name: Log in to GitHub Container Registry
@@ -85,6 +90,7 @@ jobs:
       - name: Sign the container image with cosign
         if: github.event_name == 'push' && github.ref == 'refs/heads/main' || github.event_name == 'release'
         run: |
+          # Sign each tag with cosign using the image digest
           for tag in $(echo $DOCKER_TAGS | tr ',' '\n'); do
             cosign sign --yes $tag@${DIGEST}
           done

CONFIG.md

@@ -187,16 +187,16 @@ registry:
 
 #### Automatic
 
-- Run `python setup.py` and fine-tune settings in `config.yaml`after that.
-- And run `python generate.py` to generate all files in `compose` directory.
+- Run `python setup.py` and fine-tune settings in `config.yaml` afterwards.
+- Then run `python generate.py` to generate all files in the `compose` directory.
 
 #### Manual
 
 1. Copy `config.sample.yaml` to `config.yaml`.
 2. Fill in your registry credentials and other settings.
-3. Set everything else (especially hosts)
-4. Execute `python generate.py` to generate all files in `compose` directory.
-5. Go in that directory (`cd compose`)
+3. Set everything else (especially hosts).
+4. Execute `python generate.py` to generate all files in the `compose` directory.
+5. Go into that directory (`cd compose`).
 6. Run `docker compose up -d` to start the services.
 
 By following these steps, you can configure and run your multi-registry environment with Traefik and Redis caching, simplifying the management of multiple container registries.

docker/Dockerfile

@@ -1,39 +1,45 @@
 # syntax=docker/dockerfile:1
-
-# Start the build stage for creating wheels
+#
+# Dockerfile for building and running the Python application.
+# It uses a multi-stage build to create wheel files for dependencies
+# in a full Python environment, then installs them in a slim Python image
+# to reduce the final image size.
+#
+# Stage 1: Build wheels for dependencies
 FROM python:3.12 AS wheel
 
-# Set the working directory
+# Set the working directory inside the container
 WORKDIR /app
 
 # Copy the requirements file to the working directory
 COPY requirements.txt .
 
-# Install wheel and create wheel files for the requirements
+# Install wheel package and build wheel files for all dependencies listed in requirements.txt
 RUN --mount=type=cache,target=/root/.cache/pip \
     pip install wheel && \
     pip wheel --exists-action i -r requirements.txt --wheel-dir /root/.cache/wheel
 
-# Start the final image using a slimmer version of Python
+# Stage 2: Create the final image with a slim Python base
 FROM python:3.12-slim
 
+# Environment variable to indicate running inside Docker
 ENV IN_DOCKER=1
 
-# Set the working directory
+# Set the working directory inside the container
 WORKDIR /app
 
 # Copy the requirements file to the working directory
 COPY requirements.txt .
 
-# Install the dependencies from the wheel files created in the previous stage
+# Install dependencies from the pre-built wheel files from the previous stage
 RUN --mount=type=bind,from=wheel,source=/root/.cache/wheel,dst=/root/.cache/wheel \
     pip install --no-index --find-links=/root/.cache/wheel -r requirements.txt
 
-# Copy the entire application code to the working directory
+# Copy the entire application code into the container
 COPY . .
 
-# Copy the entrypoint script and set the appropriate permissions
+# Copy the entrypoint script and set executable permissions
 COPY --chmod=777 docker/entrypoint.sh /
 
-# Specify the entrypoint for the container
+# Set the entrypoint for the container
 ENTRYPOINT [ "/entrypoint.sh" ]

docker/entrypoint.sh

@@ -1,11 +1,27 @@
 #!/usr/bin/env bash
 
+# Entrypoint script for Docker container
+# This script checks the first argument and executes the corresponding Python script or command.
+# Usage:
+#   ./entrypoint.sh setup [args]    - Runs python setup.py with the given arguments
+#   ./entrypoint.sh generate [args] - Runs python generate.py with the given arguments
+#   ./entrypoint.sh [command]       - Executes the given command
+
+# Check if the first argument is empty
+if [ -z "$1" ]; then
+    echo "No command provided. Exiting."
+    exit 1
+fi
+
 if [ "$1" == "setup" ]; then
     shift
+    # Execute setup.py with remaining arguments
     exec python setup.py "$@"
 elif [ "$1" == "generate" ]; then
     shift
+    # Execute generate.py with remaining arguments
     exec python generate.py "$@"
 else
+    # Execute the provided command as is
     exec "$@"
 fi

functions.py

@@ -36,56 +36,63 @@ def interpolate_strings(obj, variables):
         return obj
 
 
-def create_docker_service(registry, custom={}):
-    """Creates a docker service for the registry.
-    
+def create_docker_service(registry, custom=None):
+    """
+    Creates a docker service for the registry.
+
     Args:
         registry (dict): A dictionary containing the registry information.
-        custom (dict): A dictionary of customizations to apply to the 
-            docker service.
+        custom (dict, optional): A dictionary of customizations to apply to the
+            docker service. Defaults to None.
+
     Returns:
         dict: The docker service.
     """
-    obj = {
-    }
+    if custom is None:
+        custom = {}
+
+    obj = {}
     obj.update(custom)
 
     console.print(Text("Docker service created for the registry", style="green"))
     return interpolate_strings(obj, registry)
 
 
-def create_traefik_router(registry, custom={}):
+def create_traefik_router(registry, custom=None):
     """
     Creates a Traefik router object for a given registry.
 
     Args:
         registry (str): The name of the registry.
-        custom (dict, optional): A dictionary of custom router properties. Defaults to {}.
+        custom (dict, optional): A dictionary of custom router properties. Defaults to None.
 
     Returns:
         dict: A dictionary representing the Traefik router object.
     """
-    obj = {
-    }
-    
+    if custom is None:
+        custom = {}
+
+    obj = {}
     obj.update(custom)
 
     console.print(Text("Traefik router object created", style="green"))
     return interpolate_strings(obj, registry)
 
-def create_traefik_service(registry, custom={}):
+def create_traefik_service(registry, custom=None):
     """
     Creates a Traefik service object with a load balancer configuration that points to the specified registry.
 
     Args:
         registry (str): The URL of the registry to point the load balancer to.
-        custom (dict, optional): A dictionary of custom configuration options to add to the service object. Defaults to {}.
+        custom (dict, optional): A dictionary of custom configuration options to add to the service object. Defaults to None.
 
     Returns:
         dict: A Traefik service object with the specified load balancer configuration.
     """
-    obj = {
-    }
+    if custom is None:
+        custom = {}
+
+    obj = {}
     obj.update(custom)
 
     console.print(Text("Traefik service object created", style="green"))
@@ -118,8 +125,11 @@ def create_registry_config(config, registry, db):
 
     interpolated = interpolate_strings(config, registry)
 
-    if 'redis' in interpolated:
-        interpolated['redis']['db'] = int(db)
+    if isinstance(interpolated, dict) and 'redis' in interpolated:
+        # Ensure 'redis' is a dictionary before setting 'db'
+        redis_config = interpolated.get('redis')
+        if isinstance(redis_config, dict):
+            redis_config['db'] = int(db)
 
     console.print(Text("Registry configuration created", style="green"))
     return interpolated
@@ -156,8 +166,9 @@ def write_http_secret():
     """
     Write the HTTP secret to the .env file if it does not exist or if REGISTRY_HTTP_SECRET is not already set.
     """
-    if not os.path.exists('compose/.env') or 'REGISTRY_HTTP_SECRET' not in open('compose/.env').read():
-        with open('compose/.env', 'a') as env_file:
+    env_path = 'compose/.env'
+    if not os.path.exists(env_path) or 'REGISTRY_HTTP_SECRET' not in open(env_path).read():
+        with open(env_path, 'a') as env_file:
             env_file.write(f"REGISTRY_HTTP_SECRET={secrets.token_hex(32)}\n")
         console.print(Text("HTTP secret written to .env file", style="green"))
     else:

generate.py

@@ -1,7 +1,10 @@
 """
-This module sets up a multi-registry environment by creating configuration files 
-for Docker Compose, registry and Traefik.
+This module sets up a multi-registry environment by creating configuration files
+for Docker Compose, registry, and Traefik.
 See the README.md file for more information.
+
+Usage:
+    Run this script to generate configuration files based on the config.yaml.
 """
 import os
 import yaml
@@ -11,7 +14,7 @@
 import copy
 
 
-# Load config
+# Load configuration from config.yaml file
 try:
     with open('config.yaml', 'r', encoding='UTF-8') as file:
         base_config = yaml.safe_load(file)
@@ -20,6 +23,7 @@
     console.print(Text("Error: config.yaml not found", style="bold red"))
     raise
 
+# Extract configuration sections from the loaded config
 try:
     registries = base_config['registries']
     docker_config = base_config['docker']['baseConfig']
@@ -31,26 +35,29 @@
     console.print(Text(f"Error: Missing key in config file - {e}", style="bold red"))
     raise
 
-# Create a compose directory to store the configuration files
+# Create a compose directory to store the configuration files if it does not exist
 if not os.path.exists('compose'):
     os.mkdir('compose')
     os.mkdir('compose/acme')
     console.print(Text("Compose directory created", style="bold green"))
 else:
     console.print(Text("Compose directory already exists", style="bold yellow"))
 
-# Adding services to docker-compose and routers to traefik
+# Initialize Redis database count for registries
 count_redis_db = 0
+
+# Iterate over each registry to create configuration files and update docker and traefik configs
 for registry in registries:
     name = registry['name']
 
-    # Creating registry configuration file
+    # Create registry configuration file
     try:
-        # Retrocompatibility with old config files without type field
+        # Retrocompatibility with old config files without 'type' field
         if 'type' not in registry:
             registry['type'] = 'cache'
             console.print(Text(f"No type specified for registry {name}, defaulting to cache", style="bold yellow"))
 
+        # Deep copy base registry config and create specific config for this registry
         registry_config_copy = copy.deepcopy(registry_config)
         registry_config_file = functions.create_registry_config(registry_config_copy, registry, count_redis_db)
         functions.write_yaml_file(f'compose/{name}.yaml', registry_config_file)
@@ -59,15 +66,15 @@
         console.print(Text(f"Error creating registry configuration file for {name}: {e}", style="bold red"))
         raise
 
-    # Unsset password before interpolate variables
+    # Unset password before interpolating variables to avoid leaking sensitive data
     try:
         if 'password' in registry:
             registry.pop('password')
     except KeyError:
         console.print(Text(f"Error: Missing 'password' key in registry configuration for {name}", style="bold red"))
         raise
 
-    # Creating docker-compose and traefik configuration
+    # Create docker-compose and traefik configuration entries for this registry
     try:
         docker_config['services'][name] = functions.create_docker_service(registry, docker_perregistry['compose'])
         traefik_config['http']['routers'][name] = functions.create_traefik_router(registry, traefik_perregistry['router'])
@@ -77,12 +84,15 @@
         console.print(Text(f"Error creating docker-compose and traefik configuration for {name}: {e}", style="bold red"))
         raise
 
+    # Increment Redis database count for next registry
     count_redis_db += 1
 
+# Write final configuration files and handle deprecated docker-compose.yml file
 try:
     functions.write_yaml_file('compose/compose.yaml', docker_config)
     functions.write_yaml_file('compose/traefik.yaml', traefik_config)
     functions.write_to_file('compose/redis.conf', f'databases {count_redis_db}')
+
     # If docker-compose.yml exists, ask for confirmation before removing it
     docker_compose_path = 'compose/docker-compose.yml'
     if os.path.exists(docker_compose_path):
@@ -93,10 +103,10 @@
             console.print(Text("Existing docker-compose.yml file removed", style="bold blue"))
         else:
             console.print(Text("docker-compose.yml file not removed", style="bold yellow"))
-    
-    
+
+    # Write HTTP secret file
     functions.write_http_secret()
-        
+
     console.print(Text("Configuration files written successfully", style="bold green"))
 except Exception as e:
     console.print(Text(f"Error writing configuration files: {e}", style="bold red"))