mariadb-docker: the official MariaDB container image

A packaging repository, not a database distribution

This repository holds the packaging of MariaDB as a container image, not the server source. It is described as the Git repository of the Docker Library Official Image for mariadb, and it is maintained by the MariaDB Foundation and Community. The image itself is consumed from Docker Hub, and the README points there for the full usage documentation.

The layout makes the versioning model obvious. Directories exist for each server line, 10.6, 10.11, 11.4, 11.8, 12.3, 13.0 and 13.1, and each of those has a matching ubi variant directory, so 10.11-ubi, 13.0-ubi and so on. Alongside them sit main/ and main-ubi/, which are the templates for the newest release, plus Dockerfile.template and Dockerfile-ubi.template as the source for generated Dockerfiles.

The shared plumbing lives in the root of the repository: docker-entrypoint.sh, docker.cnf, healthcheck.sh, update.sh, versions.json and the two Containerfile.debug and Containerfile.plugin variants. There is also a .hadolint.yaml, a .architectures-lib file, a generate-stackbrew-library.sh script and a SECURITY.md. In other words, this is a build pipeline for producing many image variants from a small number of templates, which is the right shape when the support matrix is wide.

The language of the repository is shell, and the primary language field says so, which fits an image whose real logic is a startup script rather than a running process.

The entrypoint script is the real API of the image

Most teams meet this image through the docker-entrypoint.sh script, because that is where the behaviour that differs from a plain mysqld process lives. The entrypoint is what lets a container accept environment configuration, run initialization scripts from a mounted directory, and behave correctly when the data directory is already populated.

The password reset question in the project FAQ is a good illustration of the design, because the documented answer is not a docker exec into the running server. It is to write an SQL file and mount it into the initialization directory, then start the container with that file as the init file.

[docker|podman] run --volume [path-of-initfile.sql]:/docker-entrypoint-initdb.d --volume [data]:/var/lib/mysql --init-file=/docker-entrypoint-initdb.d/initfile.sql

The SQL file itself creates the root accounts, a separate application user, and the database, then grants privileges on it.

CREATE USER IF NOT EXISTS root@localhost IDENTIFIED BY 'thisismyrootpassword';
SET PASSWORD FOR root@localhost = PASSWORD('thisismyrootpassword');
GRANT ALL ON *.* TO root@localhost WITH GRANT OPTION;
CREATE USER IF NOT EXISTS root@'%' IDENTIFIED BY 'thisismyrootpassword';
SET PASSWORD FOR root@'%' = PASSWORD('thisismyrootpassword');
GRANT ALL ON *.* TO root@'%' WITH GRANT OPTION;
CREATE USER IF NOT EXISTS myuser@'%' IDENTIFIED BY 'thisismyuserpassword';
SET PASSWORD FOR myuser@'%' = PASSWORD('thisismyuserpassword');
CREATE DATABASE IF NOT EXISTS mydatabasename;
GRANT ALL ON mydatabasename.* TO myuser@'%';

The point of the pattern is durability. The project states that after this run the changes are made and future runs can be made as you did them before, because the initialization directory is only processed on first start against an empty data directory. Note also that the file covers both root@localhost and root@'%', which is the detail people usually miss.

Why there is no Alpine image, and why the size saving is small

The absence of an Alpine variant is the most discussed decision in this repository, and the reasoning is given in detail rather than glossed over. The stated position is that container images are only created from packages directly from MariaDB, not from distribution packages, partly because of the repeatability criteria of Docker Library, and mainly because image stability depends on the image being tested using CI prior to release.

The MariaDB server developers do not test in an Alpine Linux environment, nor against musl libc on which Alpine is based, so the project says it cannot in good conscience deliver an untested implementation. It goes further: unexpected behaviours and bugs have been reported against MariaDB for musl based interfaces on architectures MariaDB simply is not tested on, and the server developers find it hard to test, diagnose and fix bugs against those environments.

There is a performance argument too. Musl's key principles favor simplicity and size over performance, and some parts of MariaDB depend heavily on the performance of libc functions, particularly the ones glibc developers optimise per architecture. Moving to musl would require benchmarking to confirm there is no degraded performance.

The size question gets a direct answer. An Alpine image would be smaller, probably by less than 100M, and a basic data directory in MariaDB exceeds that difference. The stated conclusion is that performance and reliability are not going to be sacrificed to save a comparatively small amount of storage. LinuxServer.io is named as offering an Alpine based MariaDB, with less support from the MariaDB server developers.

New architectures need CI coverage, not a pull request

The architecture policy is as strict as the base image policy, and the reasoning is the same. To support MariaDB on a new architecture, it needs to be tested in CI against that architecture before release. The documented route is to search MariaDB JIRA and create a Task requesting the architecture, or vote or watch on an existing issue, with the votes and watcher numbers on those issues used to prioritise the work.

If an architecture is accepted due to popular demand, the CI run against it results in packages that can be used in the container manifest in the same way as the currently supported architectures. The pipeline is demand driven, but the gate is a passing test.

The FAQ anticipates the obvious pushback, the case where Alpine, Debian or Distro X already supports the version, and the answer is flat: they are not going to compromise the quality of the container by providing less tested images on any architecture. The .architectures-lib file in the repository root and the per version directory listing are where you can see which combinations currently exist, so the practical check for a new platform is whether a directory for your architecture is present.

Backwards compatibility is the rule every change is measured against

The development section states the guiding constraint plainly: the development of the container image aims to provide complete backwards compatibility for existing users. If a case existed where the container previously started and behaved in a certain way, after a change it should, under the same circumstances, behave in the same way.

That is a stricter rule than most container projects adopt, and it has consequences for you as a user. Upgrading the tag of the image can change the base packages and the MariaDB patch level while leaving the entrypoint contract intact, which is what makes it safe to run the same environment variables and the same mounted volumes across versions.

It also has consequences for contributors. Changes arrive as pull requests, and the review guidelines for official images are the reference for what a good one looks like. The project requires the tests to be updated to verify the behaviour of a bug fix or feature request, and the test suite lives in the .test directory.

The examples directory shows the intended usages in practice, with compose-debug.yml and separate directories for migration from 5.7, migration from 8, asynchronous replication and semisynchronous replication. Those are the flows that break most often in real deployments, so they are the ones worth studying before you build your own compose file.

Where the source of truth sits for the image and its releases

One piece of confusion is worth sorting out early, because it comes up in every team that maintains a Dockerfile. A change merged into this repository does not necessarily appear on Docker Hub immediately, and the project explains why by pointing at the official images change lifecycle documentation.

There are three places to look. For outstanding mariadb image pull requests, the place is the official-images repository, filtered by the library/mariadb label. For the current source of truth for the mariadb image, it is the library/mariadb file in that same official-images repository, and not this repository. And for the actual usage documentation, it is the Docker Hub page for the image.

That layering is why the repository here contains templates rather than only finished Dockerfiles. The Dockerfile.template and Dockerfile-ubi.template files, the main/ and main-ubi/ directories, update.sh and versions.json together describe how the per version directories are produced and refreshed.

On maintenance state: the repository is not archived and the last push was on 2026-09-23. It publishes no GitHub releases, so the version history is not expressed as tags here, and the release information that matters for users lives on the Docker Hub page for the image.

Licence, support channels and where to file problems

The licence is GPL-2.0, recorded in the LICENSE file at the repository root. That is the licence of the packaging work in this repository. It is a separate question from the terms of the MariaDB server software you are actually running inside the container, and the two should not be conflated when you review a distribution.

Help is organised in layers. The Docker and MariaDB section of the MariaDB Knowledge Base is the main body of documentation, with a page there for asking a question, and there is a separate article on getting help with MariaDB in general. For questions from practitioners, the Database Administrators StackExchange has questions tagged with mariadb and docker.

Bugs and feature requests go to MariaDB JIRA, filed under the MDEV project and the Docker component so that they reach the right people. That is the same tracker used for the architecture requests mentioned earlier, which means an architecture gap and a packaging bug share one queue.

A last practical note for anyone evaluating this image: because the maintainers refuse untested combinations, the support matrix you get is the matrix the CI covers. Before you commit to an architecture, a base image or a version line, check the per version directories at the repository root, and check that the directory for your combination actually exists.

Editorial conclusion

Adopt the mariadb-docker image when you want a MariaDB container that the MariaDB developers actually test, on an architecture with a CI job behind it, and accept that Alpine is not an option. Do not pick it for a minimal footprint, since the maintainers state the Alpine variant would be smaller by less than 100M and refuse the trade, and do not expect a new architecture to appear without a JIRA request and CI coverage. Verify first which version directory matches your server version, whether the -ubi variant or the plain one fits your base image policy, and that your upgrade path keeps the entrypoint behaviour the same, since the project's own compatibility rule is that a container which previously started in a certain way must keep behaving that way after a change.

Frequently asked questions

Official sources

1. Issues
2. License: GPL-2.0
3. MariaDB/mariadb-docker on GitHub
4. Project website
5. README