update_sitebuilder.md

Building your own sitebuilder container

Requires Docker and git

• Clone sitebuilder repo

mkdir -p ~/tmp
cd tmp
git clone https://github.com/sbamin/sitebuilder.git
cd sitebuilder
git pull
git status

status should be up-to-date and point to main git branch.

• Define docker image tag, e.g., 1.5.4 typically a level up than the current version. You need to manually update several of commands below to reflect an updated tag.

• Update Dockerfile as per your custom changes. At minimum, update LABEL version and mode to reflect an updated tag. You can also update hugo extended to the current release by updating myhugo ENV variable in Dockerfile. Optionally, update related go version with mygo ENV variable.

• If you need to update jekyll related gems, update Gemfile while ensuring gem version requirements for github-pages gem.

• If you need to update mkdocs-material theme, please make related changes to mkdocs installation in Dockerfile as per author's instructions from mkdocs-material website.

• Start building a docker image. You need to replace sbamin/sitebuilder with your respective docker hub user id and image name you like to rename. Read manpage for docker build.

## build amd64 version first
docker build --platform linux/amd64 -f Dockerfile -t sbamin/sitebuilder:1.5.4 .

NOTE: If using docker on Mac M1/M2, you should add --platform linux/amd64 given sitebuilder docker image is configured for amd64 and not arm64 architecture. To use arm64 architecture, you need to update Dockerfile to replace amd64 packages with arm64 ones, if available from a respective developer. See relevant details here.

• Optional: To build arm64 docker image, use a separate Dockerfile that installs arm64 packages of hugo and go.

docker build --platform linux/arm64 -f Dockerfile_arm64 -t sbamin/sitebuilder:1.5.4_arm64 .

PS: Rest of steps are implied for amd64 image, and can be followed for arm64 image too with applicable changes to docker image name.

• Once image is successfully built, copy Gemfile.lock back to host, so that we can update it with the most recent versions of gems.

## start container in an interactive session and mount local (host) directory
## to an empty location in the docker container.
docker run --platform linux/amd64 --rm -it -v "$(pwd)":/hostspace sbamin/sitebuilder:1.5.4 /bin/bash

## copy (overwrite) local Gemfile.lock with an updated version from 
## the container
cp /scratch/Gemfile.lock /hostspace/

## exit container
exit

• Check installed or updated package versions

docker run --platform linux/amd64 --rm sbamin/sitebuilder:1.5.4 /bin/bash -c "jekyll --version && hugo version && git version && go version && pip list | grep mkdocs"

docker run --platform linux/arm64 --rm sbamin/sitebuilder:1.5.4_arm64 /bin/bash -c "jekyll --version && hugo version && git version && go version && pip list | grep mkdocs"

• Commit and push those to github.

git add Dockerfile Gemfile.lock update_sitebuilder.md

## write a multiline git commit message
## -s requires a valid gpg key for signing a message
git commit -s -F- <<EOF
Updated sitebuilder
v1.5.4

## amd64

jekyll 3.9.5
hugo v0.122.0-b9a03bd59d5f71a529acb3e33f995e0ef332b3aa+extended linux/amd64 BuildDate=2024-01-26T15:54:24Z VendorInfo=gohugoio
git version 2.30.2
go version go1.22.0 linux/amd64
mkdocs                                    1.5.3
mkdocs-git-authors-plugin                 0.7.2
mkdocs-git-revision-date-localized-plugin 1.2.4
mkdocs-git-revision-date-plugin           0.3.2
mkdocs-macros-plugin                      1.0.5
mkdocs-material                           9.5.9
mkdocs-material-extensions                1.3.1
mkdocs-minify-plugin                      0.8.0
mkdocs-redirects                          1.2.1

## arm64

jekyll 3.9.5
hugo v0.122.0-b9a03bd59d5f71a529acb3e33f995e0ef332b3aa+extended linux/arm64 BuildDate=2024-01-26T15:54:24Z VendorInfo=gohugoio
git version 2.30.2
go version go1.22.0 linux/arm64
mkdocs                                    1.5.3
mkdocs-git-authors-plugin                 0.7.2
mkdocs-git-revision-date-localized-plugin 1.2.4
mkdocs-git-revision-date-plugin           0.3.2
mkdocs-macros-plugin                      1.0.5
mkdocs-material                           9.5.9
mkdocs-material-extensions                1.3.1
mkdocs-minify-plugin                      0.8.0
mkdocs-redirects                          1.2.1

EOF

git push

Update docker image

Upload your docker image to docker hub, github packages, or your preferred container hub.

• Tag or alias updated image to latest. This will overwrite existing alias to latest which is typically an older image, e.g., 1.5.1

## unless beta version, remove older docker image tagged as latest, if any on local computer.
docker rmi sbamin/sitebuilder:latest
docker tag sbamin/sitebuilder:1.5.4 sbamin/sitebuilder:latest

• Besides updating Docker Hub, if you are updating image also to github packages, update respective aliases.

## unless beta version, remove older versions
docker rmi ghcr.io/sbamin/sitebuilder:latest
docker tag sbamin/sitebuilder:1.5.4  ghcr.io/sbamin/sitebuilder:1.5.4
docker tag ghcr.io/sbamin/sitebuilder:1.5.4  ghcr.io/sbamin/sitebuilder:latest

• Confirm using docker images that IMAGE ID of a built image, sbamin/sitebuilder:1.5.x matches with aliases created above. If all good, remove previous version of sitebuilder, docker rmi sbamin/sitebuilder:1.5.0

• Before pushing images, worth doing a test build and preview run as per README.md

• Push images to docker hub and/or github packages. For github container registry, see this guide on authentication.

docker push sbamin/sitebuilder:1.5.4
docker push sbamin/sitebuilder:latest
docker push sbamin/sitebuilder:1.5.4_arm64

## avoid echo raw password!
## echo $(<decrypt pwd>) | docker login ghcr.io -u USERNAME --password-stdin

docker push ghcr.io/sbamin/sitebuilder:1.5.4
docker push ghcr.io/sbamin/sitebuilder:latest
docker push ghcr.io/sbamin/sitebuilder:1.5.4_arm64

Get singularity SIF image

If you prefer using singularity SIF image, run following command to get an updated SIF image.

## assuming running on linux/amd64 architecture.
singularity run docker://sbamin/sitebuilder:latest
## or beta version
singularity run docker://sbamin/sitebuilder:1.5.4

Done!