2021-03-23 06:28:39 +00:00
# <a href="https://github.com/jupyterhub/repo2docker"><img src="https://raw.githubusercontent.com/jupyterhub/repo2docker/8731ecf0967cc5fde028c456f2b92be651ebbc18/docs/source/_static/images/repo2docker.png" height="48px" /> repo2docker</a>
2017-10-07 00:43:31 +00:00
2020-08-14 09:24:26 +00:00
[![Build Status ](https://github.com/jupyterhub/repo2docker/workflows/Continuous%20Integration/badge.svg )](https://github.com/jupyterhub/repo2docker/actions)
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)
2020-01-28 09:17:50 +00:00
[![Contribute ](https://img.shields.io/badge/I_want_to_contribute!-grey?logo=jupyter )](https://repo2docker.readthedocs.io/en/latest/contributing/contributing.html)
2021-08-23 20:30:20 +00:00
[![Docker Repository on Quay ](https://img.shields.io/badge/quay.io-container-green "Docker Repository on Quay" )](https://quay.io/repository/jupyterhub/repo2docker?tab=tags)
2017-10-07 00:43:31 +00:00
2018-10-09 08:12:56 +00:00
`repo2docker` fetches a git repository and builds a container image based on
the configuration files found in the repository.
2017-12-07 18:50:46 +00:00
See the [repo2docker documentation ](http://repo2docker.readthedocs.io )
2018-11-06 07:50:25 +00:00
for more information on using repo2docker.
2017-10-07 00:43:31 +00:00
2019-03-17 08:16:59 +00:00
For support questions please search or post to https://discourse.jupyter.org/c/binder.
2018-10-09 08:12:56 +00:00
See the [contributing guide ](CONTRIBUTING.md ) for information on contributing to
repo2docker.
2021-06-11 11:01:24 +00:00
---
Please note that this repository is participating in a study into sustainability
of open source projects. Data will be gathered about this repository for
approximately the next 12 months, starting from 2021-06-11.
Data collected will include number of contributors, number of PRs, time taken to
close/merge these PRs, and issues closed.
For more information, please visit
[our informational page ](https://sustainable-open-science-and-software.github.io/ ) or download our [participant information sheet ](https://sustainable-open-science-and-software.github.io/assets/PIS_sustainable_software.pdf ).
---
2018-11-08 18:06:42 +00:00
2018-10-09 08:12:56 +00:00
## Using repo2docker
### 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.
2020-09-07 06:02:09 +00:00
2. Python 3.6+.
2017-10-07 00:43:31 +00:00
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 )
2018-10-09 08:12:56 +00:00
### Installation
This a quick guide to installing `repo2docker` , see our documentation for [a full guide ](https://repo2docker.readthedocs.io/en/latest/install.html ).
2017-10-07 00:43:31 +00:00
2018-10-09 08:12:56 +00:00
To install from PyPI:
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
2020-08-10 07:33:05 +00:00
git clone https://github.com/jupyterhub/repo2docker.git
2017-10-07 00:43:31 +00:00
cd repo2docker
2017-11-29 09:50:47 +00:00
pip install -e .
2017-10-07 00:43:31 +00:00
```
2018-10-09 08:12:56 +00:00
### Usage
2017-10-07 00:43:31 +00:00
2018-10-09 08:12:56 +00:00
The core feature of repo2docker is to fetch a git 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-10-09 08:12:56 +00:00
optionally launch the container that you can use to explore the repository.
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
2018-10-09 08:12:56 +00:00
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-10-09 08:12:56 +00:00
determine how the Docker image should be built. For a list of the configuration
files that ``repo2docker`` can use, see the
[complete list of configuration files ](https://repo2docker.readthedocs.io/en/latest/config_files.html ).
2017-10-07 00:43:31 +00:00
2018-10-09 08:12:56 +00:00
The philosophy of repo2docker is inspired by
[Heroku Build Packs ](https://devcenter.heroku.com/articles/buildpacks ).
2021-08-21 16:50:03 +00:00
## Docker Image
2021-08-21 19:17:09 +00:00
Repo2Docker can be run inside a Docker container if access to the Docker Daemon is provided, for example see [BinderHub ](https://github.com/jupyterhub/binderhub ). Docker images are [published to quay.io ](https://quay.io/repository/jupyterhub/repo2docker?tab=tags ). The old [Docker Hub image ](https://hub.docker.com/r/jupyter/repo2docker ) is no longer supported.