3.5 KiB
jupyter-repo2docker
jupyter-repo2docker is a tool to build, run and push docker images from source code repositories.
Pre-requisites
- Docker to build & run the repositories. The community edition is recommended.
- Python 3.4+.
Installation
To install from pypi, the python packaging index:
pip install jupyter-repo2docker
To install from source and start contributing:
git clone https://github.com/jupyter/repo2docker.git
cd repo2docker
pip install -e .
Usage
The core feature of repo2docker is to fetch a repo (from github or locally), build a container image based on the specifications found in the repo & optionally launch a local Jupyter Notebook you can use to explore it.
Note that Docker needs to be running on your machine for this to work.
Example:
jupyter-repo2docker https://github.com/jakevdp/PythonDataScienceHandbook
After building (it might take a while!), it should output in your terminal something like:
Copy/paste this URL into your browser when you connect for the first time,
to login with a token:
http://0.0.0.0:36511/?token=f94f8fabb92e22f5bfab116c382b4707fc2cade56ad1ace0
If you copy paste that URL into your browser you will see a Jupyter Notebook with the contents of the repository you had just built!
Displaying the image Dockerfile
Repo2Docker will generate a Dockerfile that composes the created Docker image.
To see the contents of this Dockerfile without building the image use --debug and --no-build
flags like so:
jupyter-repo2docker --debug --no-build https://github.com/jakevdp/PythonDataScienceHandbook
Repository specifications
Repo2Docker looks for various files in the repository being built to figure out how to build it. It is philosophically similar to Heroku Build Packs.
It currently looks for the following files. They are all composable - you can use any number of them in the same repository (except for Dockerfiles, which take precedence over everything else).
requirements.txt
This specifies a list of python packages that would be installed in a virtualenv (or conda environment).
environment.yml
This is a conda environment specification, that lets you install packages with conda. Note that you must leave the name of the environment empty for this to work out of the box.
apt.txt
A list of debian packages that should be installed. The base image used is usually the latest released version of Ubuntu (currently Zesty.)
postBuild
A script that can contain arbitrary commands to be run after the whole repository has been built. If you
want this to be a shell script, make sure the first line is #!/bin/bash. This file must have the
executable bit set (chmod +x postBuild) to be considered.
REQUIRE
This specifies a list of Julia packages! Currently only version 0.6 of Julia is supported, but more will be as they are released.
Dockerfile
This will be treated as a regular Dockerfile and a regular Docker build will be performed. The presence of a Dockerfile will cause all other building behavior to not be triggered.