Push docker compose as default way to run cwac

README.md

@@ -9,6 +9,7 @@
     - [Core technologies](#core-technologies)
     - [Linting source code](#linting-source-code)
     - [Audit plugin architecture](#audit-plugin-architecture)
+    - [Crawling sitemaps](#crawling-sitemaps)
   - [Updating Chrome and Chromedriver versions](#updating-chrome-and-chromedriver-versions)
   - [Copyright notices](#copyright-notices)
     - [Copyright of Centralised Web Accessibility Checker (CWAC)](#copyright-of-centralised-web-accessibility-checker-cwac)
@@ -51,14 +52,16 @@ performance, or the existence of a privacy or copyright statement.
 
 ## Using CWAC
 
-- [Installing CWAC](./doc/install.md)
 - [Understanding audits](./doc/audits.md)
 - [Configuring audits](./doc/audit-config.md)
 - [Running CWAC CLI](./doc/run-cwac.md)
 - [Working with audit results](./doc/audit-results.md)
 
 ## Developing CWAC
 
+Get started by reading the
+[local dev environment setup guide](./doc/local-dev-setup.md)
+
 ### Core technologies
 
 CWAC combines the following technologies:

compose.yaml

@@ -0,0 +1,23 @@
+services:
+  cwac:
+    build:
+      context: .
+      dockerfile: Dockerfile
+    command:
+      [
+        '.venv/bin/python',
+        '-u',
+        'cwac.py',
+        '${CWAC_CONFIG:-config_default.json}'
+      ]
+    # network_mode: host
+    volumes:
+      - type: bind
+        source: ./config
+        target: /cwac/config
+      - type: bind
+        source: ./base_urls
+        target: /cwac/base_urls
+      - type: bind
+        source: ./results
+        target: /cwac/results

doc/install.md → doc/local-dev-setup.md

@@ -1,4 +1,4 @@
-# Installing CWAC
+# Local dev setup
 
 ## Step 1: Ensure appropriate Python and NodeJS are installed
 

doc/run-cwac.md

@@ -1,24 +1,38 @@
 # Running CWAC
 
-1. Ensure you have completed the setup instructions in
-   [Installing CWAC](./install.md).
-2. Review [Configuring CWAC](./audit-config.md) to create your desired scan
-   configuration (or just use the defaults).
+We recommend running CWAC in docker.
 
-Once the configuration files are set up, CWAC can be run by executing:
+It is technically possible to run CWAC on other platforms but we do not
+recommend it because there are annoying edge-cases. For example, as of this
+writing, the latest Chrome for Testing (151.0.7922.71) has a hard-coded minimum
+screen width of 500 px. This means that the
+[Reflow audit](./audits/reflow-audit.md) cannot run.
+
+The instructions below focus on first-time users. If you are already familiar
+with docker then you'll probably want to skip to our
+[Docker compose file](../compose.yml).
+
+First install [Docker Desktop](https://www.docker.com/products/docker-desktop/).
+Now you should have the `docker` command available in your shell.
 
 ```bash
-# You need to have the Python venv set up in your shell. If you have not already
-# done this then run
-source .venv/bin/activate
+docker --version
+
+# clone this project
+git clone https://github.com/GOVTNZ/cwac.git
+
+# change dir to root of this project
+cd path/to/cwac
+
+Review [Configuring CWAC](./audit-config.md) to create your desired scan
+configuration (or just use the defaults).
 
-# uses ./config/config_default.json as its configuration source.
-python cwac.py
+# Build and run the container using default options.
+# Use default config (./config/config_default.json)
+docker compose up
 
-# To specify a config file for CWAC:
-# This will cause CWAC to load `./config/config_custom.json` instead of
-# `config_default.json`.
-python cwac.py config_custom.json
+# use a specific config (./config/config_my_custom_config.json)
+CWAC_CONFIG=config_my_custom_config.json docker compose up
 ```
 
 > [!WARNING]