diff --git a/examples/docker-compose/README.md b/examples/docker-compose/README.md index 38893a39..932e13aa 100644 --- a/examples/docker-compose/README.md +++ b/examples/docker-compose/README.md @@ -1,6 +1,6 @@ -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. -## Pre-requisites +## Prerequisites * [Docker Engine](https://docs.docker.com/engine/) 1.10.0+ * [Docker Machine](https://docs.docker.com/machine/) 0.6.0+ @@ -8,15 +8,137 @@ 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 + +# 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`. + + +### Can multiple notebook containers share the same notebook volume? + +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](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`. + +``` +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](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`. + +``` +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 ``` -### Provision a virtual device on IBM SoftLayer +To create a Docker machine using a virtual device on IBM SoftLayer: ``` export SOFTLAYER_USER=my_softlayer_username @@ -30,48 +152,6 @@ bin/softlayer.sh myhost bin/sl-dns.sh myhost ``` -## Deploy stand-alone Jupyter Notebook - -Build and run a `jupyter/minimal-notebook` container on an existing Docker machine. - -``` -# activate docker machine -eval "$(docker-machine env mymachine)" - -# build notebook image on the machine -notebook/build.sh - -# bring up notebook container -notebook/up.sh -``` - -To stop and remove the container: - -``` -notebook/down.sh -``` - -See [notebook README](notebook/README.md) for more details. - -## 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. - -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. - -``` -FQDN=host.mydomain.com EMAIL=myemail@somewhere.com bin/letsencrypt.sh -``` - -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`. - -``` -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.) ## Troubleshooting diff --git a/examples/docker-compose/notebook/README.md b/examples/docker-compose/notebook/README.md index 5150992d..e69de29b 100644 --- a/examples/docker-compose/notebook/README.md +++ b/examples/docker-compose/notebook/README.md @@ -1,96 +0,0 @@ -Run a docker-stack notebook container using Docker Compose on a Docker Machine-controlled host. - -## Pre-requisites - -* [Docker Engine](https://docs.docker.com/engine/) 1.10.0+ -* [Docker Machine](https://docs.docker.com/machine/) 0.6.0+ -* [Docker Compose](https://docs.docker.com/compose/) 1.6.0+ - -See the [installation instructions](https://docs.docker.com/engine/installation/) for your environment. - -## Quickstart - -Here's how to build and run a `jupyter/minimal-notebook` container on an existing Docker machine. - -``` -# activate docker machine -eval "$(docker-machine env mymachine)" - -# build notebook image on the machine -notebook/build.sh - -# bring up notebook container -notebook/up.sh -``` - -To stop and remove the container: - -``` -notebook/down.sh -``` - -## FAQ - -### 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`. - - -### Can multiple notebook containers share the same notebook volume? - -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 -``` - -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. - -``` -FQDN=host.mydomain.com EMAIL=myemail@somewhere.com bin/letsencrypt.sh -``` - -The following command will store the certificate chain 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 -```