2017-10-07 00:43:31 +00:00
|
|
|
# jupyter-repo2docker
|
|
|
|
|
|
|
|
|
|
|
|
[![Build Status](https://travis-ci.org/jupyter/repo2docker.svg?branch=master)](https://travis-ci.org/jupyter/repo2docker)
|
2017-10-23 16:10:56 +00:00
|
|
|
[![Documentation Status](https://readthedocs.org/projects/repo2docker/badge/?version=latest)](http://repo2docker.readthedocs.io/en/latest/?badge=latest)
|
2017-10-07 00:43:31 +00:00
|
|
|
|
2017-12-07 18:50:46 +00:00
|
|
|
**jupyter-repo2docker** is a tool to build, run and push Docker images from source code repositories.
|
|
|
|
|
|
|
|
See the [repo2docker documentation](http://repo2docker.readthedocs.io)
|
|
|
|
for more information.
|
2017-10-07 00:43:31 +00:00
|
|
|
|
|
|
|
## Pre-requisites
|
|
|
|
|
|
|
|
1. Docker to build & run the repositories. The [community edition](https://store.docker.com/search?type=edition&offering=community)
|
|
|
|
is recommended.
|
|
|
|
2. Python 3.4+.
|
|
|
|
|
|
|
|
## Installation
|
|
|
|
|
|
|
|
To install from pypi, the python packaging index:
|
|
|
|
|
|
|
|
```bash
|
|
|
|
pip install jupyter-repo2docker
|
|
|
|
```
|
|
|
|
|
2017-11-29 09:50:47 +00:00
|
|
|
To install from source and start contributing:
|
2017-10-07 00:43:31 +00:00
|
|
|
|
|
|
|
```bash
|
|
|
|
git clone https://github.com/jupyter/repo2docker.git
|
|
|
|
cd repo2docker
|
2017-11-29 09:50:47 +00:00
|
|
|
pip install -e .
|
2017-10-07 00:43:31 +00:00
|
|
|
```
|
|
|
|
|
|
|
|
## 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:
|
|
|
|
|
|
|
|
```bash
|
|
|
|
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!
|
|
|
|
|
2017-12-07 18:50:46 +00:00
|
|
|
For more information on how to use ``repo2docker``, see the
|
|
|
|
[usage guide](http://repo2docker.readthedocs.io/en/latest/usage.html).
|
2017-10-07 00:43:31 +00:00
|
|
|
|
|
|
|
## Repository specifications
|
|
|
|
|
2017-12-07 18:50:46 +00:00
|
|
|
Repo2Docker looks for configuration files in the repository being built to figure out how to build it.
|
2017-10-07 00:43:31 +00:00
|
|
|
It is philosophically similar to [Heroku Build Packs](https://devcenter.heroku.com/articles/buildpacks).
|
|
|
|
|
2017-12-07 18:50:46 +00:00
|
|
|
For a list of the configuration files that ``repo2docker`` can use,
|
|
|
|
see the [usage guide](http://repo2docker.readthedocs.io/en/latest/usage.html).
|