Building a custom set of images#
This section describes how to build a custom set of images. It may be helpful if you need to change the Ubuntu or Python version, or to make a significant change to the build process itself.
This project only builds one set of images at a time. If you want to use older images, take a look here.
Custom arguments#
Our repository provides several customization points:
ROOT_IMAGE
(docker argument) - the parent image fordocker-stacks-foundation
imagePYTHON_VERSION
(docker argument) - the Python version to install indocker-stacks-foundation
imageREGISTRY
,OWNER
,BASE_IMAGE
(docker arguments) - they allow to specify parent image for all the other imagesREGISTRY
,OWNER
(part ofenv
in some GitHub workflows) - these allow to properly tag and refer to images during following steps:build-test-upload
,tag-push
andmerge-tags
These customization points can’t be changed during runtime. Read more about Docker build arguments and GitHub environment variables for a single workflow.
Building stack images with custom arguments#
A selection of prebuilt images are available from Quay.io, however, it’s impossible to cater to everybody’s needs. For extensive customization with an automated build pipeline, you may wish to create a community-maintained stack, however, for minor customizations, this may be overkill. For example, you may wish to use the same Jupyter stacks but built on a different base image, or built with a different Python version.
To achieve this you can use Docker Bake to build the stacks locally with custom arguments.
Note
Custom arguments may result in build errors due to incompatibility. If so your use-case may require a fully customized stack.
As a basic example, if you want to build a custom image based on the minimal-notebook
image using Python 3.12
,
then with a Dockerfile like:
ARG BASE_IMAGE=minimal-notebook
FROM $BASE_IMAGE
...
Include the below file in your project:
group "default" {
targets = ["custom-notebook"]
}
target "foundation" {
context = "https://github.com/jupyter/docker-stacks.git#main:images/docker-stacks-foundation"
args = {
PYTHON_VERSION = "3.12"
}
tags = ["docker-stacks-foundation"]
}
target "base-notebook" {
context = "https://github.com/jupyter/docker-stacks.git#main:images/base-notebook"
contexts = {
docker-stacks-foundation = "target:foundation"
}
args = {
BASE_IMAGE = "docker-stacks-foundation"
}
tags = ["base-notebook"]
}
target "minimal-notebook" {
context = "https://github.com/jupyter/docker-stacks.git#main:images/minimal-notebook"
contexts = {
base-notebook = "target:base-notebook"
}
args = {
BASE_IMAGE = "base-notebook"
}
tags = ["minimal-notebook"]
}
target "custom-notebook" {
context = "."
contexts = {
minimal-notebook = "target:minimal-notebook"
}
args = {
BASE_IMAGE = "minimal-notebook"
}
tags = ["custom-jupyter"]
}
To build this stack, in the same directory run:
docker buildx bake
Docker Bake then determines the correct build order from the contexts
parameters
and builds the stack as requested.
This image can then be run the same way as any other image provided by this project, for example:
docker run -it --rm -p 8888:8888 custom-jupyter
or referenced in a Docker Compose file.
Forking our repository#
If for some reason, you need to change more things in our images, feel free to fork it and change it any way you want. If your customization is easy to backport to the main repo and might be helpful for other users, feel free to create a PR.
It is almost always a great idea to keep your diff as small as possible and to merge/rebase the latest version of our repo in your project.