Using repo2docker
¶
Note
Docker must be running in
order to run repo2docker
. For more information on installing
repo2docker
, see Installing repo2docker.
repo2docker
can build a reproducible computational environment for any repository that
follows The Reproducible Execution Environment Specification. repo2docker is called with a URL/path to a repository. It then
performs these steps:
- Inspects the repository for configuration files. These will be used to build the environment needed to run the repository.
- Builds a Docker image with an environment specified in these configuration files.
- Runs a Jupyter server within the image that lets you explore the repository interactively (optional)
- Pushes the images to a Docker registry so that it may be accessed remotely (optional)
Calling repo2docker¶
repo2docker is called with this command:
jupyter-repo2docker <URL-or-path to repository>
where <URL-or-path to repository>
is a URL or path to the source repository
for which you’d like to build an image.
For example, the following command will build an image of Peter Norvig’s Pytudes repository:
jupyter-repo2docker https://github.com/norvig/pytudes
Building the image may take a few minutes.
Pytudes
uses a requirements.txt file
to specify its Python environment. Because of this, repo2docker
will use
pip
to install dependencies listed in this requirement.txt
file, and
these will be present in the generated Docker image. To learn more about
configuration files in repo2docker
visit Configuration Files.
When the image is built, a message will be output to your terminal:
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
Pasting the URL into your browser will open Jupyter Notebook with the dependencies and contents of the source repository in the built image.
Building a specific branch, commit or tag¶
To build a particular branch and commit, use the argument --ref
and
specify the branch-name
or commit-hash
. For example:
jupyter-repo2docker --ref 9ced85dd9a84859d0767369e58f33912a214a3cf https://github.com/norvig/pytudes
Tip
For reproducible builds, we recommend specifying a commit-hash to deterministically build a fixed version of a repository. Not specifying a commit-hash will result in the latest commit of the repository being built.
Where to put configuration files¶
repo2docker
will look for configuration files in:
- A folder named
binder/
in the root of the repository. - A folder named
.binder/
in the root of the repository. - The root directory of the repository.
repo2docker searches for these folders in order (binder/
, .binder/
,
root). Only configuration files in the first identified folder are considered.
Check the complete list of configuration files supported
by repo2docker
to see how to configure the build process.
Note
repo2docker
builds an environment with Python 3.7 by default. If you’d
like a different version, you can specify this in your
configuration files.
Debugging repo2docker with --debug
and --no-build
¶
To debug the docker image being built, pass the --debug
parameter:
jupyter-repo2docker --debug https://github.com/norvig/pytudes
This will print the generated Dockerfile
, build it, and run it.
To see the generated Dockerfile
without actually building it,
pass --no-build
to the commandline. This Dockerfile
output
is for debugging purposes of repo2docker
only - it can not
be used by docker directly.
jupyter-repo2docker --no-build --debug https://github.com/norvig/pytudes
Command line API¶
jupyter-repo2docker¶
Fetch a repository and build a container image
usage: jupyter-repo2docker [-h] [--config CONFIG] [--json-logs]
[--image-name IMAGE_NAME] [--ref REF] [--debug]
[--no-build]
[--build-memory-limit BUILD_MEMORY_LIMIT]
[--no-run] [--publish PORTS] [--publish-all]
[--no-clean] [--push] [--volume VOLUMES]
[--user-id USER_ID] [--user-name USER_NAME]
[--env ENVIRONMENT] [--editable]
[--target-repo-dir TARGET_REPO_DIR]
[--appendix APPENDIX] [--subdir SUBDIR] [--version]
[--cache-from CACHE_FROM]
repo ...
-
repo
¶
Path to repository that should be built. Could be local path or a git URL.
-
cmd
¶
Custom command to run after building container
-
-h
,
--help
¶
show this help message and exit
-
--config
<config>
¶ Path to config file for repo2docker
-
--json-logs
¶
Emit JSON logs instead of human readable logs
-
--image-name
<image_name>
¶ Name of image to be built. If unspecified will be autogenerated
-
--ref
<ref>
¶ If building a git url, which reference to check out. E.g., master.
-
--debug
¶
Turn on debug logging
-
--no-build
¶
Do not actually build the image. Useful in conjunction with –debug.
-
--build-memory-limit
<build_memory_limit>
¶ Total Memory that can be used by the docker build process
-
--no-run
¶
Do not run container after it has been built
-
--publish
<ports>
,
-p
<ports>
¶ Specify port mappings for the image. Needs a command to run in the container.
-
--publish-all
,
-P
¶
Publish all exposed ports to random host ports.
-
--no-clean
¶
Don’t clean up remote checkouts after we are done
-
--push
¶
Push docker image to repository
-
--volume
<volumes>
,
-v
<volumes>
¶ Volumes to mount inside the container, in form src:dest
-
--user-id
<user_id>
¶ User ID of the primary user in the image
-
--user-name
<user_name>
¶ Username of the primary user in the image
-
--env
<environment>
,
-e
<environment>
¶ Environment variables to define at container run time
-
--editable
,
-E
¶
Use the local repository in edit mode
-
--target-repo-dir
<target_repo_dir>
¶ Path inside the image where contents of the repositories are copied to. Defaults to ${HOME} if not set
-
--appendix
<appendix>
¶
-
--subdir
<subdir>
¶
-
--version
¶
Print the repo2docker version and exit.
-
--cache-from
<cache_from>
¶