MacOS linting & testing support + docs (docker-mailserver#2001)

.github/workflows/linting.yml

@@ -6,7 +6,6 @@ on:
   push:
     branches:
       - master
-
 jobs:
   lint:
     runs-on: ubuntu-20.04
@@ -17,25 +16,16 @@ jobs:
           submodules: recursive
       - name: Hadolint
         run: |
-          sudo curl -S -L https://github.com/hadolint/hadolint/releases/download/v${HADOLINT_VERSION}/hadolint-$(uname -s)-$(uname -m) -o /usr/local/bin/hadolint
-          sudo chmod +rx /usr/local/bin/hadolint
           make hadolint
         env:
           HADOLINT_VERSION: 2.4.1
       - name: ShellCheck
         run: |
-          sudo curl -S -L "https://github.com/koalaman/shellcheck/releases/download/v${SHELLCHECK_VERSION}/shellcheck-v${SHELLCHECK_VERSION}.linux.x86_64.tar.xz" | tar -xJ
-          sudo mv "shellcheck-v${SHELLCHECK_VERSION}/shellcheck" /usr/bin/
-          sudo rm -rf "shellcheck-v${SHELLCHECK_VERSION}"
           make shellcheck
         env:
           SHELLCHECK_VERSION: 0.7.2
       - name: ECLint
         run: |
-          sudo curl -S -L "https://github.com/editorconfig-checker/editorconfig-checker/releases/download/${ECLINT_VERSION}/ec-linux-amd64.tar.gz" | tar -xaz
-          sudo mv bin/ec-linux-amd64 /usr/bin/eclint
-          sudo rm -rf bin
-          sudo chmod +x /usr/bin/eclint
           make eclint
         env:
           ECLINT_VERSION: 2.3.5

.gitignore

@@ -43,6 +43,9 @@ test/config/without-virtual/
 test/config/with-domain/
 test/onedir
 test/duplicate_configs
+test/alias
+test/quota
+test/relay
 
 config.bak
 testconfig.bak

Makefile

@@ -4,10 +4,6 @@ NAME   ?= mailserver-testing:ci
 VCS_REF = $(shell git rev-parse --short HEAD)
 VCS_VER = $(shell git describe --tags --contains --always)
 
-HADOLINT_VERSION   = 2.4.1
-SHELLCHECK_VERSION = 0.7.2
-ECLINT_VERSION     = 2.3.5
-
 export CDIR = $(shell pwd)
 
 # –––––––––––––––––––––––––––––––––––––––––––––––
@@ -29,7 +25,7 @@ clean:
 # remove running and stopped test containers
 	-@ [[ -d config.bak ]] && { rm -rf config ; mv config.bak config ; } || :
 	-@ [[ -d testconfig.bak ]] && { sudo rm -rf test/config ; mv testconfig.bak test/config ; } || :
-	-@ docker ps -a | grep -E "mail|ldap_for_mail|mail_overri.*" | cut -f 1-1 -d ' ' | xargs --no-run-if-empty docker rm -f
+	-@ for container in $$(docker ps -a | grep -E "mail|ldap_for_mail|mail_overri.*|hadolint|eclint|shellcheck" | cut -f 1-1 -d ' '); do docker rm -f $$container; done
 	-@ sudo rm -rf test/onedir test/alias test/quota test/relay test/config/dovecot-lmtp/userdb test/config/key* test/config/opendkim/keys/domain.tld/ test/config/opendkim/keys/example.com/ test/config/opendkim/keys/localdomain2.com/ test/config/postfix-aliases.cf test/config/postfix-receive-access.cf test/config/postfix-receive-access.cfe test/config/dovecot-quotas.cf test/config/postfix-send-access.cf test/config/postfix-send-access.cfe test/config/relay-hosts/chksum test/config/relay-hosts/postfix-aliases.cf test/config/dhparams.pem test/config/dovecot-lmtp/dh.pem test/config/relay-hosts/dovecot-quotas.cf test/config/user-patches.sh test/alias/config/postfix-virtual.cf test/quota/config/dovecot-quotas.cf test/quota/config/postfix-accounts.cf test/relay/config/postfix-relaymap.cf test/relay/config/postfix-sasl-password.cf test/duplicate_configs/
 
 # –––––––––––––––––––––––––––––––––––––––––––––––
@@ -60,13 +56,3 @@ shellcheck:
 
 eclint:
 	@ ./test/linting/lint.sh eclint
-
-install_linters:
-	@ mkdir -p tools
-	@ curl -S -L \
-		"https://github.com/hadolint/hadolint/releases/download/v$(HADOLINT_VERSION)/hadolint-$(shell uname -s)-$(shell uname -m)" -o tools/hadolint
-	@ curl -S -L \
-		"https://github.com/koalaman/shellcheck/releases/download/v$(SHELLCHECK_VERSION)/shellcheck-v$(SHELLCHECK_VERSION).linux.x86_64.tar.xz" | tar -Jx shellcheck-v$(SHELLCHECK_VERSION)/shellcheck -O > tools/shellcheck
-	@ curl -S -L \
-		"https://github.com/editorconfig-checker/editorconfig-checker/releases/download/$(ECLINT_VERSION)/ec-linux-amd64.tar.gz" | tar -zx bin/ec-linux-amd64 -O > tools/eclint
-	@ chmod u+rx tools/*

docs/content/contributing/issues-and-pull-requests.md

@@ -35,16 +35,16 @@ The development workflow is the following:
    2. Run `git submodule update --init --recursive`
 2. Write the code that is needed :D
 3. Add integration tests if necessary
-4. Get the linters with `make install_linters` and install `jq` with the package manager of your OS
-5. Use `make clean all` to build image locally and run tests (note that tests work on Linux **only**)
-6. Document your improvements if necessary (e.g. if you introduced new environment variables, describe those in the [ENV documentation][docs-environment])
-7. [Commit][commit] and [sign your commit][gpg], push and create a pull-request to merge into `master`. Please **use the pull-request template** to provide a minimum of contextual information and make sure to meet the requirements of the checklist. 
+4. [Prepare your environment and run linting and tests][docs-tests]
+5. Document your improvements if necessary (e.g. if you introduced new environment variables, describe those in the [ENV documentation][docs-environment])
+6. [Commit][commit] and [sign your commit][gpg], push and create a pull-request to merge into `master`. Please **use the pull-request template** to provide a minimum of contextual information and make sure to meet the requirements of the checklist. 
    1. Pull requests are automatically tested against the CI and will be reviewed when tests pass
    2. When your changes are validated, your branch is merged
    3. CI builds the new `:edge` image immediately and your changes will be includes in the next version release.
 
 [docs]: https://docker-mailserver.github.io/docker-mailserver/edge
 [github-file-readme]: https://github.com/docker-mailserver/docker-mailserver/blob/master/README.md
 [docs-environment]: ../config/environment.md
+[docs-tests]: ./tests.md
 [commit]: https://help.github.com/articles/closing-issues-via-commit-messages/
 [gpg]: https://docs.github.com/en/github/authenticating-to-github/generating-a-new-gpg-key

docs/content/contributing/tests.md

@@ -2,5 +2,16 @@
 title: 'Contributing | Tests'
 ---
 
-!!! todo
-    This section should provide a detailed step by step guide on how to write tests
+1. Install docker
+2. Execute `git submodule update --init --recursive`
+3. Install jq
+
+    !!! info "MacOS Specific (needed for tests)"
+
+        ```bash
+        brew install coreutils
+        # bash >= 4.0 for associative arrays
+        brew install bash
+        ```
+
+4. Execute `make clean all`

setup.sh

@@ -36,6 +36,12 @@ ly and use ./setup.sh help and read the VERSION section.\n" >&2
 
 function _get_absolute_script_directory
 {
+  if [[ "$(uname)" == "Darwin" ]]
+  then
+    readlink() {
+      greadlink "${@:+$@}" # Requires coreutils
+    }
+  fi
   if dirname "$(readlink -f "${0}")" &>/dev/null
   then
     DIR="$(dirname "$(readlink -f "${0}")")"
@@ -225,7 +231,7 @@ function _docker_image
   if ${USE_CONTAINER}
   then
     # reuse existing container specified on command line
-    ${CRI} exec "${USE_TTY}" "${CONTAINER_NAME}" "${@}"
+    ${CRI} exec "${USE_TTY}" "${CONTAINER_NAME}" "${@:+$@}"
   else
     # start temporary container with specified image
     if ! _docker_image_exists "${IMAGE_NAME}"
@@ -236,15 +242,15 @@ function _docker_image
 
     ${CRI} run --rm \
       -v "${CONFIG_PATH}:/tmp/docker-mailserver${USE_SELINUX}" \
-      "${USE_TTY}" "${IMAGE_NAME}" "${@}"
+      "${USE_TTY}" "${IMAGE_NAME}" "${@:+$@}"
   fi
 }
 
 function _docker_container
 {
   if [[ -n ${CONTAINER_NAME} ]]
   then
-    ${CRI} exec "${USE_TTY}" "${CONTAINER_NAME}" "${@}"
+    ${CRI} exec "${USE_TTY}" "${CONTAINER_NAME}" "${@:+$@}"
   else
     echo "The mailserver is not running!"
     exit 1
@@ -340,10 +346,10 @@ function _main
 
     email )
       case ${2:-} in
-        add      ) shift 2 ; _docker_image addmailuser "${@}" ;;
-        update   ) shift 2 ; _docker_image updatemailuser "${@}" ;;
-        del      ) shift 2 ; _docker_container delmailuser "${@}" ;;
-        restrict ) shift 2 ; _docker_container restrict-access "${@}" ;;
+        add      ) shift 2 ; _docker_image addmailuser "${@:+$@}" ;;
+        update   ) shift 2 ; _docker_image updatemailuser "${@:+$@}" ;;
+        del      ) shift 2 ; _docker_container delmailuser "${@:+$@}" ;;
+        restrict ) shift 2 ; _docker_container restrict-access "${@:+$@}" ;;
         list     ) _docker_container listmailuser ;;
         *        ) _usage ;;
       esac
@@ -360,32 +366,32 @@ function _main
 
     quota )
       case ${2:-} in
-        set      ) shift 2 ; _docker_image setquota "${@}" ;;
-        del      ) shift 2 ; _docker_image delquota "${@}" ;;
+        set      ) shift 2 ; _docker_image setquota "${@:+$@}" ;;
+        del      ) shift 2 ; _docker_image delquota "${@:+$@}" ;;
         *        ) _usage ;;
       esac
       ;;
 
     config )
       case ${2:-} in
-        dkim     ) shift 2 ; _docker_image open-dkim "${@}" ;;
+        dkim     ) shift 2 ; _docker_image open-dkim "${@:+$@}" ;;
         *        ) _usage ;;
       esac
       ;;
 
     relay )
       case ${2:-} in
-        add-domain     ) shift 2 ; _docker_image addrelayhost "${@}" ;;
-        add-auth       ) shift 2 ; _docker_image addsaslpassword "${@}" ;;
-        exclude-domain ) shift 2 ; _docker_image excluderelaydomain "${@}" ;;
+        add-domain     ) shift 2 ; _docker_image addrelayhost "${@:+$@}" ;;
+        add-auth       ) shift 2 ; _docker_image addsaslpassword "${@:+$@}" ;;
+        exclude-domain ) shift 2 ; _docker_image excluderelaydomain "${@:+$@}" ;;
         *              ) _usage ;;
       esac
       ;;
 
     debug )
       case ${2:-} in
         fetchmail      ) _docker_image debug-fetchmail ;;
-        fail2ban       ) shift 2 ; _docker_container fail2ban "${@}" ;;
+        fail2ban       ) shift 2 ; _docker_container fail2ban "${@:+$@}" ;;
         show-mail-logs ) _docker_container cat /var/log/mail/mail.log ;;
         inspect        ) _inspect ;;
         login          )
@@ -394,7 +400,7 @@ function _main
           then
             _docker_container /bin/bash
           else
-            _docker_container /bin/bash -c "${@}"
+            _docker_container /bin/bash -c "${@:+$@}"
           fi
           ;;
         * ) _usage ; exit 1 ;;
@@ -406,4 +412,4 @@ function _main
   esac
 }
 
-_main "${@}"
+_main "${@:+$@}"

target/scripts/helper-functions.sh

@@ -163,6 +163,7 @@ function _populate_relayhost_map
     if ! grep -q -e "^@${DOMAIN}\b" /etc/postfix/relayhost_map && ! grep -qs -e "^\s*@${DOMAIN}\s*$" /tmp/docker-mailserver/postfix-relaymap.cf
     then
       _notify 'inf' "Adding relay mapping for ${DOMAIN}"
+      # shellcheck disable=SC2153
       echo "@${DOMAIN}    [${RELAY_HOST}]:${RELAY_PORT}" >> /etc/postfix/relayhost_map
     fi
   done

test/linting/.ecrc.json

@@ -1,11 +1,18 @@
 {
-  "Version": "2.3.5",
   "Verbose": false,
   "Debug": false,
   "IgnoreDefaults": false,
   "SpacesAftertabs": true,
   "NoColor": false,
-  "Exclude": [],
+  "Exclude": [
+    "^test/",
+    "\\.git.*",
+    "\\.bats$",
+    "\\.cf$",
+    "\\.conf$",
+    "\\.init$",
+    "\\.md$"
+  ],
   "AllowedContentTypes": [],
   "PassedFiles": [],
   "Disable": {

test/linting/.hadolint.yaml

@@ -2,6 +2,7 @@ ignored:
   - DL3005
   - DL3008
   - DL3015
+  - DL3005
 
 trustedRegistries:
   - docker.io