This is an automated email from the ASF dual-hosted git repository.
zregvart pushed a commit to branch main
in repository https://gitbox.apache.org/repos/asf/camel-website.git
The following commit(s) were added to refs/heads/main by this push:
new f6bdf22 chore: document redirect tests and docker-pipe
f6bdf22 is described below
commit f6bdf22577e68f2bebea48ce6c22ce25b9fbd368
Author: Zoran Regvart <[email protected]>
AuthorDate: Thu Dec 9 10:30:07 2021 +0100
chore: document redirect tests and docker-pipe
Adds documentation for the recent changes in the redirect tests and the
supporting docker-pipe tool.
---
support/README.md | 46 ++++++++++++++++++++++++++++++++++++++++++++--
tests/redirect.sh | 41 ++++++++++++++++++++++++++++++++++++++++-
2 files changed, 84 insertions(+), 3 deletions(-)
diff --git a/support/README.md b/support/README.md
index a6e6aac..c4cccb4 100644
--- a/support/README.md
+++ b/support/README.md
@@ -10,7 +10,7 @@ update. Our preview environment is hosted on the build server
(Jenkins)
and for the local preview Hugo is acting as a web server. So with that
there is no way to test changes to `static/.htaccess` file before it is
applied to the production website. For this we have a `httpd.conf` file
-here that mimicks the production environment locally. In conjuction with
+here that mimics the production environment locally. In conjunction with
running HTTP server in a Linux container it can be used to test changes
to `static/.htaccess`.
@@ -21,6 +21,48 @@ website (`yarn build`):
$ docker run --rm -p 80:80 -p 443:443 \
-v "$PWD/public":/usr/local/apache2/htdocs/:Z \
-v "$PWD/support/http":/support:Z \
- httpd:2.4 /bin/bash -c "cp /support/* /usr/local/apache2/conf/ &&
httpd-foreground"
+ httpd:2.4 /bin/bash -c "cp /support/* /usr/local/apache2/conf/ &&
httpd-foreground"
```
+# Docker/Podman pipe
+
+When running the build within a container for some checks we might need
+to run more containers. For example the `tests/redirect.sh` script when
+run with `-s` will start Apache HTTP in a container. A common solution
+to that is a "Docker in Docker", i.e. mounting `/var/run/docker.socket`
+and `/usr/bin/docker` in the container. This has two drawbacks, one is
+that the libc version of the build container might not be compatible
+with the libc version of the `docker` CLI installed on host, now mounted
+within the build container; and another is that when running with
+additional restrictions, e.g. user-mapping or SELinux, accessing
+`/var/run/docker.socket` from the build container's namespace could lead
+to permission errors.
+
+To circumvent that the `docker-pipe.sh` script creates several named
+FIFO special files (see mkfifo(1)) that can be mounted to the build
+container, along with the `docker` stub script that uses those named
+pipes to communicate with the `docker-pipe.sh` running on the host.
+
+Typical usage scenario is something like:
+
+```shell
+$ support/docker-pipe.sh tmp &
+$ docker run -v "$PWD/tmp":"$PWD/tmp" \
+ -v "$PWD/tmp/docker":/usr/bin/docker" \
+ ...
+root@62ace315af17:...# docker run ...
+root@62ace315af17:...# exit
+$ tmp/teardown.sh
+```
+
+Some notes on the usage: the argument provided to `docker-pipe.sh` is a
+directory where named pipes `docker` stub script and `teardown.sh`
+scripts will be placed. This directory must be mounted to the same path
+within the container, as in the above example. One can use `docker` stub
+script from that directory or, as in the above example, mount it to
+`/usr/bin/docker` so it's immediately available on `$PATH`.
+`docker-pipe.sh` should be run in the background, and to terminate it
+use `teardown.sh`, one could use job control commands as well, but that
+might be a bit more involved in CI environments (hence `teardown.sh`).
+Upon exiting `docker-pipe.sh` will delete the files it created from the
+provided directory.
diff --git a/tests/redirect.sh b/tests/redirect.sh
index dec8c7b..96e53f0 100755
--- a/tests/redirect.sh
+++ b/tests/redirect.sh
@@ -1,4 +1,32 @@
#!/bin/bash
+#
+# Tests configured redirects by running `curl` against the provided URL
+# and comparing the expected result with the actual result.
+#
+# Test syntax (see tests below for examples):
+#
+# test "$BASE_URL/<relative url>" <expected status> ["$BASE_URL/<expected
value in Location header>
+#
+# By default, when run without any arguments, script tests against
+# `https://localhost` as `$BASE_URL`, this is convenient when running
+# with Apache HTTP (see ../support directory on how to do that).
+#
+# An URL can be provided to test against a different `$BASE_URL`, e.g.
+#
+# $ test/redirect.sh https://camel.apache.org
+#
+# With `-s`/`--serve` parameter a container will be spun with the Apache
+# HTTP, serving the content from the `public` directory (generated by
+# the build). For this `podman` or `docker` installation is required.
+#
+# By default output for only failing tests and the summary is printed,
+# for more verbose output run with `-v`/`--verbose`. For debug output
+# run with `-x`/`--debug` parameter
+#
+# Some redirects are generated dynamically, for example those generated
+# by Antora for the _latest_ version, so they're grepped from the
+# `.htaccess` file generated in `documentation` directory to ease the
+# maintenance. See `*_VERSION` variables below.
set -eu -o pipefail
@@ -14,7 +42,7 @@ while [[ $# -gt 0 ]]; do
VERBOSE=1
shift
;;
- -x|--very-verbose)
+ -x|--debug)
set -x
DEBUG=1
shift
@@ -32,6 +60,7 @@ done
GIT_ROOT=$(realpath "$(dirname "${BASH_SOURCE[0]}")/..")
+# run Apache HTTP in a container with the content from `public`
if [ "$SERVE" == 1 ]; then
CONTAINER_CMD=podman
if ! command -v $CONTAINER_CMD &> /dev/null; then
@@ -58,6 +87,10 @@ fi
TOTAL=0
SUCCESS=0
+# runs `curl` and records the `Status` and `Location` (if provided)
+# header values and compares it with expected values provided as
+# parameters.
+# Usage: test <url> <expected status> [expected location]
function test {
local url=$1
local code=$2
@@ -79,12 +112,17 @@ function test {
fi
}
+# determine current _latest_ versions
COMPONENTS_VERSION="$(grep 'components/latest'
"$GIT_ROOT/documentation/.htaccess" | grep -Z -o '[^/]*$')"
CAMEL_K_VERSION="$(grep 'camel-k/latest' "$GIT_ROOT/documentation/.htaccess" |
grep -Z -o '[^/]*$')"
CAMEL_KAFKA_CONNECTOR_VERSION="$(grep 'camel-kafka-connector/latest'
"$GIT_ROOT/documentation/.htaccess" | grep -Z -o '[^/]*$')"
CAMEL_QUARKUS_VERSION="$(grep 'camel-quarkus/latest'
"$GIT_ROOT/documentation/.htaccess" | grep -Z -o '[^/]*$')"
CAMEL_KAMELETS_VERSION="$(grep 'camel-kamelets/latest'
"$GIT_ROOT/documentation/.htaccess" | grep -Z -o '[^/]*$')"
+#
+# TESTS
+#
+
test "$BASE_URL/components" 302 "$BASE_URL/components/${COMPONENTS_VERSION}/"
test "$BASE_URL/components/" 302 "$BASE_URL/components/${COMPONENTS_VERSION}/"
test "$BASE_URL/components/next" 301 "$BASE_URL/components/next/"
@@ -169,6 +207,7 @@ test "$BASE_URL/manual/latest/component-dsl.html" 302
"$BASE_URL/manual/componen
test "$BASE_URL/manual/" 200
test "$BASE_URL/manual/component-dsl.html" 200
+# prints summary
if [ "$TOTAL" == "$SUCCESS" ]; then
echo -e "$0 \e[1mSUCCESSFULLY\e[0m ran $TOTAL tests"
else
