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

Merge pull request #1591 from mathbunnyru/asalikhov/cleanup_docs

Browse Source 
Cleanup docs
This commit is contained in:
Ayaz Salikhov
2022-02-02 16:20:40 +03:00
committed by GitHub
parent f27d615c50 9fa1a586fc
commit c7515d0394
14 changed files with 161 additions and 147 deletions
Download Patch File Download Diff File Expand all files Collapse all files

1
base-notebook/Dockerfile
View File

@@ -112,6 +112,7 @@ RUN set -x && \
conda config --system --set auto_update_conda false && \
conda config --system --set show_channel_urls true && \
if [[ "${PYTHON_VERSION}" != "default" ]]; then mamba install --quiet --yes python="${PYTHON_VERSION}"; fi && \
# Pin major.minor version of python
mamba list python | grep '^python ' | tr -s ' ' | cut -d ' ' -f 1,2 >> "${CONDA_DIR}/conda-meta/pinned" && \
# Using conda to update all packages: https://github.com/mamba-org/mamba/issues/1092
conda update --all --quiet --yes && \

5
docs/contributing/features.md
View File

@@ -37,8 +37,9 @@ Roughly speaking, we evaluate new features based on the following criteria:
If there's agreement that the feature belongs in one or more of the core stacks:
1. Implement the feature in a local clone of the `jupyter/docker-stacks` project.
2. Please build the image locally before submitting a pull request
Building the image locally shortens the debugging cycle by taking some load off GitHub Actions, which graciously provide free build services for open source projects like this one.
2. Please, build the image locally before submitting a pull request.
It shortens the debugging cycle by taking some load off GitHub Actions,
which graciously provides free build services for open source projects like this one.
If you use `make`, call:
```bash

10
docs/contributing/lint.md
View File

@@ -13,9 +13,9 @@ This can be achieved by using the generic task used to install all Python develo
```sh
# Install all development dependencies for the project
$ make dev-env
make dev-env
# It can also be installed directly
$ pip install pre-commit
pip install pre-commit
```
Then the git hooks scripts configured for the project in `.pre-commit-config.yaml` need to be installed in the local git repository.
@@ -29,7 +29,9 @@ make pre-commit-install
Now pre-commit (and so configured hooks) will run automatically on `git commit` on each changed file.
However it is also possible to trigger it against all files.
- Note: Hadolint pre-commit uses docker to run, so docker should be running while running this command.
```{note}
Hadolint pre-commit uses docker to run, so docker should be running while running this command.
```
```sh
make pre-commit-all
@@ -37,7 +39,7 @@ make pre-commit-all
## Image Lint
To comply with [Docker best practices][dbp], we are using the [Hadolint][hadolint] tool to analyse each `Dockerfile` .
To comply with [Docker best practices][dbp], we are using the [Hadolint][hadolint] tool to analyse each `Dockerfile`.
### Ignoring Rules

37
docs/contributing/packages.md
View File

@@ -1,41 +1,22 @@
# Package Updates
We actively seek pull requests which update packages already included in the project Dockerfiles.
This is a great way for first-time contributors to participate in developing the Jupyter Docker
Stacks.
As a general rule, we do not pin package versions in our `Dockerfile`s.
The dependencies resolution is a difficult thing to do.
This means that packages might have old versions.
Images are rebuilt weekly, so usually, packages receive updates quite frequently.
Please follow the process below to update a package version:
```{note}
We pin major.minor version of python, so this will stay the same even after invoking the `mamba update` command.
```
1. Locate the Dockerfile containing the library you wish to update (e.g.,
[base-notebook/Dockerfile](https://github.com/jupyter/docker-stacks/blob/master/base-notebook/Dockerfile),
[scipy-notebook/Dockerfile](https://github.com/jupyter/docker-stacks/blob/master/scipy-notebook/Dockerfile))
2. Adjust the version number for the package.
We prefer to pin the major and minor version number of packages so as to minimize rebuild side-effects when users submit pull requests (PRs).
For example, you'll find the Jupyter Notebook package, `notebook`, installed using conda with
`notebook=5.4.*`.
3. Please build the image locally before submitting a pull request.
Building the image locally shortens the debugging cycle by taking some load off GitHub Actions, which graciously provide free build services for open source projects like this one.
If you use `make`, call:
```bash
make build/somestack-notebook
```
4. [Submit a pull request](https://github.com/PointCloudLibrary/pcl/wiki/A-step-by-step-guide-on-preparing-and-submitting-a-pull-request)
(PR) with your changes.
5. Watch for GitHub to report a build success or failure for your PR on GitHub.
6. Discuss changes with the maintainers and address any build issues.
Version conflicts are the most common problem.
You may need to upgrade additional packages to fix build failures.
## Notes
## Outdated packages
In order to help identifying packages that can be updated you can use the following helper tool.
It will list all the packages installed in the `Dockerfile` that can be updated -- dependencies are
filtered to focus only on requested packages.
```bash
$ make check-outdated/base-notebook
make check-outdated/base-notebook
# INFO test_outdated:test_outdated.py:80 3/8 (38%) packages could be updated
# INFO test_outdated:test_outdated.py:82

11
docs/contributing/stacks.md
View File

@@ -3,9 +3,10 @@
We love to see the community create and share new Jupyter Docker images.
We've put together a [cookiecutter project](https://github.com/jupyter/cookiecutter-docker-stacks)
and the documentation below to help you get started defining, building, and sharing your Jupyter environments in Docker.
Following these steps will:
1. Setup a project on GitHub containing a Dockerfile based on either the `jupyter/base-notebook` or `jupyter/minimal-notebook` image.
1. Setup a project on GitHub containing a Dockerfile based on any of the images we provide.
2. Configure GitHub Actions to build and test your image when users submit pull requests to your repository.
3. Configure Docker Hub to build and host your images for others to use.
4. Update the [list of community stacks](../using/selecting.html#community-stacks) in this documentation to include your image.
@@ -62,7 +63,7 @@ git init
git add .
git commit -m 'Seed repo'
git remote add origin <url from github>
git push -u origin master
git push -u origin main
```
## Configuring GitHub actions
@@ -118,7 +119,11 @@ you merge a GitHub pull request to the master branch of your project.
11. Enter a meaningful name for your token and click on **Create**
![DockerHub - New Access Token page with the name field set to "my-jupyter-docker-token"](../_static/docker-org-create-token.png)
12. Copy the personal access token displayed on the next screen.
**Note that you will not be able to see it again after you close the pop-up window**.
```{note}
you will not be able to see it again after you close the pop-up window**.
```
13. Head back to your GitHub repository and click on the **Settings tab**.
![GitHub page with the the "Setting" tab active and a rectangle highlighting the "New repository secret" button in the UI](../_static/github-create-secrets.png)
14. Click on the **Secrets** section and then on the **New repository secret** button on the top right corner (see image above).

10
docs/contributing/tests.md
View File

@@ -5,8 +5,7 @@ of the Docker images.
## How the Tests Work
GitHub executes `make build-test-all` against pull requests submitted to the `jupyter/docker-stacks`
repository.
GitHub Action executes `make build-test-all` against pull requests submitted to the `jupyter/docker-stacks` repository.
This `make` command builds every docker image.
After building each image, the `make` command executes `pytest` to run both image-specific tests like those in
[base-notebook/test/](https://github.com/jupyter/docker-stacks/tree/master/base-notebook/test) and
@@ -14,6 +13,13 @@ common tests defined in [test/](https://github.com/jupyter/docker-stacks/tree/ma
Both kinds of tests make use of global [pytest fixtures](https://docs.pytest.org/en/latest/reference/fixtures.html)
defined in the [conftest.py](https://github.com/jupyter/docker-stacks/blob/master/conftest.py) file at the root of the projects.
## Unit tests
If you want to run a python script in one of our images, you could add a unit test.
You can do this by creating a `<somestack>-notebook/test/units/` directory, if it doesn't already exist and put your file there.
These file will run automatically when tests are run.
You could see an example for tensorflow package [here](https://github.com/jupyter/docker-stacks/blob/HEAD/tensorflow-notebook/test/units/unit_tensorflow.py).
## Contributing New Tests
Please follow the process below to add new tests:

14
docs/maintaining/tasks.md
View File

@@ -14,13 +14,19 @@ To build new images and publish them to the Docker Hub registry, do the followin
## Updating the Ubuntu Base Image
When there's a security fix in the Ubuntu base image or after some time passes, it's a good idea to update the pinned SHA in the
[jupyter/base-notebook Dockerfile](https://github.com/jupyter/docker-stacks/blob/master/base-notebook/Dockerfile).
Submit it as a regular PR and go through the build process.
Expect the build to take a while to complete: every image layer will rebuild.
`minimal-notebook` is based on the Latest LTS Ubuntu docker image.
Other images are directly or indirectly inherited from `minimal-notebook`.
We rebuild our images automatically each week, which means they receive the updates quite frequently.
When there's a security fix in the Ubuntu base image, it's a good idea to manually trigger images rebuild [from the GitHub actions workflow UI](https://github.com/jupyter/docker-stacks/actions/workflows/docker.yml).
Pushing `Run Workflow` button will trigger this process.
## Adding a New Core Image to Docker Hub
```{note}
In general, we do not add new core images and ask contributors to either create a [recipe](../using/recipes.md) or [community stack](../using/stacks.md).
```
When there's a new stack definition, do the following before merging the PR with the new stack:
1. Ensure the PR includes an update to the stack overview diagram

17
docs/using/common.md
View File

@@ -72,16 +72,19 @@ You do so by passing arguments to the `docker run` command.
- `--user 5000 --group-add users` - Launches the container with a specific user ID and adds that user to the `users` group so that it can modify files in the default home directory and `/opt/conda`.
You can use these arguments as alternatives to setting `${NB_UID}` and `${NB_GID}`.
## Permision-specific configurations
## Permission-specific configurations
- `-e NB_UMASK=<umask>` - Configures Jupyter to use a different `umask` value from default, i.e. `022`.
For example, if setting `umask` to `002`, new files will be readable and writable by group members instead of the owner only.
[Check this Wikipedia article](https://en.wikipedia.org/wiki/Umask) for an in-depth description of `umask` and suitable values for multiple needs.
While the default `umask` value should be sufficient for most use cases, you can set the `NB_UMASK` value to fit your requirements.
_Note that `NB_UMASK` when set only applies to the Jupyter process itself -
```{note}
`NB_UMASK` when set only applies to the Jupyter process itself -
you cannot use it to set a `umask` for additional files created during run-hooks.
For example, via `pip` or `conda`.
If you need to set a `umask` for these, you must set the `umask` value for each command._
```
- `-e CHOWN_HOME=yes` - Instructs the startup script to change the `${NB_USER}` home directory owner and group to the current value of `${NB_UID}` and `${NB_GID}`.
This change will take effect even if the user home directory is mounted from the host using `-v` as described below.
@@ -135,7 +138,7 @@ For example, to mount a host folder containing a `notebook.key` and `notebook.cr
docker run -d -p 8888:8888 \
-v /some/host/folder:/etc/ssl/notebook \
jupyter/base-notebook start-notebook.sh \
--NotebookApp.keyfile=/etc/ssl/notebook/notebook.key
--NotebookApp.keyfile=/etc/ssl/notebook/notebook.key \
--NotebookApp.certfile=/etc/ssl/notebook/notebook.crt
```
@@ -187,13 +190,13 @@ Example:
# Run Jupyter Notebook on Jupyter Server
docker run -it --rm -p 8888:8888 \
-e DOCKER_STACKS_JUPYTER_CMD=notebook \
jupyter/base-notebook
jupyter/base-notebook
# Executing the command: jupyter notebook ...
# Run Jupyter Notebook classic
docker run -it --rm -p 8888:8888 \
-e DOCKER_STACKS_JUPYTER_CMD=nbclassic \
jupyter/base-notebook
jupyter/base-notebook
# Executing the command: jupyter nbclassic ...
```
@@ -207,10 +210,10 @@ For example, to run the text-based `ipython` console in a container, do the foll
docker run -it --rm jupyter/base-notebook start.sh ipython
```
Or, to run JupyterLab instead of the classic notebook, run the following:
Or, to run Jupyter Notebook classic instead of JupyterLab, run the following:
```bash
docker run -it --rm -p 8888:8888 jupyter/base-notebook start.sh jupyter lab
docker run -it --rm -p 8888:8888 jupyter/base-notebook start.sh jupyter notebook
```
This script is handy when you derive a new Dockerfile from this image and install additional Jupyter applications with subcommands like `jupyter console`, `jupyter kernelgateway`, etc.

4
docs/using/recipes.md
View File

@@ -268,9 +268,7 @@ Enabling manpages in the base Ubuntu layer prevents this container bloat.
To achieve this, use the previous `Dockerfile` with the original ubuntu image (`ubuntu:focal`) as your base container:
```dockerfile
# Ubuntu 20.04 (focal) from 2020-04-23
# https://github.com/docker-library/official-images/commit/4475094895093bcc29055409494cce1e11b52f94
ARG BASE_CONTAINER=ubuntu:focal-20200423@sha256:238e696992ba9913d24cfc3727034985abd136e08ee3067982401acdc30cbf3f
ARG BASE_CONTAINER=ubuntu:focal
```
For Ubuntu 18.04 (bionic) and earlier, you may also require to a workaround for a mandb bug, which was fixed in mandb >= 2.8.6.1:

94
docs/using/running.md
View File

@@ -18,42 +18,42 @@ It then starts a container running a Jupyter Notebook server and exposes the ser
The server logs appear in the terminal and include a URL to the notebook server.
```bash
$ docker run -p 8888:8888 jupyter/scipy-notebook:b418b67c225b
docker run -p 8888:8888 jupyter/scipy-notebook:b418b67c225b
Executing the command: jupyter notebook
[I 15:33:00.567 NotebookApp] Writing notebook server cookie secret to /home/jovyan/.local/share/jupyter/runtime/notebook_cookie_secret
[W 15:33:01.084 NotebookApp] WARNING: The notebook server is listening on all IP addresses and not using encryption. This is not recommended.
[I 15:33:01.150 NotebookApp] JupyterLab alpha preview extension loaded from /opt/conda/lib/python3.6/site-packages/jupyterlab
[I 15:33:01.150 NotebookApp] JupyterLab application directory is /opt/conda/share/jupyter/lab
[I 15:33:01.155 NotebookApp] Serving notebooks from local directory: /home/jovyan
[I 15:33:01.156 NotebookApp] 0 active kernels
[I 15:33:01.156 NotebookApp] The Jupyter Notebook is running at:
[I 15:33:01.157 NotebookApp] http://[all ip addresses on your system]:8888/?token=112bb073331f1460b73768c76dffb2f87ac1d4ca7870d46a
[I 15:33:01.157 NotebookApp] Use Control-C to stop this server and shut down all kernels (twice to skip confirmation).
[C 15:33:01.160 NotebookApp]
# Executing the command: jupyter notebook
# [I 15:33:00.567 NotebookApp] Writing notebook server cookie secret to /home/jovyan/.local/share/jupyter/runtime/notebook_cookie_secret
# [W 15:33:01.084 NotebookApp] WARNING: The notebook server is listening on all IP addresses and not using encryption. This is not recommended.
# [I 15:33:01.150 NotebookApp] JupyterLab alpha preview extension loaded from /opt/conda/lib/python3.6/site-packages/jupyterlab
# [I 15:33:01.150 NotebookApp] JupyterLab application directory is /opt/conda/share/jupyter/lab
# [I 15:33:01.155 NotebookApp] Serving notebooks from local directory: /home/jovyan
# [I 15:33:01.156 NotebookApp] 0 active kernels
# [I 15:33:01.156 NotebookApp] The Jupyter Notebook is running at:
# [I 15:33:01.157 NotebookApp] http://[all ip addresses on your system]:8888/?token=112bb073331f1460b73768c76dffb2f87ac1d4ca7870d46a
# [I 15:33:01.157 NotebookApp] Use Control-C to stop this server and shut down all kernels (twice to skip confirmation).
# [C 15:33:01.160 NotebookApp]
Copy/paste this URL into your browser when you connect for the first time,
to login with a token:
http://localhost:8888/?token=112bb073331f1460b73768c76dffb2f87ac1d4ca7870d46a
# Copy/paste this URL into your browser when you connect for the first time,
# to login with a token:
# http://localhost:8888/?token=112bb073331f1460b73768c76dffb2f87ac1d4ca7870d46a
```
Pressing `Ctrl-C` shuts down the notebook server but leaves the container intact on disk for later restart or permanent deletion using commands like the following:
```bash
# list containers
$ docker ps -a
CONTAINER ID IMAGE COMMAND CREATED STATUS PORTS NAMES
d67fe77f1a84 jupyter/base-notebook "tini -- start-noteb…" 44 seconds ago Exited (0) 39 seconds ago cocky_mirzakhani
docker ps -a
# CONTAINER ID IMAGE COMMAND CREATED STATUS PORTS NAMES
# d67fe77f1a84 jupyter/base-notebook "tini -- start-noteb…" 44 seconds ago Exited (0) 39 seconds ago cocky_mirzakhani
# start the stopped container
$ docker start -a d67fe77f1a84
Executing the command: jupyter notebook
[W 16:45:02.020 NotebookApp] WARNING: The notebook server is listening on all IP addresses and not using encryption. This is not recommended.
...
docker start -a d67fe77f1a84
# Executing the command: jupyter notebook
# [W 16:45:02.020 NotebookApp] WARNING: The notebook server is listening on all IP addresses and not using encryption. This is not recommended.
# ...
# remove the stopped container
$ docker rm d67fe77f1a84
d67fe77f1a84
docker rm d67fe77f1a84
# d67fe77f1a84
```
**Example 2** This command pulls the `jupyter/r-notebook` image tagged `b418b67c225b` from Docker Hub if it is not already present on the local host.
@@ -61,23 +61,23 @@ It then starts a container running a Jupyter Notebook server and exposes the ser
The server logs appear in the terminal and include a URL to the notebook server, but with the internal container port (8888) instead of the the correct host port (10000).
```bash
$ docker run --rm -p 10000:8888 -v "${PWD}":/home/jovyan/work jupyter/r-notebook:b418b67c225b
docker run --rm -p 10000:8888 -v "${PWD}":/home/jovyan/work jupyter/r-notebook:b418b67c225b
Executing the command: jupyter notebook
[I 19:31:09.573 NotebookApp] Writing notebook server cookie secret to /home/jovyan/.local/share/jupyter/runtime/notebook_cookie_secret
[W 19:31:11.930 NotebookApp] WARNING: The notebook server is listening on all IP addresses and not using encryption. This is not recommended.
[I 19:31:12.085 NotebookApp] JupyterLab alpha preview extension loaded from /opt/conda/lib/python3.6/site-packages/jupyterlab
[I 19:31:12.086 NotebookApp] JupyterLab application directory is /opt/conda/share/jupyter/lab
[I 19:31:12.117 NotebookApp] Serving notebooks from local directory: /home/jovyan
[I 19:31:12.117 NotebookApp] 0 active kernels
[I 19:31:12.118 NotebookApp] The Jupyter Notebook is running at:
[I 19:31:12.119 NotebookApp] http://[all ip addresses on your system]:8888/?token=3b8dce890cb65570fb0d9c4a41ae067f7604873bd604f5ac
[I 19:31:12.120 NotebookApp] Use Control-C to stop this server and shut down all kernels (twice to skip confirmation).
[C 19:31:12.122 NotebookApp]
# Executing the command: jupyter notebook
# [I 19:31:09.573 NotebookApp] Writing notebook server cookie secret to /home/jovyan/.local/share/jupyter/runtime/notebook_cookie_secret
# [W 19:31:11.930 NotebookApp] WARNING: The notebook server is listening on all IP addresses and not using encryption. This is not recommended.
# [I 19:31:12.085 NotebookApp] JupyterLab alpha preview extension loaded from /opt/conda/lib/python3.6/site-packages/jupyterlab
# [I 19:31:12.086 NotebookApp] JupyterLab application directory is /opt/conda/share/jupyter/lab
# [I 19:31:12.117 NotebookApp] Serving notebooks from local directory: /home/jovyan
# [I 19:31:12.117 NotebookApp] 0 active kernels
# [I 19:31:12.118 NotebookApp] The Jupyter Notebook is running at:
# [I 19:31:12.119 NotebookApp] http://[all ip addresses on your system]:8888/?token=3b8dce890cb65570fb0d9c4a41ae067f7604873bd604f5ac
# [I 19:31:12.120 NotebookApp] Use Control-C to stop this server and shut down all kernels (twice to skip confirmation).
# [C 19:31:12.122 NotebookApp]
Copy/paste this URL into your browser when you connect for the first time,
to login with a token:
http://localhost:8888/?token=3b8dce890cb65570fb0d9c4a41ae067f7604873bd604f5ac
# Copy/paste this URL into your browser when you connect for the first time,
# to login with a token:
# http://localhost:8888/?token=3b8dce890cb65570fb0d9c4a41ae067f7604873bd604f5ac
```
Pressing `Ctrl-C` shuts down the notebook server and immediately destroys the Docker container.
@@ -95,14 +95,14 @@ The assigned port and notebook server token are visible using other Docker comma
```bash
# get the random host port assigned to the container port 8888
$ docker port notebook 8888
0.0.0.0:32769
docker port notebook 8888
# 0.0.0.0:32769
# get the notebook token from the logs
$ docker logs --tail 3 notebook
Copy/paste this URL into your browser when you connect for the first time,
to login with a token:
http://localhost:8888/?token=15914ca95f495075c0aa7d0e060f1a78b6d94f70ea373b00
docker logs --tail 3 notebook
# Copy/paste this URL into your browser when you connect for the first time,
# to login with a token:
# http://localhost:8888/?token=15914ca95f495075c0aa7d0e060f1a78b6d94f70ea373b00
```
Together, the URL to visit on the host machine to access the server in this case is <http://localhost:32769?token=15914ca95f495075c0aa7d0e060f1a78b6d94f70ea373b00>.
@@ -112,11 +112,11 @@ The container runs in the background until stopped and/or removed by additional
```bash
# stop the container
docker stop notebook
notebook
# notebook
# remove the container permanently
docker rm notebook
notebook
# notebook
```
## Using Binder

18
docs/using/specifics.md
View File

@@ -9,7 +9,11 @@ This page provides details about features specific to one or more images.
- `-p 4040:4040` - The `jupyter/pyspark-notebook` and `jupyter/all-spark-notebook` images open
[SparkUI (Spark Monitoring and Instrumentation UI)](https://spark.apache.org/docs/latest/monitoring.html) at default port `4040`,
this option map `4040` port inside docker container to `4040` port on host machine.
Note every new spark context that is created is put onto an incrementing port (ie. 4040, 4041, 4042, etc.), and it might be necessary to open multiple ports.
```{note}
Every new spark context that is created is put onto an incrementing port (ie. 4040, 4041, 4042, etc.), and it might be necessary to open multiple ports.
```
For example: `docker run -d -p 8888:8888 -p 4040:4040 -p 4041:4041 jupyter/pyspark-notebook`.
#### IPython low-level output capture and forward
@@ -162,8 +166,10 @@ Connection to Spark Cluster on **[Standalone Mode](https://spark.apache.org/docs
2. Run the Docker container with `--net=host` in a location that is network addressable by all of
your Spark workers.
(This is a [Spark networking requirement](https://spark.apache.org/docs/latest/cluster-overview.html#components).)
- NOTE: When using `--net=host`, you must also use the flags `--pid=host -e TINI_SUBREAPER=true`.
See <https://github.com/jupyter/docker-stacks/issues/64> for details.
```{note}
When using `--net=host`, you must also use the flags `--pid=host -e TINI_SUBREAPER=true`. See <https://github.com/jupyter/docker-stacks/issues/64> for details._
```
**Note**: In the following examples we are using the Spark master URL `spark://master:7077` that shall be replaced by the URL of the Spark master.
@@ -243,6 +249,10 @@ rdd.sum()
### Define Spark Dependencies
```{note}
This example is given for [Elasticsearch](https://www.elastic.co/guide/en/elasticsearch/hadoop/current/install.html).
```
Spark dependencies can be declared thanks to the `spark.jars.packages` property
(see [Spark Configuration](https://spark.apache.org/docs/latest/configuration.html#runtime-environment) for more information).
@@ -272,8 +282,6 @@ USER ${NB_UID}
Jars will be downloaded dynamically at the creation of the Spark session and stored by default in `${HOME}/.ivy2/jars` (can be changed by setting `spark.jars.ivy`).
_Note: This example is given for [Elasticsearch](https://www.elastic.co/guide/en/elasticsearch/hadoop/current/install.html)._
## Tensorflow
The `jupyter/tensorflow-notebook` image supports the use of

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

@@ -102,14 +102,17 @@ notebook/up.sh --secure --password a_secret
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.
```{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`.
```bash
FQDN=host.mydomain.com EMAIL=myemail@somewhere.com \
SECRETS_VOLUME=mydomain-secrets \
bin/letsencrypt.sh
SECRETS_VOLUME=mydomain-secrets \
bin/letsencrypt.sh
```
Now run `up.sh` with the `--letsencrypt` option.
@@ -128,8 +131,8 @@ To hit their staging servers, set the environment variable `CERT_SERVER=--stagin
```bash
FQDN=host.mydomain.com EMAIL=myemail@somewhere.com \
CERT_SERVER=--staging \
bin/letsencrypt.sh
CERT_SERVER=--staging \
bin/letsencrypt.sh
```
Also, be aware that Let's Encrypt certificates are short lived (90 days).

18
examples/openshift/README.md
View File

@@ -101,9 +101,9 @@ To override the name for the notebook, the image used, and the password, you can
```bash
oc new-app --template jupyter-notebook \
--param APPLICATION_NAME=mynotebook \
--param NOTEBOOK_IMAGE=jupyter/scipy-notebook:latest \
--param NOTEBOOK_PASSWORD=mypassword
--param APPLICATION_NAME=mynotebook \
--param NOTEBOOK_IMAGE=jupyter/scipy-notebook:latest \
--param NOTEBOOK_PASSWORD=mypassword
```
You can deploy any of the Jupyter Project docker-stacks images.
@@ -136,9 +136,9 @@ To add persistent storage run:
```bash
oc set volume dc/mynotebook --add \
--type=pvc --claim-size=1Gi --claim-mode=ReadWriteOnce \
--claim-name mynotebook-data --name data \
--mount-path /home/jovyan
--type=pvc --claim-size=1Gi --claim-mode=ReadWriteOnce \
--claim-name mynotebook-data --name data \
--mount-path /home/jovyan
```
When you have deleted the notebook instance, if using a persistent volume, you will need to delete it in a separate step.
@@ -229,9 +229,9 @@ Then deploy it using the name of the image stream created.
```bash
oc new-app --template jupyter-notebook \
--param APPLICATION_NAME=mynotebook \
--param NOTEBOOK_IMAGE=datascience-notebook \
--param NOTEBOOK_PASSWORD=mypassword
--param APPLICATION_NAME=mynotebook \
--param NOTEBOOK_IMAGE=datascience-notebook \
--param NOTEBOOK_PASSWORD=mypassword
```
Importing an image into OpenShift before deploying it means that when a notebook is started, the image need only be pulled from the internal OpenShift image registry rather than Docker Hub for each deployment.

56
examples/source-to-image/README.md
View File

@@ -31,11 +31,11 @@ As an example of how S2I can be used to create a custom image with a bundled set
```bash
s2i build \
--scripts-url https://raw.githubusercontent.com/jupyter/docker-stacks/master/examples/source-to-image \
--context-dir docs/source/examples/Notebook \
https://github.com/jupyter/notebook \
jupyter/minimal-notebook:latest \
notebook-examples
--scripts-url https://raw.githubusercontent.com/jupyter/docker-stacks/master/examples/source-to-image \
--context-dir docs/source/examples/Notebook \
https://github.com/jupyter/notebook \
jupyter/minimal-notebook:latest \
notebook-examples
```
This example command will pull down the Git repository <https://github.com/jupyter/notebook>
@@ -45,30 +45,30 @@ The base image which the files will be combined with is `jupyter/minimal-noteboo
The resulting image from running the command can be seen by running `docker images` command:
```bash
$ docker images
REPOSITORY TAG IMAGE ID CREATED SIZE
notebook-examples latest f5899ed1241d 2 minutes ago 2.59GB
docker images
# REPOSITORY TAG IMAGE ID CREATED SIZE
# notebook-examples latest f5899ed1241d 2 minutes ago 2.59GB
```
You can now run the image.
```bash
$ docker run --rm -p 8888:8888 notebook-examples
Executing the command: jupyter notebook
[I 01:14:50.532 NotebookApp] Writing notebook server cookie secret to /home/jovyan/.local/share/jupyter/runtime/notebook_cookie_secret
[W 01:14:50.724 NotebookApp] WARNING: The notebook server is listening on all IP addresses and not using encryption. This is not recommended.
[I 01:14:50.747 NotebookApp] JupyterLab beta preview extension loaded from /opt/conda/lib/python3.6/site-packages/jupyterlab
[I 01:14:50.747 NotebookApp] JupyterLab application directory is /opt/conda/share/jupyter/lab
[I 01:14:50.754 NotebookApp] Serving notebooks from local directory: /home/jovyan
[I 01:14:50.754 NotebookApp] 0 active kernels
[I 01:14:50.754 NotebookApp] The Jupyter Notebook is running at:
[I 01:14:50.754 NotebookApp] http://[all ip addresses on your system]:8888/?token=04646d5c5e928da75842cd318d4a3c5aa1f942fc5964323a
[I 01:14:50.754 NotebookApp] Use Control-C to stop this server and shut down all kernels (twice to skip confirmation).
[C 01:14:50.755 NotebookApp]
docker run --rm -p 8888:8888 notebook-examples
# Executing the command: jupyter notebook
# [I 01:14:50.532 NotebookApp] Writing notebook server cookie secret to /home/jovyan/.local/share/jupyter/runtime/notebook_cookie_secret
# [W 01:14:50.724 NotebookApp] WARNING: The notebook server is listening on all IP addresses and not using encryption. This is not recommended.
# [I 01:14:50.747 NotebookApp] JupyterLab beta preview extension loaded from /opt/conda/lib/python3.6/site-packages/jupyterlab
# [I 01:14:50.747 NotebookApp] JupyterLab application directory is /opt/conda/share/jupyter/lab
# [I 01:14:50.754 NotebookApp] Serving notebooks from local directory: /home/jovyan
# [I 01:14:50.754 NotebookApp] 0 active kernels
# [I 01:14:50.754 NotebookApp] The Jupyter Notebook is running at:
# [I 01:14:50.754 NotebookApp] http://[all ip addresses on your system]:8888/?token=04646d5c5e928da75842cd318d4a3c5aa1f942fc5964323a
# [I 01:14:50.754 NotebookApp] Use Control-C to stop this server and shut down all kernels (twice to skip confirmation).
# [C 01:14:50.755 NotebookApp]
Copy/paste this URL into your browser when you connect for the first time,
to login with a token:
http://localhost:8888/?token=04646d5c5e928da75842cd318d4a3c5aa1f942fc5964323a
# Copy/paste this URL into your browser when you connect for the first time,
# to login with a token:
# http://localhost:8888/?token=04646d5c5e928da75842cd318d4a3c5aa1f942fc5964323a
```
Open your browser on the URL displayed, and you will find the notebooks from the Git repository and can work with them.
@@ -159,11 +159,11 @@ To use the OpenShift command line to build into an image, and deploy, the set of
```bash
oc new-app --template jupyter-notebook-quickstart \
--param APPLICATION_NAME=notebook-examples \
--param GIT_REPOSITORY_URL=https://github.com/jupyter/notebook \
--param CONTEXT_DIR=docs/source/examples/Notebook \
--param BUILDER_IMAGE=jupyter/minimal-notebook:latest \
--param NOTEBOOK_PASSWORD=mypassword
--param APPLICATION_NAME=notebook-examples \
--param GIT_REPOSITORY_URL=https://github.com/jupyter/notebook \
--param CONTEXT_DIR=docs/source/examples/Notebook \
--param BUILDER_IMAGE=jupyter/minimal-notebook:latest \
--param NOTEBOOK_PASSWORD=mypassword
```
You can provide a password using the `NOTEBOOK_PASSWORD` parameter.