Command-line usage and API#
repo2docker is called with this command:
repo2docker <source-repository>
where <source-repository> is a repository in one of the supported repository providers.
For example, the following command will build an image of Peter Norvig’s Pytudes repository:
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 requirements.txt file, and these will be present in the generated Docker image. To learn more about configuration files in repo2docker visit Configuration files supported by repo2docker.
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.
Debug repo2docker with --debug and --no-build#
To debug the container image being built, pass the --debug parameter:
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.
repo2docker --no-build --debug https://github.com/norvig/pytudes
Build from a 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:
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.
Set environment variables during builds#
When running repo2docker locally you can use the -e or --env command-line
flag for each variable that you want to define.
For example:
repo2docker -e VAR1=val1 -e VAR2=val2 ...
You can also configure environment variables for all users of a repository using the start - Run code before the user sessions starts configuration file.
Command-line API#
.. program:: repo2docker
repo2docker ???????????
Fetch a repository and build a container image
.. code-block:: console
usage: repo2docker [-h] [–help-all] [–version] [–config CONFIG] [–json-logs] [–image-name IMAGE_NAME] [–ref REF] [–debug] [–no-build] [–build] [–no-run] [–run] [–publish PORTS] [–publish-all] [–no-clean] [–clean] [–push] [–no-push] [–volume VOLUMES] [–user-id USER_ID] [–user-name USER_NAME] [–env ENVIRONMENT] [–editable] [–target-repo-dir TARGET_REPO_DIR] [–appendix APPENDIX] [–label LABELS] [–build-arg BUILD_ARGS] [–subdir SUBDIR] [–cache-from CACHE_FROM] [–engine ENGINE] repo …
.. option:: repo
Path to repository that should be built. Could be local path or a git URL.
.. option:: cmd
Custom command to run after building container
.. option:: -h, –help
show this help message and exit
.. option:: –help-all
Display all configurable options and exit.
.. option:: –version
Print the repo2docker version and exit.
.. option:: –config
Path to config file for repo2docker
.. option:: –json-logs
Emit JSON logs instead of human readable logs
.. option:: –image-name <image_name>
Name of image to be built. If unspecified will be autogenerated
Reference to build instead of default reference. For example branch name or commit for a Git repository.
.. option:: –debug
Turn on debug logging
.. option:: –no-build
Do not actually build the image. Useful in conjunction with –debug.
.. option:: –build
Build the image (default)
.. option:: –no-run
Do not run container after it has been built
.. option:: –run
Run container after it has been built (default).
.. option:: –publish
Specify port mappings for the image. Needs a command to run in the container.
.. option:: –publish-all, -P
Publish all exposed ports to random host ports.
.. option:: –no-clean
Don’t clean up remote checkouts after we are done
.. option:: –clean
Clean up remote checkouts after we are done (default).
.. option:: –push
Push docker image to repository
.. option:: –no-push
Don’t push docker image to repository (default).
.. option:: –volume
Volumes to mount inside the container, in form src:dest
.. option:: –user-id <user_id>
User ID of the primary user in the image
.. option:: –user-name <user_name>
Username of the primary user in the image
.. option:: –env, -e
Environment variables to define at container run time
.. option:: –editable, -E
Use the local repository in edit mode
.. option:: –target-repo-dir <target_repo_dir>
Path inside the image where contents of the repositories are copied to,
and where all the build operations (such as postBuild) happen.
Defaults to ${HOME} if not set
.. option:: –appendix
Appendix of Dockerfile commands to run at the end of the build.
Can be used to customize the resulting image after all
standard build steps finish.
.. option:: –label
Extra label to set on the image, in form name=value
.. option:: –build-arg <build_args>
Extra build arg to pass to the build process, in form name=value
.. option:: –subdir
Subdirectory of the git repository to examine.
Defaults to ''.
.. option:: –cache-from <cache_from>
List of images to try & re-use cached image layers from.
Docker only tries to re-use image layers from images built locally,
not pulled from a registry. We can ask it to explicitly re-use layers
from non-locally built images by through the 'cache_from' parameter.
.. option:: –engine
Name of the container engine.
Defaults to 'docker'.