# create a Docker Machine-controlled VirtualBox VM
bin/vbox.sh mymachine

# activate the docker machine
eval "$(docker-machine env mymachine)"

# build the notebook image on the machine
notebook/build.sh

# bring up the notebook container
notebook/up.sh

To stop and remove the container:

notebook/down.sh

FAQ

How do I specify which docker-stack notebook image to deploy?

You can customize the docker-stack notebook image to deploy by modifying the notebook/Dockerfile. For example, you can build and deploy a jupyter/all-spark-notebook by modifying the Dockerfile like so:

FROM jupyter/all-spark-notebook:55d5ca6be183
...

Once you modify the Dockerfile, don't forget to rebuild the image.

# activate the docker machine
eval "$(docker-machine env mymachine)"

notebook/build.sh

Can I run multiple notebook containers on the same VM?

Yes. Set environment variables to specify unique names and ports when running the up.sh command.

NAME=my-notebook PORT=9000 notebook/up.sh
NAME=your-notebook PORT=9001 notebook/up.sh

To stop and remove the containers:

NAME=my-notebook notebook/down.sh
NAME=your-notebook notebook/down.sh

Where are my notebooks stored?

The up.sh creates a Docker volume named after the notebook container with a -work suffix, e.g., my-notebook-work.

Yes. Set the WORK_VOLUME environment variable to the same value for each notebook.

NAME=my-notebook PORT=9000 WORK_VOLUME=our-work notebook/up.sh
NAME=your-notebook PORT=9001 WORK_VOLUME=our-work notebook/up.sh

How do I run over HTTPS?

To run the notebook server with a self-signed certificate, pass the --secure option to the up.sh script. You must also provide a password, which will be used to secure the notebook server. You can specify the password by setting the PASSWORD environment variable, or by passing it to the up.sh script.

PASSWORD=a_secret notebook/up.sh --secure

# or
notebook/up.sh --secure --password a_secret

Can I use Let's Encrypt certificate chains?

Sure. If you want to secure access to publicly addressable notebook containers, you can generate a free certificate using the Let's Encrypt service.

This example includes the bin/letsencrypt.sh script, which runs the letsencrypt client to create a full-chain certificate and private key, and stores them in a Docker volume. Note: The script hard codes several letsencrypt options, one of which automatically agrees to the Let's Encrypt Terms of Service.

The following command will create a certificate chain and store it in a Docker volume named mydomain-secrets.

FQDN=host.mydomain.com EMAIL=myemail@somewhere.com \
  SECRETS_VOLUME=mydomain-secrets \
  bin/letsencrypt.sh

Now run up.sh with the --letsencrypt option. You must also provide the name of the secrets volume and a password.

PASSWORD=a_secret SECRETS_VOLUME=mydomain-secrets notebook/up.sh --letsencrypt

# or
notebook/up.sh --letsencrypt --password a_secret --secrets mydomain-secrets

Be aware that Let's Encrypt has a pretty low rate limit per domain at the moment. You can avoid exhausting your limit by testing against the Let's Encrypt staging servers. To hit their staging servers, set the environment variable CERT_SERVER=--staging.

FQDN=host.mydomain.com EMAIL=myemail@somewhere.com \
  CERT_SERVER=--staging \
  bin/letsencrypt.sh

Also, be aware that Let's Encrypt certificates are short lived (90 days). If you need them for a longer period of time, you'll need to manually setup a cron job to run the renewal steps. (You can reuse the command above.)

Can I deploy to any Docker Machine host?

Yes, you should be able to deploy to any Docker Machine-controlled host. To make it easier to get up and running, this example includes scripts to provision Docker Machines to VirtualBox and IBM SoftLayer, but more scripts are welcome!

To create a Docker machine using a VirtualBox VM on local desktop:

bin/vbox.sh mymachine

To create a Docker machine using a virtual device on IBM SoftLayer:

export SOFTLAYER_USER=my_softlayer_username
export SOFTLAYER_API_KEY=my_softlayer_api_key
export SOFTLAYER_DOMAIN=my.domain

# Create virtual device
bin/softlayer.sh myhost

# Add DNS entry (SoftLayer DNS zone must exist for SOFTLAYER_DOMAIN)
bin/sl-dns.sh myhost

Troubleshooting

Unable to connect to VirtualBox VM on Mac OS X when using Cisco VPN client

The Cisco VPN client blocks access to IP addresses that it does not know about, and may block access to a new VM if it is created while the Cisco VPN client is running.

Stop Cisco VPN client. (It does not allow modifications to route table).
Run ifconfig to list vboxnet virtual network devices.
Run sudo route -nv add -net 192.168.99 -interface vboxnetX, where X is the number of the virtual device assigned to the VirtualBox VM.
Start Cisco VPN client.

README.md

Docker Compose example

Prerequisites

Quickstart

FAQ