{"id":13416606,"url":"https://github.com/indigo-dc/udocker","last_synced_at":"2025-04-10T03:44:01.514Z","repository":{"id":40302507,"uuid":"57313402","full_name":"indigo-dc/udocker","owner":"indigo-dc","description":"A basic user tool to execute simple docker containers in batch or interactive systems without root privileges.","archived":false,"fork":false,"pushed_at":"2024-08-28T14:03:42.000Z","size":6703,"stargazers_count":1359,"open_issues_count":21,"forks_count":132,"subscribers_count":34,"default_branch":"master","last_synced_at":"2024-10-29T15:32:47.652Z","etag":null,"topics":["batch","chroot","containers","deep-hybrid-datacloud","docker","docker-containers","emulation","eosc-hub","fakechroot","grid","hpc","indigo","proot","root-privileges","runc","user"],"latest_commit_sha":null,"homepage":"https://indigo-dc.github.io/udocker/","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/indigo-dc.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":"SECURITY.md","support":null,"governance":null,"roadmap":null,"authors":"AUTHORS.md","dei":null,"publiccode":null,"codemeta":"codemeta.json"}},"created_at":"2016-04-28T15:40:49.000Z","updated_at":"2024-10-29T11:50:01.000Z","dependencies_parsed_at":"2023-10-16T23:05:27.813Z","dependency_job_id":"c3a94312-7a50-44b2-b5af-0a6f38dd5bfd","html_url":"https://github.com/indigo-dc/udocker","commit_stats":{"total_commits":1577,"total_committers":26,"mean_commits":60.65384615384615,"dds":0.4635383639822448,"last_synced_commit":"831cf68ddea0ca38bd08c211b24a9e762c64f773"},"previous_names":[],"tags_count":66,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/indigo-dc%2Fudocker","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/indigo-dc%2Fudocker/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/indigo-dc%2Fudocker/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/indigo-dc%2Fudocker/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/indigo-dc","download_url":"https://codeload.github.com/indigo-dc/udocker/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248154967,"owners_count":21056541,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["batch","chroot","containers","deep-hybrid-datacloud","docker","docker-containers","emulation","eosc-hub","fakechroot","grid","hpc","indigo","proot","root-privileges","runc","user"],"created_at":"2024-07-30T21:01:01.932Z","updated_at":"2025-04-10T03:44:01.481Z","avatar_url":"https://github.com/indigo-dc.png","language":"Python","readme":"[![PyPI version](https://badge.fury.io/py/udocker.svg)](https://badge.fury.io/py/udocker)\n[![Build Status](https://jenkins.eosc-synergy.eu/buildStatus/icon?job=indigo-dc%2Fudocker%2Fmaster)](https://jenkins.eosc-synergy.eu/job/indigo-dc/job/udocker/job/master/)\n\n[![SQAaaS badge](https://github.com/EOSC-synergy/SQAaaS/raw/master/badges/badges_150x116/badge_software_gold.png)](https://api.eu.badgr.io/public/assertions/_HIuuD5PRMipzM62mWTk3Q \"SQAaaS gold badge achieved\")\n\n---\n![logo](docs/logo-small.png)\n\nudocker is a basic user tool to execute simple docker containers in user\nspace without requiring root privileges. Enables download and execution\nof docker containers by non-privileged users in Linux systems where\ndocker is not available. It can be used to pull and execute docker\ncontainers in Linux batch systems and interactive clusters that are\nmanaged by other entities such as grid infrastructures or externally\nmanaged batch or interactive systems.\n\nudocker does not require any type of privileges nor the deployment of\nservices by system administrators. It can be downloaded and executed\nentirely by the end user. The limited root functionality provided by\nsome of the udocker execution modes is either simulated or provided\nvia user namespaces.\n\nudocker is a wrapper around several tools and libraries to mimic a\nsubset of the docker capabilities including pulling images and running\ncontainers with minimal functionality.\n\n**Important notice: We have changed the udocker tools location as of udocker 1.3.17.\nThis affects the configuration option `conf['tarball']` and environment variable\n`UDOCKER_TARBALL`, so if you are using udocker \u003c= 1.3.16, make sure to:\n`export UDOCKER_TARBALL=https://download.a.incd.pt/udocker/udocker-englib-1.2.11.tar.gz`.**\n\n## Documentation\n\nThe full documentation is available at:\n\n* [udocker documentation](https://indigo-dc.github.io/udocker/)\n* [Installation manual](https://indigo-dc.github.io/udocker/installation_manual.html)\n* [User manual](https://indigo-dc.github.io/udocker/user_manual.html)\n* [Reference card](https://indigo-dc.github.io/udocker/reference_card.html)\n\n## How does it work\n\nudocker is written in Python, it has a minimal set of dependencies so\nthat can be executed in a wide range of Linux systems.\n\nudocker does not make use of docker nor requires its presence.\n\nudocker \"executes\" the containers by simply providing a chroot like\nenvironment over the extracted container. The current implementation\nsupports different methods to mimic chroot thus enabling execution of\ncontainers under a chroot like environment without requiring privileges.\nudocker transparently supports several methods to execute the containers\nbased on external tools and libraries such as:\n\n* PRoot\n* Fakechroot\n* runc\n* crun\n* Singularity\n\nWith the exception of Singularity the tools and libraries to support\nexecution are downloaded and deployed by udocker during the installation\nprocess. This installation is performed in the user home directory\nand does not require privileges. The udocker related files such as\nlibraries, executables, documentation, licenses, container images and\nextracted directory trees are placed by default under `$HOME/.udocker`.\n\n## Advantages\n\n* Can be deployed by the end-user\n* Does not require privileges for installation\n* Does not require privileges for execution\n* Does not require compilation, just transfer the Python code\n* Encapsulates several tools and execution methods\n* Includes the required tools already statically compiled to work\n  across systems\n* Provides a docker like command line interface\n* Supports a subset of docker commands:\n  search, pull, import, export, load, save, login, logout, create and run\n* Understands docker container metadata\n* Allows loading of docker and OCI containers\n* Supports NVIDIA GPGPU applications\n* Can execute in systems and environments where Linux namespaces\n  support is unavailable\n* Runs both on new and older Linux distributions including:\n  CentOS 6, CentOS 7, CentOS 8, Ubuntu 14, Ubuntu 16, Ubuntu 18, Ubuntu 20,\n  Ubuntu 21, Alpine, Fedora, etc\n\n## Python 2 and Python 3\n\nSince v1.3.0, udocker supports Python 2.7 and Python \u003e= 3.6.\nThe original udocker v1.1.x for Python 2 is no longer maintained\nbut is still available\n[here](https://github.com/indigo-dc/udocker/tree/v1.1.8).\n\n## Syntax\n\n```txt\n        Commands:\n          search \u003crepo/expression\u003e      :Search dockerhub for container images\n          pull \u003crepo/image:tag\u003e         :Pull container image from dockerhub\n          create \u003crepo/image:tag\u003e       :Create container from a pulled image\n          run \u003ccontainer\u003e               :Execute container\n          run \u003crepo/image:tag\u003e          :Pull, create and execute container\n\n          images -l                     :List container images\n          ps -m -s                      :List created containers\n          name \u003ccontainer_id\u003e \u003cname\u003e    :Give name to container\n          rmname \u003cname\u003e                 :Delete name from container\n          rename \u003cname\u003e \u003cnew_name\u003e      :Change container name\n          clone \u003ccontainer_id\u003e          :Duplicate container\n          rm \u003ccontainer-id\u003e             :Delete container\n          rmi \u003crepo/image:tag\u003e          :Delete image\n          tag \u003crepo/image:tag\u003e \u003crepo2/image2:tag2\u003e :Tag image\n\n          import \u003ctar\u003e \u003crepo/image:tag\u003e :Import tar file (exported by docker)\n          import - \u003crepo/image:tag\u003e     :Import from stdin (exported by docker)\n          export -o \u003ctar\u003e \u003ccontainer\u003e   :Export container directory tree\n          export - \u003ccontainer\u003e          :Export container directory tree\n          load -i \u003cimagefile\u003e           :Load image from file (saved by docker)\n          load                          :Load image from stdin (saved by docker)\n          save -o \u003cimagefile\u003e \u003crepo/image:tag\u003e  :Save image with layers to file\n\n          inspect \u003crepo/image:tag\u003e      :Return low level information on image\n          inspect -p \u003ccontainer\u003e        :Return path to container location\n          verify \u003crepo/image:tag\u003e       :Verify a pulled or loaded image\n          manifest inspect \u003crepo/image:tag\u003e :Print manifest metadata\n\n          protect \u003crepo/image:tag\u003e      :Protect repository\n          unprotect \u003crepo/image:tag\u003e    :Unprotect repository\n          protect \u003ccontainer\u003e           :Protect container\n          unprotect \u003ccontainer\u003e         :Unprotect container\n\n          mkrepo \u003ctop-repo-dir\u003e         :Create another repository in location\n          setup                         :Change container execution settings\n          login                         :Login into docker repository\n          logout                        :Logout from docker repository\n\n          help                          :This help\n          run --help                    :Command specific help\n          version                       :Shows udocker version\n\n        Options common to all commands must appear before the command:\n          -D                            :Debug\n          --quiet                       :Less verbosity\n          --repo=\u003cdirectory\u003e            :Use repository at directory\n          --insecure                    :Allow insecure non authenticated https\n          --allow-root                  :Allow execution by root NOT recommended\n```\n\n## Examples\n\nSome examples of usage:\n\nSearch container images in dockerhub and listing tags.\n\n```bash\nudocker search  fedora\nudocker search  ubuntu\nudocker search  debian\n\nudocker search --list-tags ubuntu\n```\n\nPull from dockerhub and list the pulled images.\n\n```bash\nudocker pull   fedora:39\nudocker pull   busybox\nudocker pull   iscampos/openqcd\nudocker images\n```\n\nPull from a registry other than dockerhub.\n\n```bash\nudocker search  quay.io/bio\nudocker search  --list-tags  quay.io/biocontainers/scikit-bio\nudocker pull    quay.io/biocontainers/scikit-bio:0.2.3--np112py35_0\nudocker images\n```\n\nPull a different architecture such as arm64 instead of amd64.\n\n```bash\nudocker manifest inspect centos/centos8\nudocker pull --platform=linux/arm64 centos/centos8\nudocker tag centos/centos8  mycentos/centos8:arm64\n```\n\nCreate a container from a pulled image, assign a name to the created\ncontainer and run it. A created container can be run multiple times\nuntil it is explicitly removed. Files modified or added to the container\nremain available across executions until the container is removed.\n\n```bash\nudocker create --name=myfed  fedora:29\nudocker run  myfed  cat /etc/redhat-release\n```\n\nThe three steps of pulling, creating and running can be also achieved\nin a single command, however this will be much slower for multiple\ninvocations of the same container, as a new container will be created\nfor each invocation. This approach will also consume more storage space.\nThe following example creates a new container for each invocation.\n\n```bash\nudocker run  fedora:29  cat /etc/redhat-release\n```\n\nExecute mounting the host /home/u457 into the container directory /home/cuser.\nNotice that you can \"mount\" any host directory inside the container.\nDepending on the execution mode the \"mount\" is implemented differently and\nmay have restrictions.\n\n```bash\nudocker run -v /home/u457:/home/cuser -w /home/user myfed  /bin/bash\nudocker run -v /var -v /proc -v /sys -v /tmp  myfed  /bin/bash\n```\n\nPlace a script in your host /tmp and execute it in the container. Notice\nthat the behavior of `--entrypoint` changed from the previous versions\nfor better compatibility with docker.\n\n```bash\nudocker run  -v /tmp  --entrypoint=\"\" myfed  /bin/bash -c 'cd /tmp; ./myscript.sh'\n\nudocker run  -v /tmp  --entrypoint=/bin/bash  myfed  -c 'cd /tmp; ./myscript.sh'\n```\n\nExecute mounting the host /var, /proc, /sys and /tmp in the same container\ndirectories. Notice that the content of these container directories will\nbe obfuscated by the host files.\n\n```bash\nudocker run -v /var -v /proc -v /sys -v /tmp  myfed  /bin/bash\n```\n\nInstall software inside the container.\n\n```bash\nudocker run  --user=root myfed  yum install -y firefox pulseaudio gnash-plugin\n```\n\nRun as some user. The usernames should exist in the container.\n\n```bash\nudocker run --user 1000:1001  myfed  /bin/id\nudocker run --user root   myfed  /bin/id\nudocker run --user jorge  myfed  /bin/id\n```\n\nRunning Firefox.\n\n```bash\nudocker run --bindhome --hostauth --hostenv \\\n   -v /sys -v /proc -v /var/run -v /dev --user=jorge --dri myfed  firefox\n```\n\nChange execution engine mode from PRoot to Fakechroot and run.\n\n```bash\nudocker setup  --execmode=F3  myfed\n\nudocker run --bindhome --hostauth --hostenv \\\n   -v /sys -v /proc -v /var/run -v /dev --user=jorge --dri myfed  firefox\n```\n\nChange execution engine mode to accelerated PRoot.\n\n```bash\nudocker setup  --execmode=P1  myfed\n```\n\nChange execution engine to runc.\n\n```bash\nudocker setup  --execmode=R1  myfed\n```\n\nChange execution engine to Singularity. Requires the availability of\nSingularity in the host system.\n\n```bash\n./udocker setup  --execmode=S1  myfed\n```\n\nInstall software running as root emulation in Singularity:\n\n```bash\nudocker setup  --execmode=S1  myfed\nudocker run  --user=root myfed  yum install -y firefox pulseaudio gnash-plugin\n```\n\nChange execution to enable nvidia ready applications. Requires that\nthe nvidia drivers are installed in the host system.\n\n```bash\nudocker setup  --nvidia  mytensorflow\n```\n\n## Security\n\nBy default udocker via PRoot offers the emulation of the root user. This\nemulation mimics a real root user (e.g getuid will return 0). This is just\nan emulation no root privileges are involved. This feature makes possible\nthe execution of some tools that do not require actual privileges but which\nrefuse to work if the username or id are not root or 0. This enables for\ninstance software installation using rpm, yum or dnf inside the container.\n\nudocker does not offer robust isolation features such as the ones offered\nby docker. Therefore if the containers content is not trusted then these\ncontainers should not be executed with udocker as they will run inside the\nuser environment. For this reason udocker should not be run by privileged\nusers.\n\nContainer images and filesystems will be unpacked and stored in the user\nhome directory under `$HOME/.udocker` or other location of choice. Therefore\nthe containers data will be subjected to the same filesystem protections as\nother files owned by the user. If the containers have sensitive information\nthe files and directories should be adequately protected by the user.\n\nudocker does not require privileges and runs under the identity of the user\ninvoking it. Users can downloaded udocker and execute it without requiring\nsystem administrators intervention.\n\nudocker also provides execution with runc, crun and Singularity, these modes\nmake use of rootless namespaces and enable a normal user to execute as root\nwith the limitations that apply to user namespaces and to these tools.\n\nWhen executed by normal unprivileged users, udocker limits privilege\nescalation issues since it does not use or require system privileges.\n\n## General Limitations\n\nSince root privileges are not involved any operation that really\nrequires such privileges will not be possible. The following  are\nexamples of operations that are not possible:\n\n* accessing host protected devices and files\n* listening on TCP/IP privileged ports (range below 1024)\n* mount file-systems\n* the su command will not work\n* change the system time\n* changing routing tables, firewall rules, or network interfaces\n\nIf the containers require such privilege capabilities then docker\nshould be used instead.\n\nudocker is not meant to create containers. Creation of containers\nis better performed using docker and dockerfiles.\n\nudocker does not provide all the docker features, and is not intended\nas a docker replacement.\n\nudocker is mainly oriented at providing a run-time environment for\ncontainers execution in user space. udocker is particularly suited to\nrun user applications encapsulated in docker containers.\n\nDebugging or using strace with the PRoot engine will not work as both\nthe debuggers and PRoot use the same tracing mechanism.\n\n## Execution mode specific limitations\n\nudocker offers multiple execution modes leveraging several external tools\nsuch as PRoot (P mode), Fakechroot (F mode), runC (R mode), crun (R mode)\nand Singularity (S mode).\n\nWhen using execution Fakechroot modes such as F2, F3 and F4 the created\ncontainers cannot be moved across hosts. In this case convert back to a Pn\nmode before transfer.\nThis is not needed if the hosts are part of an homogeneous cluster where\nthe mount points and directory structure is the same. This limitation\napplies whenever the absolute realpath to the container directory changes.\n\nThe default accelerated mode of PRoot (mode P1) may exhibit problems in Linux\nkernels above 4.0 due to kernel changes and upstream issues, in this case use\nmode P2 or any of the other execution modes.\n\n```bash\n./udocker setup  --execmode=P2  my-container-id\n```\n\nThe Fakechroot modes (Fn modes) require shared libraries compiled against\nthe libc shipped with the container. udocker provides these libraries for\nseveral Linux distributions, these shared libraries are installed by\nudocker under:\n\n```bash\n$HOME/.udocker/lib/libfakechroot-*\n```\n\nThe runc and crun modes (R modes) require a kernel with user namespaces enabled.\n\nThe singularity mode (S mode) requires the availability of Singularity in\nthe host system. Singularity is not shipped with udocker.\n\n## Metadata generation\n\nThe `codemeta.json` metadata file was initially generated with `codemetapy`\npackage:\n\n```bash\ncodemetapy udocker --with-orcid --affiliation \"LIP Lisbon\" \\\n  --buildInstructions \"https://https://github.com/indigo-dc/udocker/blob/master/docs/installation_manual.md#3-source-code-and-build\" \\\n  --citation \"https://doi.org/10.1016/j.cpc.2018.05.021\" \\\n  --codeRepository \"https://github.com/indigo-dc/udocker\" \\\n  --contIntegration \"https://jenkins.eosc-synergy.eu/job/indigo-dc/job/udocker/job/master/\" --contributor \"Mario David\" \\\n  --copyrightHolder \"LIP\"  --copyrightYear \"2016\" --creator \"Jorge Gomes\" \\\n  --dateCreated \"2021-05-26\" --maintainer \"Jorge Gomes\" \\\n  --readme \"https://github.com/indigo-dc/udocker/blob/master/README.md\" \\\n  --referencePublication \"https://doi.org/10.1016/j.cpc.2018.05.021\" \\\n  --releaseNotes \"https://github.com/indigo-dc/udocker/blob/master/changelog\" \\\n  -O codemeta.json\n```\n\nFurther updates may be needed to add the correct values in the metadata file.\n\n## Contributing\n\nSee: [Contributing](CONTRIBUTING.md)\n\n## Citing\n\nSee: [Citing](CITING.md)\n\nWhen citing udocker please use the following:\n\n* Jorge Gomes, Emanuele Bagnaschi, Isabel Campos, Mario David,\n  Luís Alves, João Martins, João Pina, Alvaro López-García, Pablo Orviz,\n  Enabling rootless Linux Containers in multi-user environments: The udocker\n  tool, Computer Physics Communications, Available online 6 June 2018,\n  ISSN 0010-4655, \u003chttps://doi.org/10.1016/j.cpc.2018.05.021\u003e\n\n## Licensing\n\nRedistribution, commercial use and code changes must regard all licenses\nshipped with udocker. These include the [udocker license](LICENSE) and the\nindividual licences of the external tools and libraries packaged for use\nwith udocker. For further information see the\n[software licenses section](https://indigo-dc.github.io/udocker/installation_manual.html#62-software-licenses)\nof the installation manual.\n\n## Acknowledgements\n\n* Docker \u003chttps://www.docker.com/\u003e\n* PRoot \u003chttps://proot-me.github.io/\u003e\n* Fakechroot \u003chttps://github.com/dex4er/fakechroot/wiki\u003e\n* Patchelf \u003chttps://github.com/NixOS/patchelf\u003e\n* runC \u003chttps://runc.io/\u003e\n* crun \u003chttps://github.com/containers/crun\u003e\n* Singularity \u003chttps://www.sylabs.io/\u003e\n* Open Container Initiative \u003chttps://www.opencontainers.org/\u003e\n* INDIGO DataCloud \u003chttps://www.indigo-datacloud.eu\u003e\n* DEEP-Hybrid-DataCloud \u003chttps://deep-hybrid-datacloud.eu\u003e\n* EOSC-hub \u003chttps://eosc-hub.eu\u003e\n* EGI-ACE \u003chttps://www.egi.eu/projects/egi-ace/\u003e\n* EOSC-Synergy \u003chttps://www.eosc-synergy.eu/\u003e\n* DT-Geo \u003chttps://dtgeo.eu/\u003e\n* LIP [https://www.lip.pt](https://www.lip.pt/?section=home\u0026page=homepage\u0026lang=en)\n* INCD [https://www.incd.pt](https://www.incd.pt/?lang=en)\n\nThis work was performed in the framework of the H2020 project INDIGO-Datacloud\n(RIA 653549) and further developed with co-funding by the projects EOSC-hub\n(Horizon 2020) under Grant number 777536, DEEP-Hybrid-DataCloud\n(Horizon 2020) under Grant number 777435, DT-Geo (Horizon Europe) under Grant\nnumber 101058129. Software Quality Assurance is performed with the support of\nby the project EOSC-Synergy (Horizon 2020).\nThe authors wish to acknowleadge the support of INCD-Infraestrutura Nacional de\nComputação Distribuída (funded by FCT, P2020, Lisboa2020, COMPETE and FEDER\nunder the project number 22153-01/SAICT/2016).\n","funding_links":[],"categories":["Development with Docker","Python","Containers","docker"],"sub_categories":["Wrappers"],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Findigo-dc%2Fudocker","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Findigo-dc%2Fudocker","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Findigo-dc%2Fudocker/lists"}