hazza/docker-stacks
1
0
Fork 0
mirror of https://github.com/jupyter/docker-stacks.git synced 2025-10-16 22:42:57 +00:00
Code Issues Packages Projects Releases Wiki Activity

Update docker-compose example README.

Browse Source 
(c) Copyright IBM Corp. 2016
This commit is contained in:
Justin Tyberg
2016-02-16 11:40:58 -05:00
parent 4a4aabecd9
commit 4da0bf5471
2 changed files with 127 additions and 143 deletions
Download Patch File Download Diff File Expand all files Collapse all files

174
examples/docker-compose/README.md
View File

@@ -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

96
examples/docker-compose/notebook/README.md
View File

@@ -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
```