Skip to content

update_sitebuilder.md

Latest commit

 

History

History
183 lines (138 loc) · 7.67 KB

update_sitebuilder.md

File metadata and controls

183 lines (138 loc) · 7.67 KB

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.

Update packages

  • Define docker image tag, e.g., 1.5.8 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 and dart-sass with mydartsass variable. Change installation commands for prebuilt go and dart-sass binaries as and when required.

  • 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.

build and push multi-arch images

Here, I am using docker buildx build from Docker Desktop v4.22.0 on mac os 15.3 M2 to build both, amd64 and arm64/v8 images. See this guide for multi-arch builds.

  • 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.
## platform variable will be parsed in Dockerfile as TARGETPLATFORM
## to download platform specific hugo and go packages

## requires login to docker hub from Docker Desktop app
## replace --push with --load to load arch specific image locally
docker buildx build \
	--platform linux/arm64/v8,linux/amd64 \
	--tag sbamin/sitebuilder:1.5.9 \
	--tag sbamin/sitebuilder:latest \
	--push \
	--file Dockerfile .

Check docker hub: sbamin/sitebuilder and should show an updated tag. If so, update local image using docker images and then docker pull sbamin/sitebuilder to get a latest tag.

update Gemfile.lock

  • 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 --rm -it -v "$(pwd)":/hostspace sbamin/sitebuilder /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
## we already pushed both, updated version and latest tag to docker
docker run --rm sbamin/sitebuilder /bin/bash -c "jekyll --version && hugo version && git version && go version && pip list | grep -E 'mkdocs|quarto' && pagefind --version && sass --version"

## for non-os compliant OS, e.g., amd64 if using macos M2
docker run --platform linux/amd64 --rm sbamin/sitebuilder /bin/bash -c "jekyll --version && hugo version && git version && go version && pip list | grep -E 'mkdocs|quarto' && pagefind --version && sass --version"

Update github releases

git add Dockerfile Gemfile Gemfile.lock update_sitebuilder.md README.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.9

- ✨ added pagefind search
- 🙅‍♂️ mkquartodocs plugin is not functional
  - prefer running quarto docs locally and copy generated md or html to sitebuilder

## amd64

jekyll 3.10.0
hugo v0.155.3-8a858213b73907e823e2be2b5640a0ce4c04d295+extended linux/amd64 BuildDate=2026-02-08T16:40:42Z VendorInfo=gohugoio
git version 2.39.5
go version go1.26.0 linux/amd64
mkdocs                                    1.6.1
mkdocs-autorefs                           1.4.4
mkdocs-get-deps                           0.2.0
mkdocs-git-authors-plugin                 0.10.0
mkdocs-git-committers-plugin-2            2.5.0
mkdocs-git-revision-date-localized-plugin 1.5.1
mkdocs-git-revision-date-plugin           0.3.2
mkdocs-glightbox                          0.5.2
mkdocs-macros-plugin                      1.5.0
mkdocs-material                           9.7.1
mkdocs-material-extensions                1.3.1
mkdocs-minify-plugin                      0.8.0
mkdocs-redirects                          1.2.2
mkdocs-rss-plugin                         1.17.9
mkdocstrings                              1.0.3
mkdocstrings-python                       2.0.2
mkdocstrings-shell                        1.0.4
mkquartodocs                              0.7.0
pagefind 1.5.0-beta.1
Ruby Sass 3.7.4

## arm64

jekyll 3.10.0
hugo v0.155.3-8a858213b73907e823e2be2b5640a0ce4c04d295+extended linux/arm64 BuildDate=2026-02-08T16:40:42Z VendorInfo=gohugoio
git version 2.39.5
go version go1.26.0 linux/arm64
mkdocs                                    1.6.1
mkdocs-autorefs                           1.4.4
mkdocs-get-deps                           0.2.0
mkdocs-git-authors-plugin                 0.10.0
mkdocs-git-committers-plugin-2            2.5.0
mkdocs-git-revision-date-localized-plugin 1.5.1
mkdocs-git-revision-date-plugin           0.3.2
mkdocs-glightbox                          0.5.2
mkdocs-macros-plugin                      1.5.0
mkdocs-material                           9.7.1
mkdocs-material-extensions                1.3.1
mkdocs-minify-plugin                      0.8.0
mkdocs-redirects                          1.2.2
mkdocs-rss-plugin                         1.17.9
mkdocstrings                              1.0.3
mkdocstrings-python                       2.0.2
mkdocstrings-shell                        1.0.4
mkquartodocs                              0.7.0
pagefind 1.5.0-beta.1
Ruby Sass 3.7.4

EOF

git push

Update docker image

With buildx command and --push argument above, we already have uploaded images to docker hub, include latest alias.

  • 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.*

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

  • If using github container repo, this should work.

NOTE: Since sitebuilder tag: 1.5.5, future updates will always be pushed to docker hub but occasionally to github repo.

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

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

Get singularity SIF image

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

## assuming running on linux/amd64 architecture.
singularity run docker://sbamin/sitebuilder:latest
## or a specific version
singularity run docker://sbamin/sitebuilder:1.5.6

Done!