Mar 27, 2023

CartoLab-Docker

CartoLab-Docker was released in version 0.13.0 and I thought it deserves a dedicated post.

CartoLab is a Docker container that runs a JupyterLab-Server, with a prepared environment for cartographic visualizations, called worker_env.

I pretty much use CartoLab-Docker every day and it has advanced a lot over the past two years.

This is an (incomplete) list of features:

  • completely versioned using multiple docker tags (latest, stable, mapnik)
  • all versions are available as docker images from our registry, to be used (e.g.) in the provided docker-compose.yml
  • we take extra care to make sure that all provided cartographic packages in the default worker_env are compatible, have a look at the list of packages in the Readme
  • the Docker tag mapnik provides the option to run access Mapnik in Jupyter, see an example here
  • JupyterLab comes with several extensions such as Jupytext, for git versioning for notebooks
  • the Docker container will automatically shutdown after an inactivity timeout (no running notebooks) of 30 Minutes
  • the JupyterLab is password protected, using a password provided through the .env file
  • there are many options to customize the image through environmental variables in the .env file
  • we have also a deployment of CartoLab-Docker in a Kubernetes cluster, together with JupyterHub, have a look at the repository here

Roadmap: My goal is to build a complete python-based cartographic visualization workflow and publication system around CartoLab-Docker. One example is a Jupyter Base Template I created for CartoLab, with a git structure that sets up a project, initialized CI/CD and prepares notebooks with custom layout/html exports (etc.). Common tools that I need in many cartographic visualization workflows are made available from a git submodule and maintained centrally for all notebooks. The next step for CartoLab-Docker is to prepare a thorough documentation, illustrating common use cases and example workflows.

Have a look at the changelog, which provides an overview of the recent changes:

v0.13.0 (2023-03-27)

Feature

  • Add default persistent environment path and update docs (9b85dd5)

Fix

v0.12.3 (2023-02-21)

Fix

  • Incompatibility between numpy>1.2 and Shapely<1.8 (6dcade0)

Documentation

  • Update reference to docker-compose build with explicit compose file (80d4cd9)

v0.11.0 (2023-02-03)

Feature

  • Add TAG environemnt-variable to pin specific versions in docker-compose.yml (e8144b8)
  • Bump nbconvert from 6.5.* to 7.2.* (ee20a57)

Fix

Documentation

  • Add explicit docker network create (023e4c7)
  • Suggest to pull registry image, to prevent build of image by default (0879b51)
  • Clarify steps to setup svg_export (cbb888e)
  • Update readme header (5e26d21)

v0.9.0 (2022-08-30)

Feature

  • Add .version to Dockerfile, to be able to get the Container version at runtime (31ed7cb)

Fix

  • Ipywidgets compatibility (bb1c0be)
  • CI extract version from file (9d10722)
  • Use master-latest for versioned releases (6d390ef)

Documentation

  • Add instructions to install selenium and webdriver (cb4038a)
  • Add COMPOSE_FILE to .env examples (5cf73a2)
  • Update header (c57caa3)

v0.8.1 (2022-08-25)

CI

  • Automatic versioning of registry images

Feature

  • Add Mapnik docker and tag (3ce9d06)

Fix

  • Nbconvert pinned to old version (fb611fc)
  • Incompatible geoviews package for latest holoviews release (5baa575)

Documentation

  • Update readme to include collaborative editing feature (7b40eb9)
  • Add note to use registry images in readme (05528e4)
  • Add warning to update pinnings regularly (5b40fbc)

v0.6.0 (2021-07-12)

Feature

  • Add flopy to default packages (e92819b)
  • Add pyvizcomm for Holoviews/Jupyter Lab 3.0 compatibility (7a7eacf)
  • Add datashader to worker_env (ee8a49a)
  • Add package adjust_text (00bbfe8)
  • Remove firefox, geckodriver and selenium dependencies, as they are not reliable enough (fd18aae)
  • Add pyepsg package to worker_env (2e2ea2f)
  • Update Dockerfile to JupyterLab 3.0 compatibility (65615aa)

Fix

  • Incompatible geoviews package for latest holoviews release (5baa575)
  • Move config to ServerApp transition (fbd83fe)
  • Remove nodejs not needed anymore for Jupyter Lab 3.0 (a6008a3)
  • /home/alex reference to notebooks in compose; update readme (97f3525)
  • Do not use nbextensions install in jupyterlab 3.0 (0edd466)
  • Use commented default values in .env.example (8ea4401)
  • Ipywidgets not yet released (96ac9ba)
  • Environment_default.yml ipywidgets pinning (89c2f1e)

Documentation

  • Add warning to update pinnings regularly (5b40fbc)
  • Add list of packages and links to documentations to readme (2229554)
  • Update Readme.md with branch shuffle (b261af9)
  • Fix link to lbsn-ctl (0494fad)
  • Add master-stable branch note (5add915)
  • Add linebreaks to Readme (34756cd)

See Also