### Example start script Source: https://github.com/jupyterhub/repo2docker/blob/main/docs/source/configuration/actions.md A shell script to be run at runtime as an ENTRYPOINT to the Docker container. The last line must be `exec "$@"`. This script is executed each time your binder is started. ```shell #!/bin/bash set -e # Example: Set an environment variable export MY_VARIABLE="some_value" # Execute the command passed to the script exec "$@" ``` -------------------------------- ### Start Podman listening service Source: https://github.com/jupyterhub/repo2docker/blob/main/docs/source/start.md Start the Podman socket service for user-level access. Ensure Podman is installed and configured. ```bash systemctl --user start podman.socket ``` -------------------------------- ### Install repo2docker from source Source: https://github.com/jupyterhub/repo2docker/blob/main/README.md Clone the repository and perform an editable installation. ```bash git clone https://github.com/jupyterhub/repo2docker.git cd repo2docker pip install -e . ``` -------------------------------- ### Build documentation locally Source: https://github.com/jupyterhub/repo2docker/blob/main/docs/source/contribute/contributing.md Use these commands to install requirements and build the project documentation. ```bash pip install -e . pip install -r docs/requirements.txt cd docs/ make devenv ``` -------------------------------- ### Terminal output example Source: https://github.com/jupyterhub/repo2docker/blob/main/docs/source/cli.md Example of the terminal output provided after a successful build. ```default 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 ``` -------------------------------- ### Install repo2docker via PyPI Source: https://github.com/jupyterhub/repo2docker/blob/main/README.md Use pip to install the package from the Python Package Index. ```bash pip install jupyter-repo2docker ``` -------------------------------- ### Install packages with apt-get Source: https://github.com/jupyterhub/repo2docker/blob/main/docs/source/configuration/system.md Use apt.txt to list .deb packages for installation. The base image is Ubuntu 24.04 LTS (Noble Numbat) by default. All available .deb files are listed on Ubuntu Packages. ```text # Example apt.txt for LaTeX latexmk texlive-xetex ``` -------------------------------- ### Set up a local virtual environment Source: https://github.com/jupyterhub/repo2docker/blob/main/docs/source/contribute/contributing.md These commands create a Python virtual environment and install all necessary dependencies for development and documentation. ```bash python3 -m venv . source bin/activate pip3 install -e . pip3 install -r dev-requirements.txt pip3 install -r docs/requirements.txt pip3 install black ``` -------------------------------- ### Check Podman installation Source: https://github.com/jupyterhub/repo2docker/blob/main/docs/source/start.md Verify that Podman is installed and running by checking its info. This command is used after installing Podman. ```bash podman info ``` -------------------------------- ### Verify Docker installation Source: https://github.com/jupyterhub/repo2docker/blob/main/docs/source/contribute/contributing.md Check that Docker is correctly installed and running on your system. ```bash docker version ``` ```default Client: Version: 17.09.0-ce API version: 1.32 Go version: go1.8.3 Git commit: afdb6d4 Built: Tue Sep 26 22:42:45 2017 OS/Arch: linux/amd64 Server: Version: 17.09.0-ce API version: 1.32 (minimum version 1.12) Go version: go1.8.3 Git commit: afdb6d4 Built: Tue Sep 26 22:41:24 2017 OS/Arch: linux/amd64 Experimental: false ``` -------------------------------- ### Install pixi CLI in a user-accessible location Source: https://github.com/jupyterhub/repo2docker/blob/main/docs/source/use/actions-and-scripts.md When installing tools like the pixi CLI, ensure they are placed in directories writable by the `jovyan` user. `$CONDA_BIN` and `~/.local/bin` are suitable, while `/usr/bin` is not due to root privilege requirements. ```shell # Example of a valid installation path $CONDA_BIN ``` ```shell # Example of a valid installation path ~/.local/bin ``` ```shell # Example of an invalid installation path (requires root) /usr/bin ``` -------------------------------- ### Example postBuild script Source: https://github.com/jupyterhub/repo2docker/blob/main/docs/source/configuration/actions.md A shell script to be run after the repository has been built. Include `set -e` to prevent errors from being silently ignored. This script runs as the `jovyan` user. ```shell #!/bin/bash set -e # Example command to run after build echo "Post-build script executed." ``` -------------------------------- ### Launch Repo2Docker Session Source: https://github.com/jupyterhub/repo2docker/blob/main/docs/source/howto/export_environment.md Launch a basic repository using repo2docker to create an isolated environment for package installation and environment export. ```bash repo2docker https://github.com/binder-examples/conda-freeze ``` -------------------------------- ### Install repo2docker with pip Source: https://github.com/jupyterhub/repo2docker/blob/main/docs/source/start.md Install the jupyter-repo2docker package using pip. This command requires Python 3.6 or above. ```bash python3 -m pip install jupyter-repo2docker ``` -------------------------------- ### Run All Repo2Docker Tests Source: https://github.com/jupyterhub/repo2docker/blob/main/docs/source/contribute/tasks.md Execute all tests in the tests/ subdirectory using py.test. Ensure py.test is installed. ```bash py.test -s tests/* ``` -------------------------------- ### Implement fetch() Method for Content Provider Source: https://github.com/jupyterhub/repo2docker/blob/main/docs/source/contribute/contentprovider.md The fetch() method takes a spec dictionary and ensures the repository is available on disk, returning its path. This example demonstrates the ZenodoProvider's fetch method. ```python def fetch(self, spec): """Download a Zenodo repository. :param spec: A dictionary of arguments. :returns: A path to the repository. """ record_id = spec["zenodo_record_id"] # Use the Zenodo API to download the record # ... (download logic here) ... return "/path/to/downloaded/repository" ``` -------------------------------- ### Install Mercurial and hg-evolve Source: https://github.com/jupyterhub/repo2docker/blob/main/docs/source/use/repository.md Commands to install Mercurial and the hg-evolve extension on Debian-based systems. Ensure Mercurial and hg-evolve are installed for full support of Mercurial repositories. ```bash sudo apt install mercurial ``` ```bash $(hg debuginstall --template "{pythonexe}") -m pip install hg-evolve --user ``` -------------------------------- ### Troubleshoot ResolvePackageNotFound errors Source: https://github.com/jupyterhub/repo2docker/blob/main/docs/source/faq.md Example of the error output when conda environment files contain platform-specific build strings. ```default Step 39/44 : RUN conda env update -n root -f "environment.yml" && conda clean -tipsy && conda list -n root ---> Running in ebe9a67762e4 Solving environment: ...working... failed ResolvePackageNotFound: - jsonschema==2.6.0=py36hb385e00_0 - libedit==3.1.20181209=hb402a30_0 - tornado==5.1.1=py36h1de35cc_0 ... ``` -------------------------------- ### Pull and run a repo2docker container Source: https://github.com/jupyterhub/repo2docker/blob/main/docs/source/howto/deploy.md Use these commands to pull a custom image and start a Jupyter notebook server on port 8888. ```console docker pull / docker run -it --name repo2docker -p 8888:8888 / jupyter notebook --ip 0.0.0.0 ``` ```console docker pull vanessa/repo2docker docker run -it --name repo2docker -p 8888:8888 vanessa/repo2docker jupyter notebook --ip 0.0.0.0 ``` -------------------------------- ### Access the built container Source: https://github.com/jupyterhub/repo2docker/blob/main/README.md Example terminal output showing the URL to access the Jupyter environment after a successful build. ```bash 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 ``` -------------------------------- ### Execute Dockerfile Comparison Script Source: https://github.com/jupyterhub/repo2docker/blob/main/docs/source/contribute/tasks.md Example of how to execute the `dockerfile_diff.sh` script. Set the `R2D_COMPARE_TO` environment variable to the desired version and provide the target directory as an argument. ```bash cd tests/ R2D_COMPARE_TO=0.10.0 ./dockerfile_diff.sh venv/py35/ ``` -------------------------------- ### Implement detect() Method for Content Provider Source: https://github.com/jupyterhub/repo2docker/blob/main/docs/source/contribute/contentprovider.md The detect() method should identify if an input string points to this content provider and return a spec dictionary for the fetch() method. This example shows the ZenodoProvider's detect method. ```python def detect(self, spec): """Detect if the input is a Zenodo repository. :param spec: A dictionary of arguments. :returns: A dictionary of arguments or None. """ if "zenodo_record_id" in spec: return spec return None ``` -------------------------------- ### Specify packages with nix Source: https://github.com/jupyterhub/repo2docker/blob/main/docs/source/configuration/system.md Use default.nix to specify packages for the nix package manager. All other configuration files are ignored. Ensure Jupyter notebook is explicitly installed as repo2docker expects it. Pinning nixpkgs is recommended for reproducibility. ```nix let pkgs = import (fetchTarball "https://github.com/NixOS/nixpkgs/archive/YOUR-REV.tar.gz") {}; in pkgs.mkShell { buildInputs = [ pkgs.python3 pkgs.jupyterlab ]; }; ``` -------------------------------- ### Minimal Dockerfile for Frozen Environment Source: https://github.com/jupyterhub/repo2docker/blob/main/docs/source/howto/breaking_changes.md Use this minimal Dockerfile to create a frozen environment if other package installation methods fail. This image will contain a static version of your repository's build at the time of image creation. You must rebuild and push this image whenever your repository is modified. ```dockerfile FROM //: ``` -------------------------------- ### Define extra packages in environment.yml Source: https://github.com/jupyterhub/repo2docker/blob/main/docs/source/use/extend-community-image.md Use this file to specify additional Conda and pip packages to be installed on top of the base image. ```default channels: - conda-forge dependencies: - jupyterhub-singleuser>=3.0,<4.0 # Everyone wants to use nbgitpuller for everything, so let's do that - nbgitpuller=1.1.* # Install packages from pip - pip - pip: - otter-grader ``` -------------------------------- ### Build and run a repository Source: https://github.com/jupyterhub/repo2docker/blob/main/README.md Fetch a git repository and build a container image using the command line interface. ```bash jupyter-repo2docker https://github.com/norvig/pytudes ``` -------------------------------- ### Install Packages within Repo2Docker Source: https://github.com/jupyterhub/repo2docker/blob/main/docs/source/howto/export_environment.md Install necessary packages using conda within the repo2docker environment. This step is part of the strict version export process. ```bash conda install ``` -------------------------------- ### Display repo2docker usage syntax Source: https://github.com/jupyterhub/repo2docker/blob/main/docs/source/cli.md Shows the standard command-line structure and available flags for the repo2docker utility. ```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 … ``` -------------------------------- ### Build a repository image Source: https://github.com/jupyterhub/repo2docker/blob/main/docs/source/cli.md Basic command to build a container image from a source repository URL. ```default repo2docker ``` ```default repo2docker https://github.com/norvig/pytudes ``` -------------------------------- ### Build from Repository Reference Source: https://github.com/jupyterhub/repo2docker/blob/main/docs/source/use/repository.md Use this command to build a repository using repo2docker. Replace `` with a URL, DOI, SWHID, CKAN dataset URL, or local path. ```bash repo2docker ``` -------------------------------- ### Configure the local repository Source: https://github.com/jupyterhub/repo2docker/blob/main/docs/source/howto/deploy.md Commands to copy the CircleCI configuration into a new project directory and initialize it as a git repository. ```console mkdir -p myrepo cp -R continuous-build/.circleci myrepo/ ``` ```console cd myrepo git init git add .circleci ``` -------------------------------- ### Run repo2docker on a Source Repository Source: https://github.com/jupyterhub/repo2docker/blob/main/docs/source/index.md This command initiates the process of building a container image from a specified source repository. repo2docker inspects the repository for configuration files to define the environment, builds the image, and optionally runs it interactively or pushes it to a registry. ```default repo2docker ``` -------------------------------- ### Configure Dockerspawner image Source: https://github.com/jupyterhub/repo2docker/blob/main/docs/source/use/community-image.md Set the image and tag directly using the Dockerspawner configuration syntax. ```python c.DockerSpawner.image = 'pangeo/pangeo-notebook:2023.04.15' ``` -------------------------------- ### Export Conda Environment History Source: https://github.com/jupyterhub/repo2docker/blob/main/docs/source/howto/export_environment.md Use this command to create a minimal environment.yml containing only explicitly installed packages with loose version pinning. This is recommended for general use with repo2docker. ```bash conda env export --from-history -f environment.yml ``` -------------------------------- ### Configure R Environment with runtime.txt Source: https://github.com/jupyterhub/repo2docker/blob/main/docs/source/howto/languages.md Use runtime.txt to specify the R version and a CRAN snapshot date for your R environment. The format is 'r----
'. ```default r-4.1-2023-01-01 ``` -------------------------------- ### Run repo2docker in editable mode Source: https://github.com/jupyterhub/repo2docker/blob/main/docs/source/faq.md Use the -E flag to mount the local repository into the container for live editing. ```default repo2docker -E my-repository/ ``` -------------------------------- ### Build from specific reference Source: https://github.com/jupyterhub/repo2docker/blob/main/docs/source/cli.md Build a specific branch, commit, or tag using the --ref flag. ```default repo2docker --ref 9ced85dd9a84859d0767369e58f33912a214a3cf https://github.com/norvig/pytudes ``` -------------------------------- ### Build image from GitHub URL Source: https://github.com/jupyterhub/repo2docker/blob/main/docs/source/start.md Build a reproducible container image from a GitHub repository URL. repo2docker detects configuration files like requirements.txt to build the environment. ```bash jupyter-repo2docker https://github.com/binder-examples/requirements ``` -------------------------------- ### Format code with Black Source: https://github.com/jupyterhub/repo2docker/blob/main/docs/source/contribute/contributing.md Run these commands to format the codebase or enable the pre-commit hook for automatic style enforcement. ```bash black . pre-commit install ``` -------------------------------- ### Clone the continuous-build repository Source: https://github.com/jupyterhub/repo2docker/blob/main/docs/source/howto/deploy.md Use these commands to clone the template repository from GitHub via HTTPS or SSH. ```console git clone https://www.github.com//continuous-build ``` ```console git clone git@github.com:/continuous-build.git ``` -------------------------------- ### Run Specific Repo2Docker Test Source: https://github.com/jupyterhub/repo2docker/blob/main/docs/source/contribute/tasks.md Execute a single test file within the tests/ subdirectory. Replace with the actual file path. ```bash py.test -s tests/ ``` -------------------------------- ### Specify Python runtime version Source: https://github.com/jupyterhub/repo2docker/blob/main/docs/source/configuration/system.md Use runtime.txt to specify the Python version. Add a line 'python-x.y' to use Python version x.y. This is ignored if environment.yml or Project.toml are used. ```text python-3.10 ``` -------------------------------- ### Inherit and update image with Dockerfile Source: https://github.com/jupyterhub/repo2docker/blob/main/docs/source/use/extend-community-image.md This Dockerfile inherits from a base image, copies the environment configuration, and updates the environment. ```Dockerfile FROM jupyter/scipy-notebook:2023-05-01 COPY environment.yml /tmp/environment.yml RUN mamba env update --prefix ${CONDA_DIR} --file /tmp/environment.yml COPY image-tests image-tests RUN ls ``` -------------------------------- ### Clone the repository Source: https://github.com/jupyterhub/repo2docker/blob/main/docs/source/contribute/contributing.md Use this command to clone your fork of the repo2docker repository to your local machine. ```bash git clone https://github.com//repo2docker ``` -------------------------------- ### Advanced environments with Dockerfile Source: https://github.com/jupyterhub/repo2docker/blob/main/docs/source/configuration/system.md Use a Dockerfile for advanced environment customization. If a Dockerfile is present, all other configuration files are ignored. This performs a regular Docker build. ```dockerfile # Example Dockerfile FROM ubuntu:22.04 RUN apt-get update && apt-get install -y --no-install-recommends \ python3 \ python3-pip && \ rm -rf /var/lib/apt/lists/* RUN pip3 install --no-cache-dir \ jupyterlab # Set the working directory WORKDIR /app # Expose port 8888 for JupyterLab EXPOSE 8888 # Command to run JupyterLab CMD ["jupyter", "lab", "--ip=0.0.0.0", "--port=8888", "--no-browser", "--allow-root"] ``` -------------------------------- ### Specify Python Version with runtime.txt Source: https://github.com/jupyterhub/repo2docker/blob/main/docs/source/howto/languages.md Use runtime.txt to specify the Python runtime version when using requirements.txt. The file should contain a single line in the format 'python-X.X'. ```default python-3.6 ``` -------------------------------- ### Automate image builds with GitHub Actions Source: https://github.com/jupyterhub/repo2docker/blob/main/docs/source/use/extend-community-image.md A GitHub workflow configuration to build and push the extended container image using the repo2docker action. ```yaml name: Build and push container image on: push: branches: - main jobs: build-and-push: runs-on: ubuntu-latest steps: # For biggish images, github actions runs out of disk space. # So we cleanup some unwanted things in the disk image, and reclaim that space for our Docker use # https://github.com/actions/virtual-environments/issues/2606#issuecomment-772683150 # and https://github.com/easimon/maximize-build-space/blob/b4d02c14493a9653fe7af06cc89ca5298071c66e/action.yml#L104 # This gives us a total of about 52G of free space, which should be enough for now - name: cleanup disk space run: | sudo rm -rf /usr/local/lib/android /usr/share/dotnet /opt/ghc df -h - name: Checkout files in repo uses: actions/checkout@main - name: Build and push the image to quay.io uses: jupyterhub/repo2docker-action@master with: # Make sure username & password/token pair matches your registry credentials DOCKER_USERNAME: ${{ secrets.QUAY_USERNAME }} DOCKER_PASSWORD: ${{ secrets.QUAY_PASSWORD }} DOCKER_REGISTRY: "quay.io" # Disable pushing a 'latest' tag, as this often just causes confusion LATEST_TAG_OFF: true # # Uncomment and modify the following line with your image name, otherwise no push will happen IMAGE_NAME: "yuvipanda/example-inherit-from-community-image" # Lets us monitor disks getting full as images get bigger over time - name: Show how much disk space is left run: df -h ``` -------------------------------- ### Specify R runtime version Source: https://github.com/jupyterhub/repo2docker/blob/main/docs/source/configuration/system.md Use runtime.txt to specify the R version and a Posit Package Manager snapshot. Add a line 'r-x.y-YYYY-MM-DD'. Supported R versions include 4.4, 4.3, 4.2, 4.1, 4.0, 3.6, 3.5, 3.4, 3.3. If no version is specified, the latest release is used. This is ignored if environment.yml or Project.toml are used. ```text r-4.3-2023-01-01 ``` -------------------------------- ### Debug repo2docker builds Source: https://github.com/jupyterhub/repo2docker/blob/main/docs/source/cli.md Commands to inspect the generated Dockerfile during the build process. ```bash repo2docker --debug https://github.com/norvig/pytudes ``` ```bash repo2docker --no-build --debug https://github.com/norvig/pytudes ``` -------------------------------- ### Automated Dockerfile Comparison Across Directories Source: https://github.com/jupyterhub/repo2docker/blob/main/docs/source/contribute/tasks.md This command demonstrates how to run the `dockerfile_diff.sh` script for multiple directories containing a 'verify' file. It uses `find` to locate these directories and `execdir` to execute the script within each directory context. ```bash cd tests/ R2D_COMPARE_TO=0.10.0 CMD=$(pwd)/dockerfile_diff.sh find . -name 'verify' -execdir bash -c '$CMD $(pwd)' \; ``` -------------------------------- ### Set environment variables Source: https://github.com/jupyterhub/repo2docker/blob/main/docs/source/cli.md Define environment variables for the build process using the -e or --env flag. ```bash repo2docker -e VAR1=val1 -e VAR2=val2 ... ``` -------------------------------- ### repo2docker CLI Usage Source: https://github.com/jupyterhub/repo2docker/blob/main/docs/source/cli.md The primary command for repo2docker to fetch a repository and build a container image. ```APIDOC ## repo2docker CLI ### Description Fetch a repository and build a container image. ### Method CLI Command ### Endpoint N/A (Command-line tool) ### Parameters #### Path Parameters - **repo** (string) - Required - Path to repository that should be built. Could be local path or a git URL. #### Query Parameters - **-h, –help** (boolean) - Show this help message and exit. - **–help-all** (boolean) - Display all configurable options and exit. - **–version** (boolean) - Print the repo2docker version and exit. - **–config ** (string) - Path to config file for repo2docker. - **–json-logs** (boolean) - Emit JSON logs instead of human readable logs. - **–image-name ** (string) - Name of image to be built. If unspecified will be autogenerated. - **–ref ** (string) - Reference to build instead of default reference. For example branch name or commit for a Git repository. - **–debug** (boolean) - Turn on debug logging. - **–no-build** (boolean) - Do not actually build the image. Useful in conjunction with –debug. - **–build** (boolean) - Build the image (default). - **–no-run** (boolean) - Do not run container after it has been built. - **–run** (boolean) - Run container after it has been built (default). - **–publish ** (string) - Specify port mappings for the image. Needs a command to run in the container. - **-p, –publish ** (string) - Specify port mappings for the image. Needs a command to run in the container. - **–publish-all, -P** (boolean) - Publish all exposed ports to random host ports. - **–no-clean** (boolean) - Don’t clean up remote checkouts after we are done. - **–clean** (boolean) - Clean up remote checkouts after we are done (default). - **–push** (boolean) - Push docker image to repository. - **–no-push** (boolean) - Don’t push docker image to repository (default). - **–volume ** (string) - Volumes to mount inside the container, in form src:dest. - **-v, –volume ** (string) - Volumes to mount inside the container, in form src:dest. - **–user-id ** (string) - User ID of the primary user in the image. - **–user-name ** (string) - Username of the primary user in the image. - **–env** (string) - Environment variables to define at container run time. - **-e, –env** (string) - Environment variables to define at container run time. - **–editable, -E** (boolean) - Use the local repository in edit mode. - **–target-repo-dir ** (string) - 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. - **–appendix ** (string) - 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. - **–label ** (string) - Extra label to set on the image, in form name=value. - **–build-arg ** (string) - Extra build arg to pass to the build process, in form name=value. - **–subdir ** (string) - Subdirectory of the git repository to examine. Defaults to ''. - **–cache-from ** (string) - 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. - **–engine ** (string) - Name of the container engine. Defaults to 'docker'. #### Request Body N/A ### Request Example ```bash repo2docker --image-name my-custom-image --ref main my-repo/ ``` ### Response N/A (Command-line tool output) ```