Add dev Docker container and update GitHub Action

.github/workflows/genicons.yaml

@@ -15,34 +15,40 @@ on:
       - "**.yaml"
 
 jobs:
+
   lint:
     runs-on: ubuntu-latest
-    
+
     steps:
-      - uses: actions/checkout@v1
       - name: Set up Python 3
-        uses: actions/setup-python@v1
+        uses: actions/setup-python@v5
         with:
-          python-version: 3.7
+          # Matches Python3 version on Debian Bookworm
+          python-version: 3.11
       - name: Install pip
         run: |
           python -m pip install --upgrade pip
+      - name: Install Python dependencies
+        run: |
+          pip install black flake8
+      - name: Checkout repository
+        uses: actions/checkout@v4
       - name: Testing with flake8
         run: |
-          pip install flake8
           flake8 ./scripts/genicons.py
       - name: Testing with black
         run: |
-          pip install black
           black --check -l 79 ./scripts/genicons.py
+
   test:
       runs-on: ubuntu-latest
-      
+
       steps:
-        - uses: actions/checkout@v1
         - name: Install dependencies
           run: |
             sudo apt-get install gir1.2-pango-1.0 python3-gi-cairo
+        - name: Checkout repository
+          uses: actions/checkout@v4
         - name: Install CC Fonts
           run: |
             sudo mkdir -p ~/.fonts

README.md

@@ -58,32 +58,67 @@ python3 scripts/genicons.py
 This will generate the icons in the directory `www/i` directory.
 
 
-### Development
-
-- Style/Syntax
-  - Github Actions check the style and syntax with [black][black] and
-    [flake8][flake8]. Run the following commands before submitting a pull
-    request:
-    - Reformat with black using a maxiumum of 79 charaters per line:
-        ```shell
-        black -l 79 ./scripts/genicons.py
-        ```
-    - Check syntax with flake8:
-        ```shell
-        flake8 ./scripts/genicons.py
-        ```
-- Dependencies
-  - *Pycairo is a Python module providing bindings for the cairo graphics
-    library* ([Overview — Pycairo documentation][pycairo]).
-  - *PyGObject is a Python package which provides bindings for GObject based
-    libraries such as GTK, GStreamer, WebKitGTK, GLib, GIO and many more*
-    ([Overview — PyGObject][pygobject]).
-  - PangoCairo is used to load the system fonts and check if the "CC Icons" font
-    is available. See [PangoCairo.FontMap - Interfaces -
-    PangoCairo 1.0][pcfontmap].
+## Development
+
+
+### Setup
+
+Once this project's required dependencies (Docker, Git, etc.) are enabled on
+your system, you will be able to run the legal-tools application and generate
+static files.
+
+For information on learning and installing the prerequisite technologies for 
+this project, please see [Foundational technologies — Creative Commons Open
+Source][found-tech].
+
+[found-tech]: https://opensource.creativecommons.org/contributing-code/foundational-tech/
+
+
+### Docker
+
+1. Build the containers.
+    ```shell
+    docker compose build
+    ```
+2. Run the containers.
+    ```shell
+    docker compose up
+    ```
+3. Generate icons in container
+    ```shell
+    ./dev/genicons.sh
+    ```
+4. Access NGINX site in web container: [127.0.0.1:8080](http://127.0.0.1:8080/)
+
+
+## Style/Syntax
+
+Github Actions check the style and syntax with [black][black] and
+[flake8][flake8]. Run the following commands before submitting a pull request:
+- Reformat with black using a maxiumum of 79 charaters per line:
+    ```shell
+    black -l 79 ./scripts/genicons.py
+    ```
+- Check syntax with flake8:
+    ```shell
+    flake8 ./scripts/genicons.py
+    ```
 
 [black]: https://github.com/python/black
 [flake8]: https://gitlab.com/pycqa/flake8
+
+
+### Dependencies
+
+- *Pycairo is a Python module providing bindings for the cairo graphics
+  library* ([Overview — Pycairo documentation][pycairo]).
+- *PyGObject is a Python package which provides bindings for GObject based
+  libraries such as GTK, GStreamer, WebKitGTK, GLib, GIO and many more*
+  ([Overview — PyGObject][pygobject]).
+- PangoCairo is used to load the system fonts and check if the "CC Icons" font
+  is available. See [PangoCairo.FontMap - Interfaces -
+  PangoCairo 1.0][pcfontmap].
+
 [pycairo]: https://pycairo.readthedocs.io/en/latest/
 [pygobject]: https://pygobject.readthedocs.io/en/latest/index.html
 [pcfontmap]: https://lazka.github.io/pgi-docs/PangoCairo-1.0/classes/FontMap.html#PangoCairo.FontMap

dev/Dockerfile

@@ -0,0 +1,25 @@
+# https://docs.docker.com/engine/reference/builder/
+
+# https://hub.docker.com/_/debian
+FROM debian:bookworm-slim
+
+# Configure apt not to prompt during docker build
+ARG DEBIAN_FRONTEND=noninteractive
+
+# Configure apt to avoid installing recommended and suggested packages
+RUN apt-config dump \
+    | grep -E '^APT::Install-(Recommends|Suggests)' \
+    | sed -e's/1/0/' \
+    | tee /etc/apt/apt.conf.d/99no-recommends-no-suggests
+
+# Resynchronize the package index and install packages
+# https://docs.docker.com/build/building/best-practices/#apt-get
+RUN apt-get update && apt-get install -y \
+        curl \
+        git \
+        gir1.2-pango-1.0 \
+        libnginx-mod-http-fancyindex \
+        nginx-light \
+        python3-gi-cairo \
+        tree \
+    && rm -rf /var/lib/apt/lists/*

dev/etc-nginx-sites-available-default

@@ -0,0 +1,18 @@
+server {
+    listen 80;
+    server_name localhost;
+    root /srv/licensebuttons/www;
+    location /i {
+        fancyindex on;
+        fancyindex_header /header.html;
+        fancyindex_footer /footer-i.html;
+        fancyindex_exact_size off;
+    }
+    location / {
+        fancyindex on;
+        fancyindex_header /header.html;
+        fancyindex_footer /footer.html;
+        fancyindex_exact_size off;
+    }
+}
+# vim: ft=nginx

dev/genicons.sh

@@ -0,0 +1,73 @@
+#!/usr/bin/env bash
+#
+# Run Python code tools (isort, black, flake8)
+#
+#### SETUP ####################################################################
+
+set -o errexit
+set -o errtrace
+set -o nounset
+
+# shellcheck disable=SC2154
+trap '_es=${?};
+    printf "${0}: line ${LINENO}: \"${BASH_COMMAND}\"";
+    printf " exited with a status of ${_es}\n";
+    exit ${_es}' ERR
+
+DIR_REPO="$(cd -P -- "${0%/*}/.." && pwd -P)"
+# https://en.wikipedia.org/wiki/ANSI_escape_code
+E0="$(printf "\e[0m")"        # reset
+E30="$(printf "\e[30m")"      # black foreground
+E31="$(printf "\e[31m")"      # red foreground
+E107="$(printf "\e[107m")"    # bright white background
+
+#### FUNCTIONS ################################################################
+
+check_docker() {
+    local _msg
+    if ! docker compose exec web true 2>/dev/null; then
+        _msg='The app container/services is not avaialable.'
+        _msg="${_msg}\n       First run \`docker compose up\`."
+        error_exit "${_msg}"
+    fi
+}
+
+error_exit() {
+    # Echo error message and exit with error
+    echo -e "${E31}ERROR:${E0} ${*}" 1>&2
+    exit 1
+}
+
+icon_stats() {
+    local _count _size
+    print_header 'Icons stats'
+    echo '/srv/licensebuttons/www/i'
+    _count=$(docker compose exec web find /srv/licensebuttons/www/i -type f \
+        | wc -l | tr -d '[:space:]')
+    _size=$(docker compose exec web du -sh /srv/licensebuttons/www/i \
+        | awk '{print $1}')
+    printf '    %11s %5s\n'  'File count:' "${_count}"
+    printf '    %11s %5s\n'  'Size:' "${_size}"
+    echo
+}
+
+print_header() {
+    # Print 80 character wide black on white heading with time
+    printf "${E30}${E107}# %-69s$(date '+%T') ${E0}\n" "${@}"
+}
+
+#### MAIN #####################################################################
+
+cd "${DIR_REPO}"
+
+check_docker
+
+icon_stats
+
+print_header 'Generate icons in Docker container'
+docker compose exec web \
+    /usr/bin/python3 /srv/licensebuttons/scripts/genicons.py
+echo 'done.'
+echo
+
+icon_stats

docker-compose.yml

@@ -0,0 +1,24 @@
+# https://docs.docker.com/compose/compose-file/
+
+services:
+  web:
+    build:
+      dockerfile: dev/Dockerfile
+    command: sh -c "
+      echo 'Starting static webserver at http://127.0.0.1:8080/'
+      && nginx -g 'daemon off;'
+      "
+    init: true
+    ports:
+      - '8080:80'
+    restart: on-failure
+    volumes:
+      - .:/srv/licensebuttons
+      - ./dev/etc-nginx-sites-available-default:/etc/nginx/sites-available/default:ro
+      - ./www/cc-icons.ttf:/root/.fonts/cc-icons.ttf:ro
+      - licbuttons-www-i:/srv/licensebuttons/www/i
+    working_dir: /srv/licensebuttons
+
+volumes:
+ licbuttons-www-i:
+    name: licbuttons-www-i