Configuration¶

The following parameter can be set through editing the .env file:

Carto-Lab Docker version tag¶

The Carto-Lab Docker version tag to use e.g. TAG=v0.12.3; defaults to:

TAG=latest

Note

It is always recommeneded to use an explicit version tag, e.g. TAG=v0.16.3. In this case, you can go back to the Carto-Lab Docker version that was used to run specific notebooks.

After changing the version tag, use docker compose pull to update the docker container.

Docker container name¶

The Docker container name, defaults to:

CONTAINER_NAME=lbsn-jupyterlab

Docker network name¶

The Docker network to use, defaults to:

NETWORK_NAME=lbsn-network

Postgres password¶

To access lbsn postgres db, provide a password, which will be made available inside the container, so you can access this from within your notebooks:

POSTGRES_PASSWORD=eX4mP13p455w0Rd

Static Jupyter password¶

Optionally provide a static password to access jupyter lab

JUPYTER_PASSWORD=eX4mP13p455w0Rd

Adjust the startup folder for notebooks¶

Adjust the startup folder in jupyter lab this folder will be available through a bind-mount. Default:

JUPYTER_NOTEBOOKS=${HOME}/notebooks

Jupyter Web Port¶

Adjust the web port under which JupyterLab can be reached. Default:

JUPYTER_WEBPORT=8888

Jupyter Web URL¶

Adjust the web url under which JupyterLab can be reached. e.g.: https://jupyterlab.example.org

Default:

JUPYTER_WEBURL=http://localhost/

Override path to environment.yml¶

Optionally adjust path to environment.yml, e.g. to create a custom env with other packages, e.g.

ENVIRONMENT_FILE=envs/environment_custom.yml

Default:

ENVIRONMENT_FILE=environment_default.yml

Override worker environment name¶

This is the name of the default Kernel environment that can be selected in Jupyter.

Default:

WORKER_ENV_NAME=worker_env

Link persistent conda environments¶

In order to allow other persistent environments to be used within the Jupyter lab container, adjust the folder to link persistent conda environments. This folder will be available through a bind-mount

CONDA_ENVS=${HOME}/envs

Add Mapnik fonts folder¶

If using the Mapnik-Docker tag add a folder to link external fonts for mapnik

MAPNIK_FONTS=/usr/share/fonts

Define compose file to use¶

Define the compose file to use, default is docker-compose.yml. E.g. to start the Mapnik version by default:

COMPOSE_FILE=docker-compose.mapnik.yml

Enable collaboration support¶

Setting COLLABORATIVE=true will start the Jupyter server with the --collaborative flag, which activates live collaboration feature.

This also requires that DISABLE_JUPYTEXT=true is set, as these extensions are incompatible.

COLLABORATIVE=true

Live collaboration has been successfully tested starting with Carto-Lab Docker 24.1.

The default is false. However, the extension is still installed and activated. If you want to explicitly deactivate the live collaboration extension, see DISABLE_JUPYTER-COLLABORATION.

Disable live collaboration extension¶

To explicitly disable the live collaboration extension, set:

DISABLE_JUPYTER-COLLABORATION=true

Note

This also requires not setting COLLABORATIVE=true, as the --collaborative flag does not work with the collaboration extension disabled.

Disable jupytext extension¶

DISABLE_JUPYTEXT=true

Note

At the moment, disabling jupytext means that the extension will be uninstalled on runtime using conda. In our tests, simply disabling jupytext was not enough to solve the conflicts with the live collaboration extension. This means that setting DISABLE_JUPYTEXT=true can increase the startup time of Carto-Lab Docker.

Disable jupyterlab-git extension¶

DISABLE_JUPYTERLAB_GIT=true

Generate random token¶

To generate random token on startup, in addition to the user password, set:

GENERATE_TOKEN=true

The token is exported as TOKEN variable and available with echo $TOKEN in the server.

For signing into Jupyter Lab, you can then either use the token or the password.

Set Autoshutdown timeout¶

The default for Carto-Lab Docker is to shutdown automatically after 30 Minutes, if no notebook kernels are running.

This can be adjusted with the following:

JUPYTER_AUTOSHUTDOWN_TIMEOUT=1800

Note

To disable auto-shutdown, set JUPYTER_AUTOSHUTDOWN_TIMEOUT=0.