Workflow documentation

.github/workflows/documentation.yaml

@@ -0,0 +1,111 @@
+on: pull_request
+
+name: Review
+
+env:
+  COMPOSE_USER: runner
+
+jobs:
+  check-github-actions-documentation:
+    runs-on: ubuntu-latest
+    name: Check that Github Actions documentation is up to date
+    steps:
+      - uses: actions/checkout@v4
+      - uses: arduino/setup-task@v2
+        # https://github.com/arduino/setup-task/tree/56d0cc033e3cecc5f07a291fdd39f29388d21800?tab=readme-ov-file#repo-token
+        with:
+          repo-token: ${{ secrets.GITHUB_TOKEN }}
+
+      # https://github.com/mxschmitt/action-tmate?tab=readme-ov-file#manually-triggered-debug
+      # Enable tmate debugging if debug logging is enabled (cf.
+      # https://docs.github.com/en/actions/writing-workflows/choosing-what-your-workflow-does/accessing-contextual-information-about-workflow-runs#runner-context)
+      - name: Setup tmate session
+        uses: mxschmitt/action-tmate@v3
+        if: 1 == runner.debug
+
+      - run: |
+          task github-actions:documentation:update
+
+      # Check that documentation has not changed.
+      - run: |
+          task github-actions:documentation:diff
+
+  check-github-actions-template-headers:
+    runs-on: ubuntu-latest
+    name: Check that Github Actions template headers are up to date
+    steps:
+      - uses: actions/checkout@v4
+      - uses: arduino/setup-task@v2
+        with:
+          repo-token: ${{ secrets.GITHUB_TOKEN }}
+      - run: |
+          task github-actions:template-headers:update --yes
+      # Check that files have not changed.
+      - run: |
+          git diff --exit-code
+
+  check-config-file-headers:
+    runs-on: ubuntu-latest
+    name: Check that config file headers are up to date
+    steps:
+      - uses: actions/checkout@v4
+      - uses: arduino/setup-task@v2
+        with:
+          repo-token: ${{ secrets.GITHUB_TOKEN }}
+      - run: |
+          task github-actions:config-headers:update --yes
+      # Check that files have not changed.
+      - run: |
+          git diff --exit-code
+
+  check-links:
+    runs-on: ubuntu-latest
+    name: Check that workflow and config file links are up to date
+    steps:
+      - uses: actions/checkout@v4
+      - uses: arduino/setup-task@v2
+        with:
+          repo-token: ${{ secrets.GITHUB_TOKEN }}
+
+      # https://github.com/mxschmitt/action-tmate?tab=readme-ov-file#manually-triggered-debug
+      # Enable tmate debugging if debug logging is enabled (cf.
+      # https://docs.github.com/en/actions/writing-workflows/choosing-what-your-workflow-does/accessing-contextual-information-about-workflow-runs#runner-context)
+      - name: Setup tmate session
+        uses: mxschmitt/action-tmate@v3
+        if: 1 == runner.debug
+
+      - run: |
+          task github-actions:link --yes
+      # Check that files have not changed.
+      - run: |
+          git diff --exit-code
+
+  lint-markdown:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: arduino/setup-task@v2
+        with:
+          repo-token: ${{ secrets.GITHUB_TOKEN }}
+      - run: |
+          SKIP_FIX=1 task lint:markdown
+
+  lint-shell-script:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: arduino/setup-task@v2
+        with:
+          repo-token: ${{ secrets.GITHUB_TOKEN }}
+      - run: |
+          SKIP_FIX=1 task lint:shell-script
+
+  lint-yaml:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: arduino/setup-task@v2
+        with:
+          repo-token: ${{ secrets.GITHUB_TOKEN }}
+      - run: |
+          SKIP_FIX=1 task lint:yaml

.github/workflows/markdown.yaml

@@ -0,0 +1,43 @@
+# Do not edit this file! Make a pull request on changing
+# github/workflows/markdown.yaml in
+# https://github.com/itk-dev/devops_itkdev-docker if need be.
+
+### ### Markdown
+###
+### Lints Markdown files (`**/*.md`) in the project.
+###
+### [markdownlint-cli configuration
+### files](https://github.com/igorshubovych/markdownlint-cli?tab=readme-ov-file#configuration),
+### `.markdownlint.jsonc` and `.markdownlintignore`, control what is actually
+### linted and how.
+###
+### #### Assumptions
+###
+### 1. A docker compose service named `markdownlint` for running `markdownlint`
+###    (from
+###    [markdownlint-cli](https://github.com/igorshubovych/markdownlint-cli))
+###    exists.
+
+name: Markdown
+
+on:
+  pull_request:
+  push:
+    branches:
+      - main
+      - develop
+
+jobs:
+  markdown-lint:
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - run: |
+          docker network create frontend
+
+      - run: |
+          docker compose run --rm markdownlint markdownlint '**/*.md'

.github/workflows/workflow-template.yaml

@@ -0,0 +1,26 @@
+on: pull_request
+
+name: Workflow templates
+
+jobs:
+  check-yaml:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - run: |
+          docker pull mikefarah/yq
+          for f in $(find github/workflows/ -name '*.yaml'); do
+            docker run --rm --volume "$PWD":/workdir mikefarah/yq "$f" > /dev/null
+          done
+
+  shellcheck:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: arduino/setup-task@v2
+        with:
+          repo-token: ${{ secrets.GITHUB_TOKEN }}
+
+      - run: |
+          task lint:shell-script

.gitignore

@@ -0,0 +1 @@
+.task

.markdownlint.jsonc

@@ -0,0 +1,19 @@
+// markdownlint-cli configuration file (cf. https://github.com/igorshubovych/markdownlint-cli?tab=readme-ov-file#configuration)
+{
+  "default": true,
+  // https://github.com/DavidAnson/markdownlint/blob/main/doc/md013.md
+  "line-length": {
+    "line_length": 120,
+    "code_blocks": false,
+    "tables": false
+  },
+  // https://github.com/DavidAnson/markdownlint/blob/main/doc/md024.md
+  "no-duplicate-heading": {
+    "siblings_only": true
+  },
+  // https://docs.github.com/en/get-started/writing-on-github/working-with-advanced-formatting/organizing-information-with-collapsed-sections#creating-a-collapsed-section
+  // https://github.com/DavidAnson/markdownlint/blob/main/doc/md033.md
+  "no-inline-html": {
+    "allowed_elements": ["details", "summary"]
+  }
+}

.markdownlintignore

@@ -0,0 +1,8 @@
+# https://github.com/igorshubovych/markdownlint-cli?tab=readme-ov-file#ignoring-files
+vendor/
+node_modules/
+LICENSE.md
+# Drupal
+web/*.md
+web/core/
+web/*/contrib/

README.md

@@ -39,21 +39,28 @@ __Note__: You have to follow the instructions brew writes to get it working (use
 If you use the [Dory](https://github.com/FreedomBen/dory) revers proxy required to
 run DDF CMS unmodified you need to install dory. We only use dory for DPL/DDF shared
 projects (multi supplier projects).
+
 ```sh
 brew install dory
 ```
 
 ### Templates
 
 The [`templates`](templates/) directory contains templates for adding
-the itkdev `docker-compose` setup to new or exiting projects.
+the itkdev `docker compose` setup to new or exiting projects.
+
+Run
 
 ```sh
-rsync -avz templates/<TYPE>/ <PATH TO HTDOCS FOLDER>
+itkdev-docker-compose template:install --list
 ```
 
-Also create an `.env` file beside the `docker-compose.yml` file that contains
-`COMPOSE_PROJECT_NAME=<NAME>` to namespace the docker setup for the projekt.
+to see a list of all templates.
+
+Run `itkdev-docker-compose template:install drupal-10`, say, to install or update a template in a project.
+
+In addition to the docker compose setup for our projects, installing a template will also add GitHib Actions workflow
+files to a project; see [Github Actions templates](docs/github-actions-templates.md) for details.
 
 ### Docker commands
 
@@ -112,13 +119,15 @@ LOCAL_PATH='sites/default/files'
 
 ## SSL certification support
 
-This setup comes with self-signed wildcard certificates for *.local.itkdev.dk, but other certificates can be generated by using this openssl command on Mac, just change the two places where the domain is written.
+This setup comes with self-signed wildcard certificates for *.local.itkdev.dk, but other certificates can be generated
+by using this openssl command on Mac, just change the two places where the domain is written.
 
 ```sh
 openssl req -x509 -sha256 -nodes -days 3650 -newkey rsa:2048 -keyout docker.key -out docker.crt -subj "/CN=*.local.itkdev.dk" -reqexts SAN -extensions SAN -config <(cat /usr/local/etc/openssl/openssl.cnf <(printf '[SAN]\nsubjectAltName=DNS:*.local.itkdev.dk'))
 ```
 
-To mac browser trust this certificate you need to open it with key-chain right click and select "Get info" and then open the "Trust" tab and select "Always trust".
+To mac browser trust this certificate you need to open it with key-chain right click and select "Get info" and then open
+the "Trust" tab and select "Always trust".
 
 The certificate is located in `./treafik/ssl/docker.crt` in this repository.
 
@@ -158,17 +167,19 @@ The fuld list can be found at
 [https://hub.docker.com/search?q=itkdev&type=image](https://hub.docker.com/search?q=itkdev&type=image).
 
 ## More
-For more details about usage see https://docs.itkdev.dk
+
+For more details about usage see <https://docs.itkdev.dk>
 
 ## Previous versions
 
 ### NFS mounts removed
 
 From version 3.0.0 the feature to use NFS mounted name-volumes has been removed
-because it is no longer compatible with MacOS. (@see https://github.com/docker/for-mac/issues/6544)
+because it is no longer compatible with MacOS. (@see <https://github.com/docker/for-mac/issues/6544>)
 
 If you have previously enabled NFS with `nfs:enable` you should clean up as
 follows:
+
 ```shell
 sudo nano /etc/exports
 # Delete the line matching this pattern, and save you changes

Taskfile.yml

@@ -0,0 +1,69 @@
+# https://taskfile.dev
+
+version: '3'
+
+includes:
+  github-actions: ./task/Taskfile.github-actions.yml
+
+vars:
+  GITHUB_ACTIONS_TEMPLATES_HEADER: |
+    # Github Actions templates
+
+    This repository contains a number of [GitHub
+    Actions](https://docs.github.com/en/actions) workflow template files that
+    are copied to a project when running `itkdev-docker-compose
+    template:install`. Any changes to the workflows should be made in [this
+    repository](%THIS_REPOSITORY%) and then the project template must be updated
+    to match the new templates.
+
+  GITHUB_ACTIONS_TEMPLATES_FOOTER: |
+
+tasks:
+  build:
+    desc: "Build everything"
+    cmds:
+      - task: github-actions:template-headers:update
+      - task: github-actions:documentation:update
+      - task: github-actions:link
+      - task: lint:markdown
+      - task: lint:yaml
+
+  lint:markdown:
+    desc: "Lint Markdown"
+    cmds:
+      - '[[ -n "$SKIP_FIX" ]] || {{.MARKDOWNLINT_COMMAND}} --fix'
+      - '{{.MARKDOWNLINT_COMMAND}}'
+    vars:
+      # We use a block scalar (https://yaml-multiline.info/#block-scalars) here to make escaping (a little) easier.
+      GLOB: >-
+        {{.CLI_ARGS | default "'**/*.md'"}}
+      # I don't (yet) know why, but `itkdev/markdownlint` has an issue with
+      # permissions when running in GitHub Actions. Therefore we use
+      # `peterdavehello/markdownlint`
+      # (https://hub.docker.com/r/peterdavehello/markdownlint)
+      MARKDOWNLINT_COMMAND: >-
+        docker run --rm --volume "$PWD":/md peterdavehello/markdownlint markdownlint --dot {{.GLOB}}
+
+  lint:shell-script:
+    desc: "Lint shell scripts"
+    cmds:
+      # https://github.com/koalaman/shellcheck?tab=readme-ov-file#installing
+      - docker run --rm --volume "$PWD:"/mnt koalaman/shellcheck:stable {{.GLOB}}
+    vars:
+      # We use a block scalar (https://yaml-multiline.info/#block-scalars) here to make escaping (a little) easier.
+      GLOB: >-
+        {{.CLI_ARGS | default "task/scripts/*"}}
+
+  lint:yaml:
+    desc: "Lint YAML"
+    cmds:
+      - |
+        # docker pull mikefarah/yq
+        for f in $(find github/workflows/ -name '*.yaml'); do
+          docker run --rm --volume "$PWD":/workdir mikefarah/yq "$f" > /dev/null
+        done
+
+  default:
+    cmds:
+      - task --list
+    silent: true

compose.yaml

@@ -0,0 +1,16 @@
+services:
+  markdownlint:
+    image: itkdev/markdownlint
+    profiles:
+      - dev
+    volumes:
+      - ./:/md
+
+  jinja2-cli:
+    # https://hub.docker.com/r/roquie/docker-jinja2-cli
+    # Is https://hub.docker.com/r/stagex/user-py-jinja2 a better choice?
+    image: roquie/docker-jinja2-cli
+    profiles:
+      - dev
+    volumes:
+      - ./:/app