Skip to content

Docker dev container

Jump to bottom
Ian Thomas edited this page Mar 20, 2023 · 10 revisions

Bokeh development docker container

Introduction

A docker image is created periodically and is available at docker hub (https://hub.docker.com/r/bokeh/bokeh-dev/tags). The image allows users to build and run bokeh in a controlled Linux environment (Ubuntu 22.04) regardless of the Operating System they are running on.

The idea is that the developer has the bokeh github repository checked out locally on their computer. Call this the "host" system. The developer then downloads the latest docker image and runs this image in a new docker container. The directory containing the bokeh github repo on the host system is shared with the docker container (this is known as a docker volume) so that both can read and write to the shared directory.

The expected usage is for a code editor (e.g. vscode) to run on the host system with access to the source code, and a separate command-line terminal is used for the docker container, in which the user compiles bokeh, runs tests, etc.

The docker container installs miniconda and all of the bokeh conda dependencies into the directory /home/docker/conda_bokeh in the container. When the container is started for the first time, if this directory does not exist then it will be created and the conda environment downloaded and installed. When the installation is finished the docker container activates the bkdev conda environment ready for the developer to use. Whenever the same container is restarted the directory will already exist and hence the user will be dropped into the docker command line straight away. If there are ever any problems with the conda environment, the /home/docker/conda_bokeh directory can be deleted and the next time the container is started it will be recreated from scratch.

Workflow

  1. Ensure you have docker installed. This is Docker Desktop on macOS and Windows, and a command-line tool on Linux.

  2. Ensure you have git installed.

  3. Clone the bokeh github repo in the usual manner. Check out the correct git branch before starting the container for the first time to ensure that you are using one of the correct yml files which determine which conda packages to download and install.

  4. cd to the base directory of your bokeh github repository.

  5. If you are on macOS or Windows, start Docker Desktop.

  6. Start a new docker container using the script that is in the Bokeh code base in the scripts/docker directory.

    1. On Linux or macOS use scripts/docker/docker_run.sh bokeh/bokeh-dev:branch-3.1

    2. On Windows using PowerShell use bash ./scripts/docker/docker_run.sh bokeh/bokeh-dev:branch-3.1

    3. By default the system will use conda Python 3.9. If you wish to use a different version of Python, e.g. 3.10, use something like BOKEH_DOCKER_PY=3.10 scripts/docker/docker_run.sh bokeh/bokeh-dev:latest

    4. When the container starts it checks that it is in the base directory of a bokeh github repo and whether or not conda has been installed into the directory /home/docker/conda_bokeh. If conda has not been installed it downloads and installs miniconda and the required dependencies according to the version of Python required. For example, if Python 3.9 is requested it will use the list of dependencies from scripts/environment-test-3.9.yml.

  7. Control is then returned to the user in a bash shell which already has the conda bkdev environment enabled. This can be used in the normal way.

    1. To build bokeh, use pip install -ve .

    2. To run an example bokehjs integration test, use cd bokehjs; node make test:integration -k "Blackbody".

    3. To run a bokeh serve example use bokeh serve --show examples/server/app/sliders.py. This uses port 5006 on the docker container which is mapped directly across to localhost:5006 of the host system and can hence be viewed in the host system as usual by opening a browser at localhost:5006/sliders

    4. To leave the docker container, type exit

  8. When the container is closed, it is kept on disk so that it can be restarted without having to reinstall conda, etc. To restart it:

    1. Obtain the ID of the container using docker ps -a. The container ID is a 12-character long hexadecimal number.

    2. Restart the container using docker start -i <container_id> using the correct container ID.

  9. If you want to completely stop a container and remove all resources (disk space) that it is using, use docker rm. See https://docs.docker.com/engine/reference/commandline/rm/ for the options here.

Notes for Windows users

The image has been tested on Windows 11, but care is needed to avoid some common problems.

  1. If the bokeh github repo is stored on the Windows filesystem, it will not have executable flags for the bash scripts. Hence it may be necessary to prefix the running of shell scripts with bash.

  2. Windows uses different line endings to Linux which can cause problems. There are various options when installing git on Windows to deal with this.

  3. Use PowerShell to run docker commands.

  4. Use Linux forward slashes not Windows back slashes for paths when using bash.

Advanced

There are a number of environment variables you can use when starting a docker container for the first time, e.g. BOKEH_DOCKER_CHROME_VERSION=1 scripts/docker/docker_run.sh bokeh/bokeh-dev:branch-3.1. These are:

  • BOKEH_DOCKER_CHROME_VERSION=1. Print the version of chrome used in the container and return immediately. This is used by the docker github action to correctly tag the image with the chrome version.

  • BOKEH_DOCKER_CONDA=0. Do not automatically install conda and the dependencies. This can be useful for checking something within the container without having to wait for the conda install.

  • BOKEH_DOCKER_PY=3.10 or some other version. Use scripts/environment-test-3.10.yml to install a conda environment with a particular version of Python. The default is 3.9.

There are also environment variables that are used by the various github actions in CI:

  • BOKEH_DOCKER_BUILD=1. Build Bokeh before returning control to the user.

  • BOKEH_DOCKER_FROM_WHEEL=1. Install Bokeh from an already generated wheel and run the local tests against that.

  • BOKEH_DOCKER_INTERACTIVE=0. Do not return control to the user when the docker image is up and running.

  • BOKEH_DOCKER_TEST=1. Run Bokeh tests before returning control to the user.

Clone this wiki locally