Create dev environment with docker

[trungleduc]

References

Similar to the gitpod setup, but for people who prefer to work offline.
To start a JupyterLab dev container on a UNIX system with docker installed:

bash docker/start.sh

This command will build the docker image if it does not exist, then start the container with JupyterLab running in watch mode. The port 8888 is exposed and the current JupyterLab repo is mounted into the container.

Other available commands:

• bash docker/start.sh dev: same as calling bash docker/start.sh
• bash docker/start.sh stop: stop the running container
• bash docker/start.sh clean: remove the docker image
• bash docker/start.sh build: rebuild the docker image
• bash docker/start.sh shell: log into the container's shell with the JupyterLab environment activated. It's useful to run the tests or install dependencies.

How it works

To avoid polluting the node_module directory with packages coming from the host machine while still preserving the hot-reload capability, the js dependencies in the container are actually stored in the /home/$DEV_USER/jupyterlab_cache/node_modules/ while the working directory is mounted to /home/$DEV_USER/jupyterlab. On container startup, the node_modules at jupyterlab_cache is rsync-ed back to the host.

Since the image and container name contain the hash of the current JupyterLab directory, two clones of JupyterLab will generate different images.

How to add dependencies

Due to the above setup, the easiest way to add new dependencies is to log into the container's shell, install the dependencies to update the package.json and yarn.lock files, and then rebuild the docker image.

bash docker/start.sh shell
# In the container shell
jlpm add ...
exit
# back to host shell
bash docker/start.sh build

[jupyterlab-probot]

Thanks for making a pull request to jupyterlab!
To try out this branch on binder, follow this link:

[trungleduc]

cc @jtpio for awareness

[jtpio]

Thanks @trungleduc.

Maybe this will also be useful to enable better support for dev containers and GitHub Codespaces. And also streamline the setup between Gitpod and Codespaces: #13049

[jtpio]

Also should there be a new section in the contributing guide to mention how to use this setup? https://jupyterlab.readthedocs.io/en/latest/developer/contributing.html

[trungleduc]

Also should there be a new section in the contributing guide to mention how to use this setup? https://jupyterlab.readthedocs.io/en/latest/developer/contributing.html

Done

[jtpio]

Similar to the discussion about Vagrant (#12806 and jupyterlab/frontends-team-compass#152 (comment)), one of the main challenges with this setup will be for maintainers to be able to maintain this Docker configuration, since Docker is yet another tool and not everyone might be familiar with it.

But since Docker is available on GitHub Actions by default maybe there could be a way to put it under tests? To make sure the config does not lag behind or become out of date.

[trungleduc]

@jtpio I added a workflow for building and starting the dev container (https://github.com/jupyterlab/jupyterlab/actions/runs/6312097376/job/17137422797?pr=15111). But I am not sure about the activation rate, running this test on every commit wastes a lot of resources.

[krassowski]

We could run it on PR approval only, as we do with benchmarks.

[jtpio]

Otherwise as a cron job?

But I guess we would first need to know if someone from the JupyterLab maintainers will be willing to maintain this new dev setup.

[trungleduc]

Otherwise as a cron job?

But I guess we would first need to know if someone from the JupyterLab maintainers will be willing to maintain this new dev setup.

I can maintain this script but I am also open to move it outside of the JupyterLab repo

[krassowski]

I am ok with having this in if it helps at least one contributor - if it falls unmaintained, removing it will be easy (4 files to delete plus documentation fragment to cut).

[fcollonval]

Thanks @trungleduc

[trungleduc]

Otherwise as a cron job?

But I guess we would first need to know if someone from the JupyterLab maintainers will be willing to maintain this new dev setup.

a cron job sounds good! I'll update the action script.

[krassowski]

Thanks!