# bitnami/minideb: a Debian base image that is never built from a Dockerfile

> minideb is a trimmed Debian root filesystem published as bitnami/minideb and used as the base for Bitnami's language and infrastructure images. It is assembled by debootstrap and a tarball import rather than a Dockerfile, rebuilt daily from the Debian archive, and it deliberately carries no patches of its own.

**bitnami/minideb** — A small image based on Debian designed for use in containers

- Repository: https://github.com/bitnami/minideb
- Website: https://bitnami.com
- Stars: 2,215 · Forks: 294
- Language: Shell
- License: Apache-2.0
- Published: 2026-09-30 · Updated: 2026-09-30 · Language: en
- Canonical page: https://hysenlabs.com/projects/bitnami-minideb

## debootstrap, mkimage, and a tarball that docker import turns into an image

The first surprise is that there is no Dockerfile. The top-level files are a Makefile and a row of small scripts, buildall, buildone, debootstrap/, dockerdiff, import, mkimage, pre-build.sh, pushmanifest, pushone, qemu_build, shellcheck and test, with no Dockerfile among them and no build directory committed. What the Makefile shows is the actual pipeline. A pattern rule takes a release name as its target, makes a build directory, and runs ./mkimage with an output path ending in .tar, so the artifact of a build is a root filesystem tarball rather than a layered image. The test target then does something that explains the design: it pipes that tarball into docker import to produce an image, and runs a test script against it. Importing a tarball is how a filesystem becomes an image, and it produces a single layer with no build history, no environment metadata and no way to inspect the steps that created it. That is the mechanism behind the size claim, and it is also the trade: you cannot read a Dockerfile to see what went in, you read the scripts. The scripts are small and shellcheck sits in the tree as the linting gate, which is a reasonable substitute for a build file you can read at a glance.

## What gets removed, and the Essential package tax you pay for it

The README is explicit about the two categories of removal. Packages that are rarely needed inside a container go first, hardware-related things and init systems among them. Then files that are rarely needed go: documentation, man pages, locales and caches. The image stays on glibc rather than a smaller C library, which the README gives as the reason for wide compatibility, and it keeps apt rather than replacing it with a static binary, so you inherit a large package catalogue instead of a minimal one. The cost of that bargain is stated in the compatibility section, and it is not hypothetical. Because some packages Debian marks Essential have been removed, packages you install may not always install or work correctly, and the workaround the project offers is to work out which package is missing and name it explicitly alongside the ones you actually wanted. In practice that means a build log with a dependency error on a package you never asked for, and a Dockerfile that accumulates hand-named extras copied from a previous failure. For an image you intend to rebuild on a schedule, that is a recurring cost rather than a one-off, and the README asks you to file an issue when you hit it so the removal set can be reconsidered.

## install_packages instead of apt, and what the retry does not fix

The one piece of tooling minideb adds is an install_packages command, and the README lists three things it does for you. It installs the packages you name, skipping prompts. It cleans up the apt metadata afterwards, and the stated reason is keeping the image small. And it retries when apt fails, with the explanation that a package can fail to download because of a network issue and that retrying may fix it, which the README says is particularly useful in an automated build pipeline. Using it is a one-liner:

```bash
install_packages apache2 memcached
```

The retry is the part to understand correctly. It addresses a transport failure, not a broken package, so a genuine dependency problem will simply fail again on the second attempt, and a build that succeeds intermittently is a build you cannot trust to have tested what you think it tested. The other two behaviours are what make the helper worth having over a raw apt line, since the metadata cleanup is the step people forget and the one that decides how much of the apt cache ships in your layer. Comparing the two ways to get an image is where the practical comparison lies. A distroless or Alpine base gives you a smaller image and no package manager at all, so anything you add means copying binaries in and managing their libraries yourself; minideb is larger and hands you apt. For an image whose dependencies change on a security cadence rather than on a release schedule, that is usually the right way round, and for an image with three static binaries in it, it is not.

## CVE scanners will report findings, and the tracker is the answer

The security section is the most important page in this README, and it is unusually blunt. The images are built daily with the Debian security release enabled, so they contain any update released more than twenty four hours earlier, which sets a floor on how fast a patch can appear and means the newest image can still be behind by a day. Then the harder part. Debian does not fix every CVE that affects its packages, so a scanner will find vulnerabilities in a minideb image that nobody is going to fix. The project's position is that it will not patch these directly, because patching them would break compatibility with Debian, so a CVE that Debian does not fix stays in minideb too. The documented way to judge a finding is the Debian security tracker, which records whether Debian intends to release a fix. The inverse case has a clear procedure too: if a vulnerability is fixed in Debian but still present in the latest minideb image, that is not intentional and an issue should be filed. For a team with a scanner in CI this is a policy decision rather than a technical one, because the finding will keep firing on every build and the only durable answer is a documented exception referencing the tracker, not a suppression nobody wrote down.

## sudo make, a local minideb:trixie tag, and a sed with a trailing space

Building the image yourself needs a Debian based machine and root, and the README says so before it shows the commands. The Makefile makes the three targets easy to separate:

```bash
sudo make
sudo make trixie
sudo make test-trixie
```

The first builds every supported release, the second one release, the third imports the resulting tarball and runs the test script. Two details in the Makefile matter more than they look. The test target imports to minideb with the release name as its tag, so what lands on your machine is a local image called minideb:trixie, not the published bitnami/minideb:trixie, and a script that assumes the published name will be testing something other than what it thinks. The targets are also guarded by marker files rather than being unconditional: build depends on .installed-requirements, which runs pre-build.sh once and is then touched into existence, and the qemu marker works the same way with install-qemu.sh. So clean, which removes the build directory, and clobber, which additionally removes the installed-requirements marker, do different amounts of work, and the second is the one that forces the pre-build step to run again. Running with podman instead of docker is handled by editing the scripts rather than by a flag:

```bash
sed -i "s/docker /podman /g" buildone dockerdiff import test
```

The pattern is given as four named scripts, and note that the search string ends with a space, so this substitutes the word docker only where it is followed by one, and leaves anything else alone.

## qemu_build for foreign architectures, limited to AMD64 and ARM64

Cross architecture builds go through emulation rather than through a build machine of the target type. The README describes qemu_build as a simple script that starts a QEMU instance for the target architecture and builds the image inside it, and the invocation names both the release and the architecture:

```bash
./qemu_build trixie arm64
```

The result is imported locally through the Docker CLI under a tag made of the distribution and the architecture, so that run produces bitnami/minideb:trixie-arm64 locally. Two limitations are stated, and they are worth taking at face value. The script can only be run on Debian based distributions, so the emulated path is unavailable on the macOS laptops many developers use, which is a different constraint from the sudo requirement on the native build. And it supports AMD64 and ARM64 targets only, so there is no route here to 32-bit ARM even though the native distribution scripts include a linux-arm7 target. The README does not say how long an emulated build takes, nor how the artifact compares to the officially published one, and it makes no claim that the two are identical. If your pipeline needs a multi architecture image, the daily published tags with their manifest list are the path the project actually documents, and the emulated script is a tool for looking at a foreign architecture rather than for producing something to ship.

## Daily images with no GitHub releases, under an Apache-2.0 file naming Broadcom

Versioning works in a way that surprises people who arrive from GitHub. The repository publishes no GitHub releases at all, and the last push was on 2026-09-07. What moves is the image: the README points at the tag list on Docker Hub, where a tag exists per Debian release, and the visible ones are latest and trixie, with bookworm named as a build target in the Makefile examples. Releases are therefore continuous rather than versioned, and the unit of upgrade is the tag, which means a deployment pinning a tag gets new content under the same name as soon as the daily rebuild lands. The tag list is the changelog, and there is no other. Licensing is straightforward but the naming in the file is not. The repository is Apache-2.0 with the copyright line naming 2025 and Broadcom, with a note that the term refers to Broadcom Inc. and its subsidiaries, while the badge at the top of the README still refers to bitnami by VMware. So the code grant is a standard permissive one and unambiguous, while the corporate name on the project has changed underneath it, which matters if your own review process records vendor identity. The project also keeps a security policy and a code of conduct at the top level, and the README routes both image build security issues and upstream fixes through the same issue tracker.

## Conclusion

minideb is the right base when your image needs a real package manager and a small layer count, because install_packages gives you apt with the metadata already cleaned up, and the image points at the Debian archive rather than a curated mirror that might fall behind. It is the wrong base when your build depends on packages Debian has marked Essential and minideb has removed, since those installs may fail and the documented workaround is naming the missing package by hand in every layer. Before adopting it, settle two questions with your own process. First, what your vulnerability scanner will do with an image that intentionally carries no patches of its own, because the README's answer for a reported CVE is the Debian security tracker rather than a Minideb release. Second, whether the local image you build with sudo make test-trixie is the image you deploy, since that target tags minideb:trixie while the published image is bitnami/minideb:trixie, and the two names are easy to confuse in a script.

## FAQ

### How do I pull a specific Debian release of bitnami/minideb?

The README shows docker run --rm -it bitnami/minideb:latest for the current image and docker run --rm -it bitnami/minideb:trixie for a named Debian release, with a tag list on Docker Hub for the others. There is no version number in the tag, since the images are rebuilt daily and the repository publishes no GitHub releases.

### Why does apt fail to install a package in a minideb image?

Some packages Debian marks Essential have been removed to reduce image size, so a package you install may not install or work correctly. The documented workaround is to identify the missing package and install it explicitly alongside the packages you wanted.

### What does install_packages do that a plain apt command would not?

It installs the named packages without prompting, cleans up the apt metadata afterwards to keep the image small, and retries when apt fails, which the README attributes to transient download problems in automated builds. The retry addresses network failures, not broken packages.

### Why does my vulnerability scanner report findings on a minideb image?

The project does not patch vulnerabilities in minideb directly, to stay compatible with Debian, so any CVE Debian has not fixed remains in the image and the scanner will keep reporting it. The README directs you to the Debian security tracker to see whether Debian intends to release a fix, and asks for an issue if a vulnerability is fixed in Debian but still present in the latest image.

### Can I build minideb without Docker?

Yes, with podman instead of docker, by editing the scripts. The README gives a single command that substitutes the word in the buildone, dockerdiff, import and test scripts. A separate QEMU based path exists for foreign architectures, limited to Debian hosts and to AMD64 or ARM64 targets.

## Sources

- [bitnami/minideb on GitHub](https://github.com/bitnami/minideb)
- [Issues](https://github.com/bitnami/minideb/issues)
- [License: Apache-2.0](https://github.com/bitnami/minideb/blob/master/LICENSE)
- [Project website](https://bitnami.com)
- [README](https://github.com/bitnami/minideb/blob/master/README.md)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/bitnami-minideb