From e2cea22ba909dfcaaab97c8e5ff75f2cac07ea60 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Jan=20H=C3=B8ydahl?= Date: Wed, 26 Jun 2024 12:50:05 +0200 Subject: [PATCH 1/7] Improve build script --- README.md | 6 ++--- build.sh | 80 +++++++++++++++++++++++++++++++++++++++++-------------- 2 files changed, 63 insertions(+), 23 deletions(-) diff --git a/README.md b/README.md index 6eb40193f..1af5fc977 100644 --- a/README.md +++ b/README.md @@ -15,9 +15,9 @@ If the staged site looks good, simply merge the changes to branch `production` a For larger edits it is recommended to build and preview the site locally. This lets you see the result of your changes instantly without committing anything. The bundled script uses a pelican docker image to build and serve the site locally. Please make sure you have docker installed. - # Usage: ./build.sh [-l] [] + # Usage: ./build.sh [-l] [-b] [] # -l Live build and reload source changes on localhost:8000 - # --help Show full help for options that Pelican accepts + # -b Re-build local docker image, re-installing packages from requirements.txt ./build.sh -l Now go to to view the beautiful Solr web page served from your laptop with live-preview of updates :) @@ -28,7 +28,7 @@ If you want to build the site without the docker image, you can install Python 3 On Windows, you can use the Windows Subsystem for Linux (WSL) to run the build script. Or you can run the docker command directly in a Terminal: - docker run --rm -w /work -p 8000:8000 -v $(pwd):/work qwe1/docker-pelican:4.8.0 pip3 install -r requirements.txt; pelican content -r -l -b 0.0.0.0 + docker run --rm -ti -w /work -p 8000:8000 -v $(pwd):/work qwe1/docker-pelican:4.8.0 sh -c "pip3 install -r requirements.txt; pelican content -r -l -b 0.0.0.0" ## Updating site during a Solr release diff --git a/build.sh b/build.sh index 0fa36a532..984b5dd04 100755 --- a/build.sh +++ b/build.sh @@ -14,20 +14,43 @@ # See the License for the specific language governing permissions and # limitations under the License. +# Fail on error +set -e +#set -x + # Using https://hub.docker.com/r/qwe1/docker-pelican as pelican image, supports both AMD64 and ARM64 PELICAN_IMAGE="qwe1/docker-pelican:4.8.0" -DOCKER_CMD="docker run --rm -w /work -p 8000:8000 -v $(pwd):/work $PELICAN_IMAGE" +SOLR_PELICAN_IMAGE="solr-pelican-image" +DOCKER_CMD="docker run --rm -ti -w /work -p 8000:8000 -v $(pwd):/work $SOLR_PELICAN_IMAGE" unset SERVE PIP_CMD="pip3 install -r requirements.txt" PELICAN_CMD="pelican content -o output" +PELICAN_OPTS="" export SITEURL="https://solr.apache.org/" function usage { - echo "Usage: ./build.sh [-l] []" + echo "Usage: ./build.sh [-l] [-b] []" echo " -l Live build and reload source changes on localhost:8000" + echo " -b Re-build local docker image, re-installing packages from requirements.txt" echo " --help Show full help for options that Pelican accepts" } +function build_image { + echo "Building local Docker image for Pelican, called $SOLR_PELICAN_IMAGE." + # Make a new local image with the pip packages installed + docker rm -f solr-pelican >/dev/null 2>&1 || true + docker run --name solr-pelican -w /work -v $(pwd):/work $PELICAN_IMAGE sh -c "$PIP_CMD" + docker commit solr-pelican $SOLR_PELICAN_IMAGE + docker rm -f solr-pelican >/dev/null 2>&1 || true +} + +function ensure_image { + if ! docker inspect $SOLR_PELICAN_IMAGE >/dev/null 2>&1 + then + build_image + fi +} + if ! docker -v >/dev/null 2>&1 then echo "ERROR: This script requires docker." @@ -37,29 +60,46 @@ then exit 2 fi -if [[ ! -z $1 ]]; then - if [[ "$1" == "-l" ]]; then - SERVE=true - shift - else - usage - if [[ "$1" == "-h" ]]; then - exit 0 - elif [[ "$1" == "--help" ]]; then - echo - echo "Below is a list of other arguments you can use which will be passed to pelican." - echo - $DOCKER_CMD pelican -h +while getopts ":lbh-:" opt; do + case ${opt} in + l ) + SERVE=true + ;; + b ) + build_image + ;; + h ) + usage exit 0 - fi - fi -fi + ;; + - ) + case "${OPTARG}" in + help ) + echo + echo "Below is a list of other arguments you can use which will be passed to pelican." + echo + $DOCKER_CMD pelican -h + exit 0 + ;; + * ) + PELICAN_OPTS+="--${OPTARG} " + ;; + esac + ;; + \? ) + PELICAN_OPTS+="-${OPTARG} " + ;; + esac +done +shift $((OPTIND -1)) + +ensure_image if [[ $SERVE ]]; then echo "Building Solr site locally. Goto http://localhost:8000 to view." echo "Edits you do to the source tree will be compiled immediately!" - $DOCKER_CMD $PIP_CMD; $PELICAN_CMD --autoreload --listen -b 0.0.0.0 $@ + $DOCKER_CMD sh -c "$PELICAN_CMD --autoreload --listen -b 0.0.0.0 $PELICAN_OPTS $*" else echo "Building Solr site." echo "To build and serve live edits locally, run this script with -l argument. Use -h for help." - $DOCKER_CMD $PIP_CMD; $PELICAN_CMD $@ + $DOCKER_CMD sh -c "$PELICAN_CMD $PELICAN_OPTS $*" fi From 218fc25280e85f734bdbd17ff40f18f696c720cb Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Jan=20H=C3=B8ydahl?= Date: Wed, 26 Jun 2024 13:00:16 +0200 Subject: [PATCH 2/7] Print output about -b option --- build.sh | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/build.sh b/build.sh index 984b5dd04..e84945ff5 100755 --- a/build.sh +++ b/build.sh @@ -97,9 +97,11 @@ ensure_image if [[ $SERVE ]]; then echo "Building Solr site locally. Goto http://localhost:8000 to view." echo "Edits you do to the source tree will be compiled immediately!" + echo "Changes to requirements.txt will require using -b option to rebuild the image." $DOCKER_CMD sh -c "$PELICAN_CMD --autoreload --listen -b 0.0.0.0 $PELICAN_OPTS $*" else - echo "Building Solr site." + echo "Building Solr site locally." echo "To build and serve live edits locally, run this script with -l argument. Use -h for help." + echo "Changes to requirements.txt will require using -b option to rebuild the image." $DOCKER_CMD sh -c "$PELICAN_CMD $PELICAN_OPTS $*" fi From 71d9b107135cb6aeca20b268c250f17f988e9e8a Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Jan=20H=C3=B8ydahl?= Date: Wed, 26 Jun 2024 13:11:48 +0200 Subject: [PATCH 3/7] Fixup manual-install.md --- manual-install.md | 16 ++++++++-------- 1 file changed, 8 insertions(+), 8 deletions(-) diff --git a/manual-install.md b/manual-install.md index 122afd6df..d18d812e8 100644 --- a/manual-install.md +++ b/manual-install.md @@ -1,12 +1,13 @@ # Installing Pelican by hand -The site uses [Pelican][1] for static html generation. Pelican requires [Python 3.5+][4] and can be installed with pip. +The site uses [Pelican][1] for static html generation. Pelican requires [Python 3.5+][2] and can be installed with pip. -**The `build.sh` script mentioned in REAME is the easiest way of building the site**, and you can skip this part unless you want to understand the moving parts and install things by hand. +**The `build.sh` script mentioned in README is the easiest way of building the site using Docker**. +If for some reason you want to install Python and Pelican by hand, here are the steps: ## Install Python 3 -First, you need to install Python 3. You can download the latest version from the [Python website][4] or +First, you need to install Python 3. You can download the latest version from the [Python website][2] or use your package manager to install it. For example, on macOS: ```shell @@ -21,7 +22,7 @@ To install pelican and requirements, simply run the following command in the roo pip3 install -r requirements.txt ``` -If you run into conflicts with existing packages, a solution is to use a virtual Python environment. See the [Pelican installation page][2] for more details. These are quick commands, Linux flavor: +If you run into conflicts with existing packages, a solution is to use a virtual Python environment. See the [Pelican installation page][3] for more details. These are quick commands, Linux flavor: ```sh python3 -m venv env @@ -43,7 +44,6 @@ You can also tell Pelican to watch for your modifications, instead of manually r pelican --autoreload --listen ``` -Remember that on Mac/Linux you can use the `build.sh` script with `-l` option to do the same. - -[1]: https://blog.getpelican.com/ -[4]: https://www.python.org/downloads/ +[1]: https://getpelican.com +[2]: https://www.python.org/downloads/ +[3]: https://docs.getpelican.com/en/stable/install.html From 667a489f226b0b16828594282615fcb142ba8e94 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Jan=20H=C3=B8ydahl?= Date: Wed, 26 Jun 2024 13:25:54 +0200 Subject: [PATCH 4/7] Use python:3-alpine as base image --- README.md | 2 +- build.sh | 15 +++++++-------- 2 files changed, 8 insertions(+), 9 deletions(-) diff --git a/README.md b/README.md index 1af5fc977..87eb1aea0 100644 --- a/README.md +++ b/README.md @@ -28,7 +28,7 @@ If you want to build the site without the docker image, you can install Python 3 On Windows, you can use the Windows Subsystem for Linux (WSL) to run the build script. Or you can run the docker command directly in a Terminal: - docker run --rm -ti -w /work -p 8000:8000 -v $(pwd):/work qwe1/docker-pelican:4.8.0 sh -c "pip3 install -r requirements.txt; pelican content -r -l -b 0.0.0.0" + docker run --rm -ti -w /work -p 8000:8000 -v $(pwd):/work python:3-alpine sh -c "pip3 install -r requirements.txt; pelican content -r -l -b 0.0.0.0" ## Updating site during a Solr release diff --git a/build.sh b/build.sh index e84945ff5..e69c79ff8 100755 --- a/build.sh +++ b/build.sh @@ -18,10 +18,9 @@ set -e #set -x -# Using https://hub.docker.com/r/qwe1/docker-pelican as pelican image, supports both AMD64 and ARM64 -PELICAN_IMAGE="qwe1/docker-pelican:4.8.0" -SOLR_PELICAN_IMAGE="solr-pelican-image" -DOCKER_CMD="docker run --rm -ti -w /work -p 8000:8000 -v $(pwd):/work $SOLR_PELICAN_IMAGE" +PYTHON_IMAGE="python:3-alpine" +SOLR_LOCAL_PELICAN_IMAGE="solr-pelican-image" +DOCKER_CMD="docker run --rm -ti -w /work -p 8000:8000 -v $(pwd):/work $SOLR_LOCAL_PELICAN_IMAGE" unset SERVE PIP_CMD="pip3 install -r requirements.txt" PELICAN_CMD="pelican content -o output" @@ -36,16 +35,16 @@ function usage { } function build_image { - echo "Building local Docker image for Pelican, called $SOLR_PELICAN_IMAGE." + echo "Building local Docker image for Pelican, called $SOLR_LOCAL_PELICAN_IMAGE." # Make a new local image with the pip packages installed docker rm -f solr-pelican >/dev/null 2>&1 || true - docker run --name solr-pelican -w /work -v $(pwd):/work $PELICAN_IMAGE sh -c "$PIP_CMD" - docker commit solr-pelican $SOLR_PELICAN_IMAGE + docker run --name solr-pelican -w /work -v $(pwd):/work $PYTHON_IMAGE sh -c "$PIP_CMD" + docker commit solr-pelican $SOLR_LOCAL_PELICAN_IMAGE docker rm -f solr-pelican >/dev/null 2>&1 || true } function ensure_image { - if ! docker inspect $SOLR_PELICAN_IMAGE >/dev/null 2>&1 + if ! docker inspect $SOLR_LOCAL_PELICAN_IMAGE >/dev/null 2>&1 then build_image fi From d6c52b69841c2adfbc16497320344062d6d7a010 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Jan=20H=C3=B8ydahl?= Date: Wed, 26 Jun 2024 15:04:54 +0200 Subject: [PATCH 5/7] Auto rebuild when requirements.txt has changed --- README.md | 3 +-- build.sh | 36 ++++++++++++++++++++++++++++++++---- 2 files changed, 33 insertions(+), 6 deletions(-) diff --git a/README.md b/README.md index 87eb1aea0..72c0a03c4 100644 --- a/README.md +++ b/README.md @@ -15,9 +15,8 @@ If the staged site looks good, simply merge the changes to branch `production` a For larger edits it is recommended to build and preview the site locally. This lets you see the result of your changes instantly without committing anything. The bundled script uses a pelican docker image to build and serve the site locally. Please make sure you have docker installed. - # Usage: ./build.sh [-l] [-b] [] + # Usage: ./build.sh [-l] [] # -l Live build and reload source changes on localhost:8000 - # -b Re-build local docker image, re-installing packages from requirements.txt ./build.sh -l Now go to to view the beautiful Solr web page served from your laptop with live-preview of updates :) diff --git a/build.sh b/build.sh index e69c79ff8..54bc02d0d 100755 --- a/build.sh +++ b/build.sh @@ -28,9 +28,8 @@ PELICAN_OPTS="" export SITEURL="https://solr.apache.org/" function usage { - echo "Usage: ./build.sh [-l] [-b] []" + echo "Usage: ./build.sh [-l] []" echo " -l Live build and reload source changes on localhost:8000" - echo " -b Re-build local docker image, re-installing packages from requirements.txt" echo " --help Show full help for options that Pelican accepts" } @@ -50,6 +49,36 @@ function ensure_image { fi } +function check_requirements_update { + # Get the last modified time of requirements.txt + local req_mod_time + if [[ $(uname) == "Darwin" ]]; then + req_mod_time=$(stat -f "%m" requirements.txt) + else + req_mod_time=$(stat -c "%Y" requirements.txt) + fi + + # Get the build timestamp of the docker image + local image_build_time + image_build_time=$(docker inspect --format='{{.Created}}' $SOLR_LOCAL_PELICAN_IMAGE) + + # Parse the timestamp into seconds since epoch in UTC + if [[ $(uname) == "Darwin" ]]; then + # macOS date command workaround + image_build_time=$(echo "$image_build_time" | awk -F '.' '{print $1}') + image_build_time=$(date -ju -f "%Y-%m-%dT%H:%M:%S" "$image_build_time" "+%s") + else + # Linux date command + image_build_time=$(date -d "$(echo "$image_build_time" | cut -d'.' -f1 | sed 's/T/ /; s/Z//')" --utc "+%s") + fi + + # Compare the timestamps and build the image if requirements.txt is newer + if [[ $req_mod_time -gt $image_build_time ]]; then + echo "requirements.txt has been updated since the last build, rebuilding image!" + build_image + fi +} + if ! docker -v >/dev/null 2>&1 then echo "ERROR: This script requires docker." @@ -93,14 +122,13 @@ done shift $((OPTIND -1)) ensure_image +check_requirements_update if [[ $SERVE ]]; then echo "Building Solr site locally. Goto http://localhost:8000 to view." echo "Edits you do to the source tree will be compiled immediately!" - echo "Changes to requirements.txt will require using -b option to rebuild the image." $DOCKER_CMD sh -c "$PELICAN_CMD --autoreload --listen -b 0.0.0.0 $PELICAN_OPTS $*" else echo "Building Solr site locally." echo "To build and serve live edits locally, run this script with -l argument. Use -h for help." - echo "Changes to requirements.txt will require using -b option to rebuild the image." $DOCKER_CMD sh -c "$PELICAN_CMD $PELICAN_OPTS $*" fi From 4561009d5637198dc6cb7179ffeb019a0dd4a53d Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Jan=20H=C3=B8ydahl?= Date: Wed, 26 Jun 2024 15:10:21 +0200 Subject: [PATCH 6/7] Help line --- README.md | 1 + 1 file changed, 1 insertion(+) diff --git a/README.md b/README.md index 72c0a03c4..859f183a0 100644 --- a/README.md +++ b/README.md @@ -17,6 +17,7 @@ The bundled script uses a pelican docker image to build and serve the site local # Usage: ./build.sh [-l] [] # -l Live build and reload source changes on localhost:8000 + # --help Show full help for options that Pelican accepts ./build.sh -l Now go to to view the beautiful Solr web page served from your laptop with live-preview of updates :) From 1337500784ae11b32aeaf2d44181a1534b4b7a67 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Jan=20H=C3=B8ydahl?= Date: Wed, 26 Jun 2024 21:46:05 +0200 Subject: [PATCH 7/7] Show usage for --help too --- build.sh | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/build.sh b/build.sh index 54bc02d0d..861179f1f 100755 --- a/build.sh +++ b/build.sh @@ -28,7 +28,7 @@ PELICAN_OPTS="" export SITEURL="https://solr.apache.org/" function usage { - echo "Usage: ./build.sh [-l] []" + echo "Usage: ./build.sh [-l] [-h] []" echo " -l Live build and reload source changes on localhost:8000" echo " --help Show full help for options that Pelican accepts" } @@ -103,6 +103,7 @@ while getopts ":lbh-:" opt; do - ) case "${OPTARG}" in help ) + usage echo echo "Below is a list of other arguments you can use which will be passed to pelican." echo