[WIP, draft] Improve Docker support

.github/workflows/tests.yml

@@ -35,3 +35,14 @@ jobs:
           node-version: ${{ matrix.node-version }}
       - run: npm ci
       - run: npm test
+
+  test-docker:
+    name: test on base Docker image 'node:${{ matrix.node-version }}-alpine'
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: true
+      matrix:
+        node-version: [18, 20]
+    steps:
+      - uses: actions/checkout@v4
+      - run: docker build . --build-arg BASE_IMAGE=node:${{ matrix.node-version }}-alpine -t pa11y-ci-on-node-${{ matrix.node-version }}-alpine

Dockerfile

@@ -0,0 +1,31 @@
+ARG BASE_IMAGE=node:20-alpine
+FROM $BASE_IMAGE
+
+# Install Chromium
+RUN apk add --no-cache \
+	chromium
+
+# Install Chromium's dependencies
+RUN apk add --no-cache \
+	ca-certificates \
+	freetype \
+	harfbuzz \
+	nss \
+	ttf-freefont
+
+# Switch user from 'root' to 'node' (inherited from node:alpine)
+USER node
+
+# Let's install global dependencies somewhere visitable by user 'node'
+ENV NPM_CONFIG_PREFIX=/home/node/.npm-global
+ENV PATH=$PATH:/home/node/.npm-global/bin
+
+# Avoid downloading Chromium again
+ENV PUPPETEER_SKIP_CHROMIUM_DOWNLOAD=true
+ENV PUPPETEER_EXECUTABLE_PATH=/usr/bin/chromium-browser
+
+# Install Pa11y CI and our config into the container
+RUN npm install --global pa11y-ci
+# COPY ./config.json /usr/config.json
+
+ENTRYPOINT ["pa11y-ci", "--config", "/usr/config.json"]

README.md

@@ -342,36 +342,72 @@ module.exports = function (options) {
 
 ### Docker
 
-If you want to run `pa11y-ci` in a Docker container then you can use the [`buildkite/puppeteer`](https://github.com/buildkite/docker-puppeteer) image as this installs Chrome and all the required libs to run headless chrome on Linux.
+We could use [Puppeteer's official Docker image](https://pptr.dev/guides/docker) as the base of a Pa11y CI image. However, this would require the `SYS_ADMIN` capability, which will increase the security surface of the container. We can avoid this by installing Puppeteer and Chromium afresh at the cost of a more complex Dockerfile. This will also reduce the size of the Puppeteer-related layers from over 2GB to ~750MB.
 
-You will need a `config.json` that sets the `--no-sandbox` Chromium launch arguments:
+1. Create a `Dockerfile`. Install `pa11y-ci` within and supply `config.json`.
 
-```json
-{
-    "defaults": {
-        "chromeLaunchConfig": {
-            "args": [
-                "--no-sandbox"
-            ]
-        }
-    },
-    "urls": [
-        "https://pa11y.org/",
-        "https://pa11y.org/contributing"
-    ]
-}
-```
+    ```Dockerfile
+    FROM node:20-alpine
 
-And then a Dockerfile that installs `pa11y-ci` and adds the `config.json`
+    # Install Chromium
+    RUN apk add --no-cache \
+        chromium
 
-```Dockerfile
-FROM buildkite/puppeteer:v1.15.0
+    # Install Chromium's dependencies
+    RUN apk add --no-cache \
+        ca-certificates \
+        freetype \
+        harfbuzz \
+        nss \
+        ttf-freefont
 
-RUN npm install --global --unsafe-perm pa11y-ci
-ADD config.json /usr/config.json
+    # Switch user from 'root' to 'node' (inherited from node:alpine)
+    USER node
 
-ENTRYPOINT ["pa11y-ci", "-c", "/usr/config.json"]
-```
+    # Let's install global dependencies somewhere visitable by user 'node'
+    ENV NPM_CONFIG_PREFIX=/home/node/.npm-global
+    ENV PATH=$PATH:/home/node/.npm-global/bin
+
+    # Avoid downloading Chromium again
+    ENV PUPPETEER_SKIP_CHROMIUM_DOWNLOAD=true
+    ENV PUPPETEER_EXECUTABLE_PATH=/usr/bin/chromium-browser
+
+    # Install Pa11y CI and our config into the container
+    RUN npm install --global pa11y-ci
+    COPY ./config.json /usr/config.json
+
+    ENTRYPOINT ["pa11y-ci", "--config", "/usr/config.json"]
+    ```
+
+1. Create a `./config.json`. Use the `--no-sandbox` argument for Chromium.
+
+    ```json
+    {
+        "defaults": {
+            "chromeLaunchConfig": {
+                "args": [
+                    "--no-sandbox"
+                ]
+            }
+        },
+        "urls": [
+            "https://pa11y.org/",
+            "https://pa11y.org/contributing"
+        ]
+    }
+    ```
+
+1. Build our configured image.
+
+    ```sh
+    docker build -t pa11y-ci-for-some-project .
+    ```
+
+1. Create and run a container from the image.
+
+    ```sh
+    docker run pa11y-ci-for-some-project
+    ```
 
 ## Tutorials and articles