{"id":20456757,"url":"https://github.com/jgoerzen/docker-debian-base","last_synced_at":"2025-04-13T04:04:43.390Z","repository":{"id":66276337,"uuid":"93770098","full_name":"jgoerzen/docker-debian-base","owner":"jgoerzen","description":"[read-only mirror] More complete Debian environment for Docker","archived":false,"fork":false,"pushed_at":"2023-06-10T16:19:56.000Z","size":163,"stargazers_count":79,"open_issues_count":0,"forks_count":12,"subscribers_count":9,"default_branch":"master","last_synced_at":"2025-04-13T04:04:13.999Z","etag":null,"topics":["apache","debian","docker","docker-debian","php","syslogd","sysvinit"],"latest_commit_sha":null,"homepage":"https://salsa.debian.org/jgoerzen/docker-debian-base/","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":"2017-06-08T16:27:00.000Z","updated_at":"2024-09-17T15:22:01.000Z","dependencies_parsed_at":"2023-03-20T13:18:16.032Z","dependency_job_id":null,"html_url":"https://github.com/jgoerzen/docker-debian-base","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","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jgoerzen%2Fdocker-debian-base/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jgoerzen%2Fdocker-debian-base/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jgoerzen%2Fdocker-debian-base/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/jgoerzen","download_url":"https://codeload.github.com/jgoerzen/docker-debian-base/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":["apache","debian","docker","docker-debian","php","syslogd","sysvinit"],"created_at":"2024-11-15T11:23:57.415Z","updated_at":"2025-04-13T04:04:43.371Z","avatar_url":"https://github.com/jgoerzen.png","language":"Shell","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**OUDATED**: For stretch and jessie, this image uses sysvinit instead of systemd,\nnot because of any particular opinion on the merits of them, but\nrather because sysvinit does not require any kind of privileged Docker\nor cgroups access.\n\nFor buster and bullseye, 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 for you.\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.  Containes 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\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 bullseye, systemd)\n - bullseye: Debian bullseye (systemd)\n - buster: Debian buster (systemd)\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/sid)\n\nHere's how you invoke for systemd (buster/bullseye) 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      \nFor a host running bullseye, or a newer cgroups and systemd, you have to use 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\nNote that the buster image has not been tested under these situations, and since bullseye is now stable, it is 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\n## Container Invocation, sysvinit containers (jessie/stretch)\n\n    docker run -td --stop-signal=SIGPWR --name=name jgoerzen/debian-base-whatever\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    # jessie or stretch use this line:\n    docker kill -s SIGPWR container\n    # bullseye, buster or sid use this one:\n    docker kill -s SIGRTMIN+3 container\n    \n    # Either way, then proceed with:\n    sleep 10\n    docker kill container\n\nWithin the container, you can call `telinit 1` (jessie/stretch) or\n`poweroff` (bullseye/buster/sid) to cause the container to shutdown.\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`SIGPWR` (jessie/stretch) or `SIGRTMIN+3` (bullseye/buster/sid).\n\nThe process for this with sysvinit is... interesting, since we are\nunable to directly kill PID 1 inside a docker container.  First, init\ncalls `/etc/init.d/powerfail`.  The powerfail script I install simply\ntells init to go to single-user mode.  This causes it to perform an\norderly shutdown of the daemons, and when it is done, it invokes\n`/sbin/sulogin`.  On an ordinary system, this prompts for the root\npassword for single-user mode.  In this environment, we instead\nsymlink /sbin/init to /bin/true, then tell init to re-exec itself.\nThis causes PID 1 to finally exit.\n\nWith sysvinit, one of the preinit scripts makes sure that `/sbin/init`\nproperly links to `/sbin/init.real` at boot time.\n\nWith systemd in bullseye/buster/sid, 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(jessie/stretch):\n\n    update-rc.d ssh disable \n    update-rc.d ssh enable\n   \nOr this (bullseye/buster/sid):\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: programs that depend on disabled scripts (stretch/jessie only)\n\n**This section pertains only to stretch/jessie; systemd in bullseye/buster/sid\n  does not have these issues.**\n\nThere are a number of scripts in `/etc/init.d` that are normally part\nof a Debian system initialization, but fail in a Docker environment.\nThey do things like set up swap space, mount filesystems, etc.  Docker\nimages typically leave those scripts in place, but they are never\ncalled because Docker systems typically don't run a real init like\nthese images do.\n\nAlthough calling the scripts produces nothing worse than harmless\nerrors, I have disabled those scripts in these images in order to\navoid putting useless error messages in people's log files.  In some\nvery rare circumstances, this may cause installation of additional\npackages to fail due to boot script dependency ordering not working\nright.  (Again, this is very rare).\n\nI saw this happen once where a package had a long chain of\ndependencies that wound up pulling in cgmanager, which died in\npostinst complaining that its init script required `mountkernfs`.  I\nworked around this in my Dockerfile like this:\n\n    update-rc.d mountkernfs.sh defaults\n    apt-get -y --no-install-recommends offending-package\n    update-rc.d -f cgmanager remove\n    update-rc.d -f mountkernfs.sh remove\n\nAlso, I have blocked systemd from accidentally being installed on the\nsystem.  There are a few packages that pull in systemd shims and so\nforth, so if you get errors about systemd not installing, try adding\n`rm /etc/apt/preferences.d/systemd` to your Dockerfile.\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-2019 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","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjgoerzen%2Fdocker-debian-base","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fjgoerzen%2Fdocker-debian-base","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjgoerzen%2Fdocker-debian-base/lists"}