lemarsu/nb

nb-docker

Simple image to deploy https://github.com/xwmx/nb in docker environment.

• Features
  • Webhook server
  • Periodic sync server
• Non features
  • Restrict access
• Build image
  • With docker
  • With docker compose
• Usage
  • With docker
  • With docker compose
• Configuration
  • nb environment variables
  • nb-docker environment variables
  • Other environment variables
• Caveats

Features

This docker image allows you to run https://github.com/xwmx/nb server in docker environment. To allow better update, to features was added.

Webhook server

You can configure your git server to execute a webhook to allow nb-docker to update nb notebooks. To enable it, set the NBDOCKER_WEBHOOK_PASSWORD environment variable with the password required for your webhook. This password will have to be given on the X-Authentication header, as is.

Here is an example of curl command to call the webhook. For this example to work, the NBDOCKER_WEBHOOK_PASSWORD must be set to my-secret-password. Please use a different password for production environment.

bash
curl -d '{}' -H "x-authentication: my-secret-password" localhost:3000/webhook

:warning: The NBDOCKER_WEBHOOK_PASSWORD only protects the /webhook path for the webhook server. It will not protect anybody accessing your notebooks. Protecting your notebooks must be done by a reverse proxy.

More info in configuration section.

Periodic sync server

If you can't use the webhook to sync your notebooks, you can enable the periodic sync server by setting the variable NBDOCKER_PERIODIC_SYNC_INTERVAL_MIN to the number of minutes you want the sync to occur.

If the variable is not set or set to 0, the feature is disabled.

More info in configuration section.

Non features

Restrict access

This image doesn't try to restrict access to your nb notebooks. This must be done by a reverse proxy. Setting up a reverse proxy is (yet ?) out of scope of this documentation.

If you set up a reverse proxy with access restriction and you are using the webhook server, you need to allow POST requests on /webhook path. The webhook configuration will handle authentication on its own.

Build image

With docker

bash
# If required and wanted, enable buildkit
export DOCKER_BUILDKIT=1

docker build -t lemarsu/nb .

With docker compose

Using ./docker-compose.yaml inside the repository.

bash
docker compose build

Usage

When running, nb-docker expect to find notebooks in /nb/nb folder.

:warning: The folder must at least contain one notebook with at least one note, otherwise nb will exit automatically.

With docker

bash
docker run -v ~/.nb:/nb/nb --rm -p 0.0.0.0:6789:6789/tcp -e NB_SERVER_BIND_HOST=0.0.0.0 -it lemarsu/nb:latest b --daemon

With docker compose

Using ./docker-compose.yaml inside the repository.

bash
docker compose up --build

--build is not needed if the image has been build in the previous chapter.

Configuration

All nb-docker configuration is done by setting environment variables

nb environment variables

All nb configuration variables are followed as is. But if they are not defined, then some defaults are overridden as presented in the following table.

nb-docker environment variables

The following variables allow to configure nb-docker behaviour.

* These variables are required if any of this condition is true :

• NB_AUTO_SYNC is unset or set to 1
• NBDOCKER_PERIODIC_SYNC_INTERVAL_MIN is set to something other than 0.

If NBDOCKER_GIT_CREDENTIALS_USERNAME and NBDOCKER_GIT_CREDENTIALS_PASSWORD are set, git will be configured to use those credentials.

Other environment variables

This debian based container allows the following built-in configuration variables.

Caveats

• For now, only one set of user/password git credentials can be set. If your notebooks are hosted on different servers that requires different credentials, it is not (yet?) possible to sync them all with nb-docker.