This folder contains files and sub-folders that demonstrate how to run docker-stack notebook containers using Docker Compose on a Docker Machine-controlled host.
This example demonstrate how to deploy docker-stack notebook containers to any Docker Machine-controlled host using Docker Compose.
@@ -8,59 +8,114 @@ This folder contains files and sub-folders that demonstrate how to run docker-st
See the [installation instructions](https://docs.docker.com/engine/installation/) for your environment.
## Provision Docker machines
## Quickstart
### Provision a VirtualBox VM on local desktop
Build and run a `jupyter/minimal-notebook` container on a VirtualBox VM on local desktop.
```
# create a Docker Machine-controlled VirtualBox VM
bin/vbox.sh mymachine
```
### Provision a virtual device on IBM SoftLayer
# 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
```
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
To stop and remove the container:
# Add DNS entry (SoftLayer DNS zone must exist for SOFTLAYER_DOMAIN)
bin/sl-dns.sh myhost
```
notebook/down.sh
```
## FAQ
### How do I specify which docker-stack notebook image to deploy?
## Deploy stand-alone Jupyter Notebook
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:
Build and run a `jupyter/minimal-notebook` container on an existing Docker machine.
```
FROM jupyter/all-spark-notebook:55d5ca6be183
...
```
Once you modify the Dockerfile, don't forget to rebuild the image.
```
# activate docker machine
# activate the docker machine
eval "$(docker-machine env mymachine)"
# build notebook image on the machine
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.
# bring up notebook container
notebook/up.sh
```
NAME=my-notebook PORT=9000 notebook/up.sh
NAME=your-notebook PORT=9001 notebook/up.sh
```
To stop and remove the container:
To stop and remove the containers:
```
notebook/down.sh
NAME=my-notebook notebook/down.sh
NAME=your-notebook notebook/down.sh
```
See [notebook README](notebook/README.md) for more details.
### 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`.
## Let's Encrypt
If you want to secure access to publicly addressable notebook containers, you can generate a free certificate using the [Let's Encrypt](https://letsencrypt.org) service.
### Can multiple notebook containers share the same notebook volume?
The following command creates a Docker volume, runs the `letsencrypt` client to create a full-chain certificate and private key, and stores them in the volume. Note: The script uses several `letsencrypt` options, one of which automatically agrees to the Let's Encrypt Terms of Service.
Yes. Set the `WORK_VOLUME` environment variable to the same value for each notebook.
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](https://letsencrypt.org) 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`.
Be aware that Let's Encrypt has a pretty [low rate limit per domain](https://community.letsencrypt.org/t/public-beta-rate-limits/4772/3) 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`.
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.
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
```
To use a real certificate from Let's Encrypt, first run the `bin/letsencrypt.sh` script to create the certificate chain and store it in a Docker volume.
