{"id":20456672,"url":"https://github.com/jgoerzen/docker-debian-base-security","last_synced_at":"2025-04-13T04:06:12.951Z","repository":{"id":66276339,"uuid":"177852448","full_name":"jgoerzen/docker-debian-base-security","owner":"jgoerzen","description":"[read-only mirror] More complete Debian environment for Docker, security enhancements","archived":false,"fork":false,"pushed_at":"2024-07-06T02:55:41.000Z","size":132,"stargazers_count":4,"open_issues_count":0,"forks_count":1,"subscribers_count":2,"default_branch":"master","last_synced_at":"2025-04-13T04:06:00.868Z","etag":null,"topics":["debian","docker","docker-image"],"latest_commit_sha":null,"homepage":"https://salsa.debian.org/jgoerzen/docker-debian-base-security","language":"Shell","has_issues":false,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/jgoerzen.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"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":"2019-03-26T19:07:57.000Z","updated_at":"2024-07-06T02:55:45.000Z","dependencies_parsed_at":null,"dependency_job_id":"87d097e6-2df7-455b-9b37-f564d9e03dda","html_url":"https://github.com/jgoerzen/docker-debian-base-security","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jgoerzen%2Fdocker-debian-base-security","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jgoerzen%2Fdocker-debian-base-security/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jgoerzen%2Fdocker-debian-base-security/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jgoerzen%2Fdocker-debian-base-security/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/jgoerzen","download_url":"https://codeload.github.com/jgoerzen/docker-debian-base-security/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248661707,"owners_count":21141450,"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":["debian","docker","docker-image"],"created_at":"2024-11-15T11:23:33.772Z","updated_at":"2025-04-13T04:06:12.929Z","avatar_url":"https://github.com/jgoerzen.png","language":"Shell","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Debian Working System for Docker\n\n**NOTE: Github is no longer the home for this project; see the [new home on Salsa](https://salsa.debian.org/jgoerzen/docker-debian-base)**.\n\nThis image is part of the\n[docker-debian-base](https://salsa.debian.org/jgoerzen/docker-debian-base)\nimage set.\n\nThis is a simple set of images that transform the standard Docker\nDebian environment into one that provides more traditional full\nUnix APIs (including syslog, zombie process collection, etc.)\n\nDespite this, they are all very small, both in terms of disk and RAM usage.\n\nYou can find a [description of the motivation for these images](https://changelog.complete.org/archives/9794-fixing-the-problems-with-docker-images) on my blog.\n\nThis is loosely based on the concepts, but not the code, in the\n[phusion baseimage-docker](https://github.com/phusion/baseimage-docker).\nYou can look at that link for additional discussion on the motivations.\n\nYou can find the source and documentation at the [Salsa page](https://salsa.debian.org/jgoerzen/docker-debian-base)\nand automatic builds are available from [my Docker hub page](https://hub.docker.com/u/jgoerzen/).  The builds are auto-generated from Salsa CI and run at least weekly.\n\n**OUTDATED**: For stretch and jessie, these images used sysvinit instead of systemd.  If you are still using these extremely old images, consult the [old version of documentation](https://salsa.debian.org/jgoerzen/docker-debian-base/-/blob/ff9b50581f076f35c1be2b28828c98040ce57de0/README.md) for information about them.  Newer images are systemd exclusive and the information here will be incorrect for those very old ones.\n\nThe older images used sysvinit,\nnot because of any particular opinion on the merits of them, but\nrather because sysvinit did not require any kind of privileged Docker\nor cgroups access.\n\nFor newer releases, systemd contains the necessary support for running in an\nunprivileged Docker container and, as it doesn't require the hacks\nthat sysvinit does, is used there.  The systemd and sysvinit images\nprovide an identical set of features and installed software, which\ntarget the standard Linux API.\n\nHere are the images I provide from this repository:\n\n- [jgoerzen/debian-base-minimal](https://salsa.debian.org/jgoerzen/docker-debian-base-minimal) - a minimalistic base.\n  - Provides working sysvinit/systemd, syslogd, cron, anacron, at, and logrotate.\n  - syslogd is configured to output to the docker log system by default.\n- [jgoerzen/debian-base-standard](https://salsa.debian.org/jgoerzen/docker-debian-base-standard) - adds some utilities.  Contains everything above, plus:\n  - Utilities: less, nano, vim-tiny, man-db (for viewing manpages), net-tools, wget, curl, pwgen, zip, unzip\n  - Email: exim4-daemon-light, mailx\n  - Network: netcat-openbsd, socat, openssl, ssh, telnet (client)\n- [jgoerzen/debian-base-security](https://salsa.debian.org/jgoerzen/docker-debian-base-security) - A great way to keep things updated.  Contains everything above, plus:\n  - automated security patches using unattended-upgrades and needrestart\n  - debian-security-support\n  - At container initialization, runs the unattended-upgrade code path to ensure that the\n    system is up-to-date before services are exposed to the Internet.  This addresses an\n    issue wherein security patches may hit security.debian.org before Docker\n    images are refreshed, a fairly common issue with the Docker infrastructure.\n    This behavior can be suppressed with `DEBBASE_NO_STARTUP_APT` (see below).\n- [jgoerzen/debian-base-vnc](https://salsa.debian.org/jgoerzen/docker-debian-base-vnc) - For systems that need X.  debian-base-security, plus:\n  - tightvncserver, xfonts-base, lwm, xterm, xdotool, xvnc4viewer\n- [jgoerzen/debian-base-apache](https://salsa.debian.org/jgoerzen/docker-debian-base-apache) - A web server - debian-base-security, plus:\n  - apache2 plus utilities: ssl-cert\n  - LetsEncrypt options: certbot, acme-tiny\n- [jgoerzen/debian-base-apache-php](https://salsa.debian.org/jgoerzen/docker-debian-base-apache-php) - debian-base-apache, plus:\n  - libapache2-mod-php (mod-php5 on jessie)\n- [jgoerzen/debian-base-gemini](https://salsa.debian.org/jgoerzen/docker-debian-base-gemini) - debian-base-security, plus:\n  - molly-brown, twins, gmnhg, md2gmn, md2gemini\n\nMemory usage at boot (stretch):\n\n- jgoerzen/debian-base-minimal: 6MB\n- jgoerzen/debian-base-standard: 11MB\n- jgoerzen/debian-base-security: 11MB\n\n# Docker Tags\n\nThese tags are autobuilt:\n\n - latest: whatever is stable (currently bookworm, systemd)\n - bookworm: Debian bookworm (systemd)\n - bullseye: Debian bullseye (systemd)\n - buster: Debian buster (systemd) - **no longer supported, may be removed at any time**\n - stretch: Debian stretch (sysvinit) - **no longer supported, may be removed at any time**\n - jessie: Debian jessie (sysvinit) - **no longer supported, may be removed at any time**\n - sid: Debian sid (not tested; systemd)\n\n# Install\n\nYou can install with:\n\n    docker pull jgoerzen/debian-base-whatever\n\nYour Dockerfile should use CMD to run `/usr/local/bin/boot-debian-base`.\n\nWhen running, use `-t` to enable the logging to `docker logs`\n\n# Container Invocation\n\nA container should be started using these commands, among others.  See\nalso the section on environment variables, below.\n\n## Container Invocation, systemd containers (buster/bullseye/bookworm/sid)\n\nFor a host running bullseye or bookworm, or a newer cgroups and systemd, you invoke like this:\n\n    docker run -td --stop-signal=SIGRTMIN+3 \\\n      --tmpfs /run:size=100M --tmpfs /run/lock:size=100M \\\n      -v /sys/fs/cgroup:/sys/fs/cgroup:rw --cgroupns=host \\\n      --name=name jgoerzen/debian-base-whatever\n\nHere's how you invoke on a system running an older systemd on the host, with cgroups v1:\n\n    docker run -td --stop-signal=SIGRTMIN+3 \\\n      --tmpfs /run:size=100M --tmpfs /run/lock:size=100M \\\n      -v /sys/fs/cgroup:/sys/fs/cgroup:ro \\\n      --name=name jgoerzen/debian-base-whatever\n      \nbookworm is now the recommended image for all modern deployments.\n\nThe `/run` and `/run/lock` tmpfs are required by systemd.  The 100M\nsets a maximum size, not a default allocation, and serves to limit the\namount of RAM an errant process could cause the system to consume,\ndown from a default limit of 16G.\n\nNote that these images, contrary to many others out there, do NOT\nrequire `--privileged`.\n\nFor more information about the systemd/cgroups situation, consult these links\n\n- https://github.com/systemd/systemd/issues/19245\n- https://github.com/containers/podman/issues/5153\n- https://github.com/moby/moby/issues/42275\n- https://serverfault.com/questions/1053187/systemd-fails-to-run-in-a-docker-container-when-using-cgroupv2-cgroupns-priva/1054414#1054414\n- http://docs.podman.io/en/latest/markdown/podman-run.1.html#cgroupns-mode\n\n# Environment Variables\n\nThis environment variable is available for your use:\n\n - `DEBBASE_SYSLOG` defaults to `stdout`, which redirects all syslog activity\n   to the Docker infrastructure.  If you instead set it to `internal`, it will\n   use the default Debian configuration of logging to `/var/log` within the\n   container.  The configuration is applied at container start time by\n   adjusting the `/etc/syslog.conf` symlink to point to either `syslog.conf.internal` or\n   `syslog.conf.stdout`.  `syslog.conf.internal` is the default from the system.\n   `dpkg-divert` is used to force all packages' attempts to write to `/etc/syslog.conf`\n   to instead write to `/etc/syslog.conf.internal`.\n- `DEBBASE_TIMEZONE`, if set, will configure the `/etc/timezone` and `/etc/localtime`\n  files in the container to the appropriate timezone.  Set this to the desired timezone;\n  for instance, `America/Denver`.\n- `DEBBASE_SSH` defaults to `disabled`.  If you set to `enabled`, then the SSH server\n  will be run.\n- `DEBBASE_NO_STARTUP_APT` defaults to empty.  If set, it will cause images based\n  on debian-base-security to skip the apt job run at container startup.\n\n# Container initialization\n\nExecutables or scripts may be placed in `/usr/local/preinit`, which will be executed\nat container start time by `run-parts` prior to starting init.  These can\ntherefore perform container startup steps.  A script which needs to only run\nonce can delete itself after a successful run to prevent a future execution.\n\n# Orderly Shutdown\n\nThe `--stop-signal` clause in the \"Container Invocation\" section above\nhelps achieve an orderly shutdown.\n\nIf you start without `--stop-signal`, you can instead use these steps:\n\n    docker kill -s SIGRTMIN+3 container\n\n    # Then proceed with:\n    sleep 10\n    docker kill container\n\nWithin the container, you can call `poweroff` to cause the container to\nshutdown.\n\n## Advanted topic: Orderly Shutdown Mechanics\n\nBy default, `docker stop` sends the SIGTERM (and, later, SIGKILL)\nsignal to PID 1 (init) iniside a container.  Neither sysvinit nor\nsystemd act upon this signal in a useful way.  This will shut down a\ncontainer, but it will not give your shutdown scripts the chance to\nrun gracefully.  In many situations, this is fine, but it may not be\nso in all.\n\nA workaround is, howerver, readily available, without modifying init.  These\nimages are configured to perform a graceful shutdown upon receiving\n`SIGRTMIN+3`.\n\n\nWith systemd, no special code for all this is needed;\nsystemd handles it internally with no fuss.\n\n# Configuration\n\nAlthough the standard and security images run the SMTP and SSH servers,\nthey do not expose these to the Internet by default.  Both require\nsite-specific configuration before they are actually useful.\n\nBecause the SMTP service is used inside containers, but the SSH service\ngenerally is not, the SSH service is disabled by default.\n\n## Enabling or Disabling Services\n\nYou can enable or disable services using commands like this:\n\n    systemctl disable ssh\n    systemctl enable ssh\n\n(Note, that in the case of ssh, the environment variable will cause\ncommands like this to be executed automatically on each container\nstart.)\n\n## Email\n\nemail is the main thing you'd need to configure.  In the running system,\n`dpkg-reconfigure -plow exim4-config` will let you do this.\n\n## SSH\n\nSSH host keys will be generated upon first run of a container, if\nthey do not already exist.  This implies every instantiation\nof a container containing SSH will have a new random host key.\nIf you want to override this, you can of course supply your own\nfiles in `/etc/ssh` or make it a volume.\n\n# Advanced Topic: Adding these enhancements to other images\n\nSometimes, it is desirable to not have to rebuild an image entirely.\nThese images are also designed to make it easy to add the\nfunctionality to other images.  You can do this by using the support\nfor multiple FROM lines in a Dockerfile.  For instance, here's a\nsimple one I worked up:\n\n    FROM jgoerzen/debian-base-security:jessie AS debian-addons\n    \n    FROM homeassistant/home-assistant:0.63.1\n\n    COPY --from=debian-addons /usr/local/preinit/ /usr/local/preinit/\n    COPY --from=debian-addons /usr/local/bin/ /usr/local/bin/\n    COPY --from=debian-addons /usr/local/debian-base-setup/ /usr/local/debian-base-setup/\n    \n    RUN run-parts --exit-on-error --verbose /usr/local/debian-base-setup\n    CMD [\"/usr/local/bin/boot-debian-base\"]\n\nIt happens that home-assistant is based on a Python image which, in\nturn, is based on Debian jessie.  There are just those four lines that\nare needed: copying the /usr/local/preinit, bin, and debian-base-setup\ndirectories, and then the `run-parts` call.  This effectively adds all\nthe features of debian-base-security to the home-assistant image.\n\nThis works because each image that is part of the chain leading up to\nsecurity (minimal, standard, and security) performs all of its\nactivity from scripts it drops -- and leaves -- in\n`/usr/local/debian-base-setup`.  Those scripts need nothing other than\nthe files in the three directories referenced above.  By adding those\nthree directories and calling the scripts, it is easy to add these\nfeatures to other images.\n\n# Source\n\nThis is prepared by John Goerzen \u003cjgoerzen@complete.org\u003e and the source\ncan be found at https://salsa.debian.org/jgoerzen/docker-debian-base\n\n# See Also\n\nSome references to additional information:\n\n - systemd's\n   [contianer interface documentation](https://www.freedesktop.org/wiki/Software/systemd/ContainerInterface/)\n - [Article](https://developers.redhat.com/blog/2016/09/13/running-systemd-in-a-non-privileged-container/)\n   on running systemd in a container.  Highlights some of the reasons\n   to do so: providing a standard Linux API, reaping zombie processes,\n   handling of logging, not having to re-implement init, etc.  All of\n   these have already been implemented in these images with sysvinit\n   and continue with systemd.\n - [serverfault thread](https://serverfault.com/questions/607769/running-systemd-inside-a-docker-container-arch-linux)\n\n# Copyright\n\nDocker scripts, etc. are\nCopyright (c) 2017-2024 John Goerzen\nAll rights reserved.\n\nRedistribution and use in source and binary forms, with or without\nmodification, are permitted provided that the following conditions\nare met:\n1. Redistributions of source code must retain the above copyright\n   notice, this list of conditions and the following disclaimer.\n2. Redistributions in binary form must reproduce the above copyright\n   notice, this list of conditions and the following disclaimer in the\n   documentation and/or other materials provided with the distribution.\n3. Neither the name of the University nor the names of its contributors\n   may be used to endorse or promote products derived from this software\n   without specific prior written permission.\n\nTHIS SOFTWARE IS PROVIDED BY THE AUTHORS AND CONTRIBUTORS ``AS IS'' AND\nANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE\nIMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE\nARE DISCLAIMED.  IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE\nFOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL\nDAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS\nOR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)\nHOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT\nLIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY\nOUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF\nSUCH DAMAGE.\n\nAdditional software copyrights as noted.\n\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjgoerzen%2Fdocker-debian-base-security","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fjgoerzen%2Fdocker-debian-base-security","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjgoerzen%2Fdocker-debian-base-security/lists"}