diff --git a/docs/contributing/features.md b/docs/contributing/features.md index b4d681976a..7da372de13 100644 --- a/docs/contributing/features.md +++ b/docs/contributing/features.md @@ -12,6 +12,7 @@ Please follow the process below to suggest a new feature for inclusion in one of describing the feature you'd like to contribute. 2. Discuss with the maintainers whether the addition makes sense in [one of the core stacks](../using/selecting.md#core-stacks), + as a [way to build a custom set of images](../using/custom-images.md), as a [recipe in the documentation](recipes.md), as a [community stack](stacks.md), or as something else entirely. diff --git a/docs/index.rst b/docs/index.rst index 896ca0f7da..23aa0e90de 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -13,6 +13,7 @@ Table of Contents using/common using/specifics using/recipes + using/custom-images using/troubleshooting using/faq diff --git a/docs/using/custom-images.md b/docs/using/custom-images.md new file mode 100644 index 0000000000..ad2ca87b87 --- /dev/null +++ b/docs/using/custom-images.md @@ -0,0 +1,82 @@ +# 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` - a docker argument of `docker-stacks-foundation` image +- `PYTHON_VERSION` - a docker argument of `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. diff --git a/docs/using/recipes.md b/docs/using/recipes.md index 46c6edb6aa..69ecf9e180 100644 --- a/docs/using/recipes.md +++ b/docs/using/recipes.md @@ -4,6 +4,9 @@ Users sometimes share interesting ways of using the Jupyter Docker Stacks. We encourage users to [contribute these recipes](../contributing/recipes.md) to the documentation in case they prove helpful to other community members by submitting a pull request to `docs/using/recipes.md`. The sections below capture this knowledge. +All the recipes here assume you would like to use an image built by this project and install some things on top of it. +If you would like to build a custom set of images, [take a look at the docs](custom-images.md). + ## Using `sudo` within a container Password authentication is disabled for the `NB_USER` (e.g., `jovyan`). @@ -517,57 +520,3 @@ they may be explained in the "Installation instructions" section of the Download ```{literalinclude} recipe_code/oracledb.dockerfile :language: docker ``` - -## 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](https://jupyter-docker-stacks.readthedocs.io/en/latest/contributing/stacks.html), -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 build 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 using: - -```bash -docker run custom-jupyter -``` - -or referenced in a docker compose file.