mirror of
https://github.com/jupyter/docker-stacks.git
synced 2025-10-10 03:23:00 +00:00
82 lines
2.9 KiB
Markdown
82 lines
2.9 KiB
Markdown
# 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](https://jupyter-docker-stacks.readthedocs.io/en/latest/#using-old-images).
|
|
|
|
## Automating your build using template cookiecutter project
|
|
|
|
If you wish to build your own image on top of one of our images and automate your build process,
|
|
please, [take a look at cookiecutter template](../contributing/stacks.md).
|
|
|
|
## Custom arguments
|
|
|
|
Existing customization points:
|
|
|
|
- `ROOT_CONTAINER`, `PYTHON_VERSION` - docker arguments of a `docker-stacks-foundation` image
|
|
- `REGISTRY`, `OWNER`, `BASE_CONTAINER` - docker arguments for all the other images we build
|
|
- `REGISTRY`, `OWNER` - part of `env` in most of our GitHub workflows
|
|
|
|
## Building stack images with custom arguments
|
|
|
|
A selection of prebuilt images are available from [Quay.io](https://quay.io/organization/jupyter),
|
|
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](../contributing/stacks),
|
|
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](https://docs.docker.com/build/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:
|
|
|
|
```{code-block} Dockerfile
|
|
:caption: Dockerfile
|
|
|
|
ARG BASE_CONTAINER=minimal-notebook
|
|
FROM $BASE_CONTAINER
|
|
...
|
|
```
|
|
|
|
Include the below file in your project:
|
|
|
|
```{literalinclude} recipe_code/docker-bake.python312.hcl
|
|
:force:
|
|
:language: hcl
|
|
:caption: docker-bake.hcl
|
|
```
|
|
|
|
To build this stack, in the same directory run:
|
|
|
|
```bash
|
|
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:
|
|
|
|
```bash
|
|
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.
|