kopia lustrzana https://github.com/jupyterhub/repo2docker
updating docs
Chris Holdgraf
rodzic
65d541125d
commit
56870a3a6c
202
README.md
202
README.md
|
|
@ -1,100 +1,102 @@
|
|||
# jupyter-repo2docker
|
||||
|
||||
|
||||
[](https://travis-ci.org/jupyter/repo2docker)
|
||||
|
||||
**jupyter-repo2docker** is a tool to build, run and push docker images from source code repositories.
|
||||
|
||||
|
||||
## 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
|
||||
```
|
||||
|
||||
To install from source:
|
||||
|
||||
```bash
|
||||
git clone https://github.com/jupyter/repo2docker.git
|
||||
cd repo2docker
|
||||
pip install .
|
||||
```
|
||||
|
||||
## 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.
|
||||
|
||||
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!
|
||||
|
||||
### 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:
|
||||
|
||||
```bash
|
||||
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](https://devcenter.heroku.com/articles/buildpacks).
|
||||
|
||||
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.
|
||||
# jupyter-repo2docker
|
||||
|
||||
|
||||
[](https://travis-ci.org/jupyter/repo2docker)
|
||||
|
||||
**jupyter-repo2docker** is a tool to build, run and push docker images from source code repositories.
|
||||
|
||||
|
||||
## 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
|
||||
```
|
||||
|
||||
To install from source:
|
||||
|
||||
```bash
|
||||
git clone https://github.com/jupyter/repo2docker.git
|
||||
cd repo2docker
|
||||
pip install .
|
||||
```
|
||||
|
||||
## 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!
|
||||
|
||||
### 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:
|
||||
|
||||
```bash
|
||||
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](https://devcenter.heroku.com/articles/buildpacks).
|
||||
|
||||
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.
|
||||
|
|
|
|||
|
|
@ -188,19 +188,23 @@ epub_exclude_files = ['search.html']
|
|||
import os
|
||||
s = ''
|
||||
FILE_ORDER_PREFERENCE = ['System', 'Python', 'Julia', 'Docker', 'Misc']
|
||||
SKIP_FOLDERS = ['binder-dir']
|
||||
FILES_DICT = {ii: [] for ii in FILE_ORDER_PREFERENCE}
|
||||
for folder, _, files in os.walk(os.path.join('..', '..', 'tests')):
|
||||
if 'README.rst' not in files:
|
||||
for root, _, files in os.walk(os.path.join('..', '..', 'tests')):
|
||||
depth = len(root.split('/')) - 3
|
||||
if 'README.rst' not in files or depth > 2:
|
||||
continue
|
||||
if any(folder in root for folder in SKIP_FOLDERS):
|
||||
continue
|
||||
header = files.pop(files.index('README.rst'))
|
||||
with open(os.path.join(folder, header), 'r') as ff:
|
||||
with open(os.path.join(root, header), 'r') as ff:
|
||||
this_s = ff.read() + '\n'
|
||||
title = this_s.split('\n')[0]
|
||||
for ifile in files:
|
||||
filename = os.path.basename(ifile)
|
||||
if filename == 'verify':
|
||||
continue
|
||||
with open(os.path.join(folder, ifile), 'r') as ff:
|
||||
with open(os.path.join(root, ifile), 'r') as ff:
|
||||
lines = ff.readlines()
|
||||
lines = [' ' + line for line in lines]
|
||||
this_s += 'File: ``{}``\n{}\n\n**Contents**::\n\n'.format(
|
||||
|
|
@ -209,7 +213,7 @@ for folder, _, files in os.walk(os.path.join('..', '..', 'tests')):
|
|||
this_s += '\n\n'
|
||||
usename = [ii for ii in FILE_ORDER_PREFERENCE if ii in title]
|
||||
usename = 'Misc' if len(usename) == 0 else usename[0]
|
||||
FILES_DICT[usename].append(this_s)
|
||||
FILES_DICT[usename].append(this_s)
|
||||
for key in FILE_ORDER_PREFERENCE:
|
||||
for istring in FILES_DICT[key]:
|
||||
s += istring
|
||||
|
|
|
|||
|
|
@ -4,4 +4,11 @@ Sample build files
|
|||
There are many options for specifying your environment with ``repo2docker``.
|
||||
The following sections describe a few samples to get you started.
|
||||
|
||||
.. note::
|
||||
|
||||
These files must be in the root of your repository, or in a folder called
|
||||
``binder`` that is in the root of your repository. If you include a folder
|
||||
called ``binder`` in the root of your repository, then all build files *not*
|
||||
inside this folder will be ignored.
|
||||
|
||||
.. include:: test_file_text.txt
|
||||
|
|
|
|||
Plik diff jest za duży
Load Diff
|
|
@ -1,4 +1,4 @@
|
|||
Binder Directory
|
||||
----------------
|
||||
|
||||
top-level Dockerfile will be ignored if binder directory exists.
|
||||
Binder Directory
|
||||
----------------
|
||||
|
||||
A top-level Dockerfile will be ignored if a ``binder`` directory exists.
|
||||
|
|
|
|||
|
|
@ -5,3 +5,10 @@ It is possible to run scripts after you've built the environment specified in
|
|||
your other files. This could be used to, for example, download data or run
|
||||
some configuration scripts. For example, this will download and install a
|
||||
Jupyter extension.
|
||||
|
||||
.. note::
|
||||
|
||||
This file needs to be executable in order to work with ``repo2docker``. The
|
||||
easiest way to do this is to run the following command with ``git``::
|
||||
|
||||
git update-index --chmod=+x postBuild
|
||||
|
|
|
|||
Ładowanie…
Reference in New Issue