diff --git a/README.md b/README.md index 9793c8b..021e866 100644 --- a/README.md +++ b/README.md @@ -7,6 +7,10 @@ This Docker image provides the use of [pa11y v5](https://github.com/pa11y/pa11y). (Note that the v5 version of that project is currently not in the master branch.) +As of version 2, a variant (with tags suffixed `-ci`) ships with the [pa11y-ci](https://github.com/pa11y/pa11y-ci) tool. + +Version 2 of outrigger/pa11y Docker image provides stable versions of pa11y v5 and pa11y-ci v2. + ## Usage Examples ### Docker Run @@ -16,7 +20,7 @@ given URL. ``` docker run -i --rm --cap-add=SYS_ADMIN \ - --name pa11y outrigger/pa11y:1 http://outrigger.sh + --name pa11y outrigger/pa11y:2 http://outrigger.sh ``` ### Docker-Compose - Simple @@ -27,14 +31,16 @@ This is the docker-compose style to execute the same docker run command as above version: '3.3' services: pa11y: - image: outrigger/pa11y:1 - container_name: projectname_${DOCKER_ENV:-local}_pa11y + image: outrigger/pa11y:2 command: http://outrigger.sh network_mode: bridge cap_add: - SYS_ADMIN ``` +This configuration can be used via `docker-compose run --rm pa11y`. + + ### Docker-Compose - Project This is an example service definition to run pa11y as part of your project. @@ -80,6 +86,80 @@ pa11y('http://outrigger.sh', { browser.close(); ``` +### pa11y-ci + +This is a variant of pa11y that allows JSON or JS configuration of URLs to be +scanned. It will aggregate the results as well, allowing a CI process to process +an entire website. + +#### Docker Run + +You can use docker run to trigger your pa11y-ci execution in the same manner +pa11y operates. However, you will need to position a pa11y-ci configuration file +in the container. + +To start, you might copy pa11yci.example.json to your local directory, and run +the command like so: + +``` +docker run -i --rm --cap-add=SYS_ADMIN \ + -v $PWD/pa11yci.example.json:/app/.pa11yci + --name pa11y-ci outrigger/pa11y:2-ci "--json" +``` + +You may notice the use of the --json flag: this instructs pa11y-ci to output +the test results in a machine-parseable JSON format. It is not built into the +Docker image to allow the full range of pa11y-ci options to be explored. + +#### Docker Compose - Simple + +This is the docker-compose style to execute the same docker run command as above. + +```yaml +version: '3.3' +services: + pa11y: + image: outrigger/pa11y:2-ci + command: "--json" + volumes: + - ./pa11yci.example.json:/app/.pa11yci + network_mode: bridge + cap_add: + - SYS_ADMIN +``` + +This configuration can be used via `docker-compose run --rm pa11y-ci`. + +#### Capture the Report + +To capture the pa11y-ci report (such as for further rendering into a dashboard), +you can pipe the output of your execution into a file: + +``` +docker-compose run --rm pa11y-ci > report.json +``` + +If you want the command to be "all-in-one", you can also make further changes +to build the file output into your docker-compose configuration and use bind +mounts to export the file to the host machine: + +```yaml +version: '3.3' +services: + pa11y: + image: outrigger/pa11y:2-ci + # Override the entrypoint so we can wrap the pa11y-ci command in a subshell. + entrypoint: ["dumb-init", "--"] + # Reroute the output report to a file as part of executing the command. + command: "bash -c 'pa11y-ci --json > /app/reports/report.json'" + volumes: + - ./pa11yci.example.json:/app/.pa11yci + - ./reports:/app/reports + network_mode: bridge + cap_add: + - SYS_ADMIN +``` + ### Screenshot Example This is an example of reaching around pa11y to the underlying screenshot tools diff --git a/build.sh b/build.sh index 1c73be0..99da7c5 100755 --- a/build.sh +++ b/build.sh @@ -1,3 +1,4 @@ #!/bin/sh -docker build -t outrigger/pa11y . +docker build -t outrigger/pa11y ./pa11y +docker build -t outrigger/pa11y:ci ./pa11y-ci diff --git a/pa11y-ci/Dockerfile b/pa11y-ci/Dockerfile new file mode 100644 index 0000000..c1d1772 --- /dev/null +++ b/pa11y-ci/Dockerfile @@ -0,0 +1,23 @@ +FROM alekzonder/puppeteer:1 + +# @see http://label-schema.org/rc1/ +LABEL maintainer="Phase2 " \ + org.label-schema.vendor="Phase2 " \ + org.label-schema.name="Outrigger pa11y" \ + org.label-schema.description="Docker image for pa11y-ci, the CLI-based accessibility testing tool." \ + org.label-schema.vcs-url="https://github.com/phase2/docker-pa11y" + +USER root + +# Let's get pa11y-ci v2 in here. +RUN yarn global add pa11y-ci@2 && \ + yarn cache clean && \ + chown -R pptruser:pptruser /usr/local/share/.config/yarn/global/node_modules + +ENV PATH "/usr/local/share/.config/yarn/global/node_modules/.bin/:${PATH}" + +USER pptruser + +ENTRYPOINT ["dumb-init", "--", "pa11y-ci"] + +CMD ["-h"] diff --git a/Dockerfile b/pa11y/Dockerfile similarity index 73% rename from Dockerfile rename to pa11y/Dockerfile index e6dfc75..077e692 100644 --- a/Dockerfile +++ b/pa11y/Dockerfile @@ -14,8 +14,14 @@ LABEL maintainer="Phase2 " \ USER root # Let's get pa11y v5 in here. -RUN yarn global add pa11y@5 pa11y-ci@2 +RUN yarn global add pa11y@5 && \ + yarn cache clean && \ + chown -R pptruser:pptruser /usr/local/share/.config/yarn/global/node_modules + +ENV PATH "/usr/local/share/.config/yarn/global/node_modules/.bin/:${PATH}" USER pptruser -ENTRYPOINT ["dumb-init", "--"] +ENTRYPOINT ["dumb-init", "--", "pa11y"] + +CMD ["-h"] diff --git a/pa11yci.example.json b/pa11yci.example.json new file mode 100644 index 0000000..95b01d4 --- /dev/null +++ b/pa11yci.example.json @@ -0,0 +1,5 @@ +{ + "urls": [ + "http://outrigger.sh/" + ] +}