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
2018-03-21 19:32:16 +00:00
**jupyter-repo2docker** takes as input a repository source, such as a GitHub
2018-08-20 11:04:01 +00:00
repository. It then builds, runs, and/or pushes Docker images built from that source.
2017-12-07 18:50:46 +00:00
See the [repo2docker documentation ](http://repo2docker.readthedocs.io )
for more information.
2017-10-07 00:43:31 +00:00
2018-08-20 11:09:20 +00:00
## Prerequisites
2017-10-07 00:43:31 +00:00
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+.
2018-03-21 19:32:16 +00:00
Supported on Linux and macOS. [See documentation note about Windows support. ](http://repo2docker.readthedocs.io/en/latest/install.html#note-about-windows-support )
2017-10-07 00:43:31 +00:00
## Installation
2018-03-21 19:32:16 +00:00
To install from PyPI, the python packaging index, using `pip` :
2017-10-07 00:43:31 +00:00
```bash
pip install jupyter-repo2docker
```
2018-03-21 19:32:16 +00:00
To install from source:
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
2018-08-20 11:09:20 +00:00
The core feature of repo2docker is to fetch a repository (from GitHub or locally),
2018-08-20 11:04:01 +00:00
build a container image based on the specifications found in the repository &
2018-03-21 19:32:16 +00:00
optionally launch a local Jupyter Notebook you can use to explore it.
2017-10-07 00:43:31 +00:00
**Note that Docker needs to be running on your machine for this to work.**
Example:
```bash
2018-03-21 19:32:16 +00:00
jupyter-repo2docker https://github.com/norvig/pytudes
2017-10-07 00:43:31 +00:00
```
2018-03-21 19:32:16 +00:00
After building (it might take a while!), it should output in your terminal
something like:
2017-10-07 00:43:31 +00:00
2018-03-21 19:32:16 +00:00
```bash
2017-10-07 00:43:31 +00:00
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
```
2018-03-21 19:32:16 +00:00
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-10-07 00:43:31 +00:00
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-08 19:53:15 +00:00
Repo2Docker looks for configuration files in the source repository to
2018-03-21 19:32:16 +00:00
determine how the Docker image should be built. It is philosophically similar
to [Heroku Build Packs ](https://devcenter.heroku.com/articles/buildpacks ).
2017-10-07 00:43:31 +00:00
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 ).