{"id":15395421,"url":"https://github.com/creemama/docker-run-non-root","last_synced_at":"2026-04-02T02:05:23.521Z","repository":{"id":66939116,"uuid":"145237172","full_name":"creemama/docker-run-non-root","owner":"creemama","description":"Run Docker containers with a non-root user by default","archived":false,"fork":false,"pushed_at":"2019-03-17T17:15:20.000Z","size":34,"stargazers_count":11,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"master","last_synced_at":"2025-04-16T00:42:03.473Z","etag":null,"topics":["docker","linux","non-root","root","shell","shell-scripts"],"latest_commit_sha":null,"homepage":"https://github.com/creemama/run-non-root","language":"Dockerfile","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/creemama.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2018-08-18T16:55:27.000Z","updated_at":"2023-12-11T10:46:28.000Z","dependencies_parsed_at":null,"dependency_job_id":"eaa28c08-57a1-4504-882a-1b210cc44da8","html_url":"https://github.com/creemama/docker-run-non-root","commit_stats":{"total_commits":37,"total_committers":1,"mean_commits":37.0,"dds":0.0,"last_synced_commit":"68be2a7901bb6979cb93a16ef56a660d4587b3f3"},"previous_names":[],"tags_count":15,"template":false,"template_full_name":null,"purl":"pkg:github/creemama/docker-run-non-root","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/creemama%2Fdocker-run-non-root","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/creemama%2Fdocker-run-non-root/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/creemama%2Fdocker-run-non-root/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/creemama%2Fdocker-run-non-root/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/creemama","download_url":"https://codeload.github.com/creemama/docker-run-non-root/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/creemama%2Fdocker-run-non-root/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":31294398,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-02T01:43:37.129Z","status":"online","status_checked_at":"2026-04-02T02:00:08.535Z","response_time":89,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"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":["docker","linux","non-root","root","shell","shell-scripts"],"created_at":"2024-10-01T15:28:16.066Z","updated_at":"2026-04-02T02:05:23.496Z","avatar_url":"https://github.com/creemama.png","language":"Dockerfile","funding_links":[],"categories":[],"sub_categories":[],"readme":"# run-non-root\n\n\u003e Run Docker containers with a non-root user by default.\n\n[![Travis CI Build Status](https://img.shields.io/travis/creemama/run-non-root/master.svg?style=flat-square\u0026label=Travis+CI)](https://travis-ci.org/creemama/run-non-root) [![run-non-root Version](https://img.shields.io/github/tag/creemama/run-non-root.svg?style=flat-square)](https://github.com/creemama/docker-run-non-root) [![run-non-root on Docker Hub](https://img.shields.io/docker/automated/jrottenberg/ffmpeg.svg?style=flat-square)](https://hub.docker.com/r/creemama/run-non-root/)\n\n`run-non-root` runs Linux commands as a non-root user, creating a non-root user if necessary.\n\nThis allows us to\n\n**run Docker containers with a non-root user by default**\n\nwithout having to specify a `USER` with hardcoded UIDs and GIDs in our Dockerfiles.\n\n# Supported tags and respective `Dockerfile` links\n\n * [`1.5.1-alpine`, `1.5-alpine`, `1-alpine`, `1.5.1`, `1.5`, `1`, `latest` *(alpine/Dockerfile)*](https://github.com/creemama/docker-run-non-root/blob/1.5.1/alpine/Dockerfile)\n * [`1.5.1-centos`, `1.5-centos`, `1-centos`, `centos` *(centos/Dockerfile)*](https://github.com/creemama/docker-run-non-root/blob/1.5.1/centos/Dockerfile)\n * [`1.5.1-debian`, `1.5-debian`, `1-debian`, `debian` *(debian/Dockerfile)*](https://github.com/creemama/docker-run-non-root/blob/1.5.1/debian/Dockerfile)\n * [`1.5.1-fedora`, `1.5-fedora`, `1-fedora`, `fedora` *(fedora/Dockerfile)*](https://github.com/creemama/docker-run-non-root/blob/1.5.1/fedora/Dockerfile)\n * [`1.5.1-ubuntu`, `1.5-ubuntu`, `1-ubuntu`, `ubuntu` *(ubuntu/Dockerfile)*](https://github.com/creemama/docker-run-non-root/blob/1.5.1/ubuntu/Dockerfile)\n\n**Examples**\n\n * [`1.5.1-certbot` *(certbot/Dockerfile)*](https://github.com/creemama/docker-run-non-root/blob/1.5.1/certbot/Dockerfile)\n * [`1.5.1-certbot-renew-cron` *(certbot-renew-cron/Dockerfile)*](https://github.com/creemama/docker-run-non-root/blob/1.5.1/certbot-renew-cron/Dockerfile)\n * [`1.5.1-node-10.15.3` *(node/Dockerfile)*](https://github.com/creemama/docker-run-non-root/blob/cc2a7a3e804b2ac88e8dd9240e1b9ece7f79e13b/node/Dockerfile)\n\n# run-non-root\n\n[run-non-root](https://github.com/creemama/run-non-root) is a shell script that runs Linux commands as a non-root user.\n\n```\nUsage:\n  run-non-root [options] [--] [COMMAND] [ARGS...]\n\nRun Linux commands as a non-root user, creating a non-root user if necessary.\n\nOptions:\n  -c, --chown             Colon-separated list of files and directories to run\n                          \"chown USERNAME:GID\" on before executing the\n                          command; you can use this option multiple times\n                          instead of using a colon-separated list; run-non-root\n                          ignores this option if you are already running as a\n                          non-root user; unlike -p this option is non-recursive.\n  -d, --debug             Output debug information; using --quiet does not\n                          silence debug output. Double up (-dd) for more output.\n  -f, --group GROUP_NAME  The group name to use when executing the command; the\n                          default group name is USERNAME or nonroot; this\n                          option is ignored if we are already running as a\n                          non-root user or if the GID already exists; this\n                          option overrides the RUN_NON_ROOT_GROUP environment\n                          variable.\n  -g, --gid GID           The group ID to use when executing the command; the\n                          default GID is UID or a new ID determined by\n                          groupadd; this option is ignored if we are already\n                          running as a non-root user; this option overrides the\n                          RUN_NON_ROOT_GID environment variable.\n  -h, --help              Output this help message and exit.\n  -i, --init              Run an init (the tini command) that forwards signals\n                          and reaps processes; this matches the docker run\n                          option --init.\n  -p, --path              Colon-separated list of directories to run\n                          \"chown -R USERNAME:GID\" on before executing the\n                          command; you can use this option multiple times\n                          instead of using a colon-separated list; if a\n                          directory does not exist, run-non-root attempts to\n                          create it; run-non-root ignores this option if you\n                          are already running as a non-root user; unlike -c\n                          this option is recursive.\n  -q, --quiet             Do not output \"Running ( COMMAND ) as USER_INFO ...\"\n                          or warnings; this option does not silence --debug\n                          output.\n  -t, --user USERNAME     The username to use when executing the command; the\n                          default is nonroot; this option is ignored if we are\n                          already running as a non-root user or if the UID\n                          already exists; this option overrides the\n                          RUN_NON_ROOT_USER environment variable.\n  -u, --uid UID           The user ID to use when executing the command; the\n                          default UID is GID or a new ID determined by\n                          useraddd; this option is ignored if we are already\n                          running as a non-root user; this option overrides the\n                          RUN_NON_ROOT_UID environment variable.\n  -v, --version           Ouput the version number of run-non-root.\n\nEnvironment Variables:\n  RUN_NON_ROOT_COMMAND    The command to execute if a command is not given; the\n                          default is bash; if bash does not exist, the default\n                          is sh.\n  RUN_NON_ROOT_GID        The group ID to use when executing the command; see\n                          the --gid option for more info.\n  RUN_NON_ROOT_GROUP      The group name to use when executing the command; see\n                          the --group option for more info.\n  RUN_NON_ROOT_UID        The user ID to use when executing the command; see\n                          the --uid option for more info.\n  RUN_NON_ROOT_USER       The username to use when executing the command; see\n                          the --user option for more info.\n\nExamples:\n  # Run bash or sh as a non-root user.\n  run-non-root\n\n  # Run id as a non-root user.\n  run-non-root -- id\n\n  # Run id as a non-root user using options and the given user specification.\n  run-non-root -f ec2-user -g 1000 -t ec2-user -u 1000 -- id\n\n  # Run id as a non-root user using environment variables\n  # and the given user specification.\n  export RUN_NON_ROOT_GID=1000\n  export RUN_NON_ROOT_GROUP=ec2-user\n  export RUN_NON_ROOT_UID=1000\n  export RUN_NON_ROOT_USER=ec2-user\n  run-non-root -- id\n```\n\n# Examples\n\n```sh\n# Run sh as a non-root user.\ndocker run -it --rm creemama/run-non-root:latest\n# Output: Running ( su-exec nonroot:1000 sh ) as uid=1000(nonroot) gid=1000(nonroot) groups=1000(nonroot) ...\n\n# Run id as a non-root user.\ndocker run -it --rm creemama/run-non-root:latest --q -- id\n# Output: uid=1000(nonroot) gid=1000(nonroot) groups=1000(nonroot)\n\n# Run id as a non-root user using options and the given user specification.\ndocker run -it --rm creemama/run-non-root:latest \\\n  -f ec2-user -g 1000 -q -t ec2-user -u 1000 -- id\n# Output: uid=1000(ec2-user) gid=1000(ec2-user) groups=1000(ec2-user)\n\n# Run id as a non-root user using environment variables\n# and the given user specification.\ndocker run \\\n  -e RUN_NON_ROOT_GID=1000 \\\n  -e RUN_NON_ROOT_GROUP=ec2-user \\\n  -e RUN_NON_ROOT_UID=1000 \\\n  -e RUN_NON_ROOT_USER=ec2-user \\\n  -it --rm creemama/run-non-root:latest \\\n  -q -- id\n# Output: uid=1000(ec2-user) gid=1000(ec2-user) groups=1000(ec2-user)\n\n# Run as yourself.\ndocker run -it --rm creemama/run-non-root:latest \\\n  -f $(id -gn) -g $(id -g) -t $(id -nu) -u $(id -u) \\\n  -- id\n\n# Run as root if you need to.\ndocker run -it --rm creemama/run-non-root:latest -qu 0 -- whoami\n# Output: root\n```\n\n# Docker and `run-non-root`\n\nAs we all know, [processes in containers should not run as root](https://medium.com/@mccode/processes-in-containers-should-not-run-as-root-2feae3f0df3b).\n\nThere are several approaches to run as a non-root user.\n\n**Specify a `USER` in your Dockerfile**\n\nOne approach is to create a user via `useradd` and specify a [`USER`](https://docs.docker.com/engine/reference/builder/#user) in your Dockerfile.\n\n```\nFROM debian:stretch\n\nRUN groupadd -g 999 appuser \u0026\u0026 \\\n    useradd -r -u 999 -g appuser appuser\nUSER appuser\n\nCMD [\"cat\", \"/tmp/secrets.txt\"]\n```\n\nThe upside to this approach is that the container, by default, runs as `appuser` instead of root.\n\nThe downside is that `appuser` has a specific UID and GID that [you cannot change without some work](https://www.cyberciti.biz/faq/linux-change-user-group-uid-gid-for-all-owned-files/).\n\n**Specify a UID when starting your container**\n\nAnother approach is to use the `-u` or `--user` option.\n\n```sh\ndocker run -it --rm \\\n  --user $(id -u):$(id -g) \\               # Run as the given user.\n  --volume $(app):/app \\                   # Mount the source code.\n  --workdir /app \\                         # Set the working dir.\n  my-docker/my-build-environment:latest \\  # The build image\n  make assets                              # The command\n```\n\nThe upside to this approach is that you have control of the specific UID and GID of the user running the container.\n\nThe [downside](https://medium.com/redbubble/running-a-docker-container-as-a-non-root-user-7d2e00f8ee15) is that your user may be HOME-less and nameless. In other words,\nthe user might have no home directory and `whoami` might not find a name for the user.\n\nBasically, unless the UID you specified is in the `getent passwd` list, your container does not know about the user you specified.\n\n**Specify `run-non-root` as your `ENTRYPOINT`**\n\nUsing `run-non-root` as the `ENTRYPOINT` of your container overcomes the downsides of the aforementioned approaches.\n\nFrom a base image:\n```\nFROM alpine:3.9\n\n...\n\nADD https://raw.githubusercontent.com/creemama/run-non-root/master/run-non-root.sh /usr/local/bin/run-non-root\nRUN chmod +rx /usr/local/bin/run-non-root\n\nENTRYPOINT [\"run-non-root\"]\nCMD [\"--\", \"/your/program\", \"-and\", \"-its\", \"arguments\"]\n```\n\nFrom one of run-non-root's images:\n```\nFROM creemama/run-non-root:1.5.1-alpine\n\n...\n\nCMD [\"--\", \"/your/program\", \"-and\", \"-its\", \"arguments\"]\n```\n\nWith this approach, you do not have to specify `USER` in your Dockerfile or use the `--user` option when calling `docker run`. Your container runs as a non-root user by default.\n\nIf `run-non-root` creates the non-root user (which is nonroot by default), this user will have a home directory, and `whoami` will return that user's name.\n\n# `tini`\n\nUse `run-non-root` in conjunction with [`tini`](https://github.com/krallin/tini) to handle zombie reaping and signal forwarding by using the `--init` option.\n\n```sh\n$ docker run -it --rm creemama/run-non-root:latest --init -q -- ps aux\nPID   USER     TIME  COMMAND\n    1 nonroot   0:00 tini -- ps aux\n   17 nonroot   0:00 ps aux\n```\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcreemama%2Fdocker-run-non-root","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fcreemama%2Fdocker-run-non-root","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcreemama%2Fdocker-run-non-root/lists"}