Welcome to our basic tutorial on how to install and run MariaDB as a Docker container. According to Docker website, “Docker is an open platform for developing, shipping, and running applications“. A container on the hand “is a standard unit of software that packages up code and all its dependencies so the application runs quickly and reliably from one computing environment to another. A Docker container image is a lightweight, standalone, executable package of software that includes everything needed to run an application: code, runtime, system tools, system libraries and settings“.
Install and Run MariaDB as a Docker Container
Install Docker Engine
Before you can install and run MariaDB as a docker container, you first need to have installed Docker Engine on your system. Follow the links below to install Docker Engine on CentOS 8/Ubuntu 20.04 systems;
Every docker container is based off a specific image. Docker image contains everything that is necessary to run a container and is therefore a series of instructions that defines how an application is run.
You can build your own Docker image or simply utilize the images that the community have created. You can find the images at the Docker Hub.
In this tutorial, we will be utilizing the community available Docker images.
First off, you need to identify the name of the specific MariaDB Docker Image. To search for the image on the docker hub, simply run the command below;
docker search mariadb
You will get a ton of MariaDB images that have been created;
NAME DESCRIPTION STARS OFFICIAL AUTOMATED mariadb MariaDB is a community-developed fork of MyS… 3572 [OK] linuxserver/mariadb A Mariadb container, brought to you by Linux… 151 bitnami/mariadb Bitnami MariaDB Docker Image 120 [OK] toughiq/mariadb-cluster Dockerized Automated MariaDB Galera Cluster … 41 [OK] ...
Usually, an image with no prefix is considered official docker hub image, stable and being maintained. It also contains [OK] on the Official column. Therefore, we will pull the first image from the list above.
To download the Docker Image, you use the
docker pull <name-of-the-image> command. In this case, our image name is
docker pull mariadb
The command downloads the image to your system, if doesn’t already exist.
By default, when you pull a docker image, the latest version of it is downloaded. If you need to download other versions of MariaDB Docker Images, for example, MariaDB 10.3 Docker Image, simply use the command;
docker pull mariadb:10.3
You can see a wide range of tags you can use on Docker Hub MariaDB page.
List Downloaded Docker Images
You can list locally available images using the
docker images command.
REPOSITORY TAG IMAGE ID CREATED SIZE mariadb latest 8075b7694a2d 8 days ago 407MB
We have the latest MariaDB Docker Image downloaded.
Once you have the Docker image in place, you can then create and run a docker container based on the image.
docker run <options> <image-name> is the Docker command for running Docker containers.
When running a MariaDB container, you need to specify one of following environment variables:
MYSQL_ROOT_PASSWORD: specifies the password that will be set for the MariaDB
MYSQL_ALLOW_EMPTY_PASSWORD: sets an empty password for MariaDB root user account (optional). Takes the values, yes or no
MYSQL_RANDOM_ROOT_PASSWORD: Sets a random password for MariaDB root user account (optional). Takes the values, yes or no
In our case here, the name of the image is,
latest being the tag);
docker run --name mariadbdemo -e MYSQL_ROOT_PASSWORD=password -d mariadb
The command above basically creates and run (in the background,
-d) the MariaDB Docker container based on the latest image version available, sets the MariaDB database root password to password (
-e MYSQL_ROOT_PASSWORD=password) and the name of the container as
--name mariadbdemo, random names are usually set for containers if you don’t specify the name).
If you have other versions of MariaDB Docker Images, you can specify the tags to run a container based on that specific image. For example, assuming we had MariaDB 10.4 image and we would like to run a container based on that image, you could specify the tag as,
docker run --name mariadbdemo -d -e MYSQL_ROOT_PASSWORD=password mariadb:10.4
docker run --help for more options.
Once you have run a container, you can list them using the
docker ps command.
CONTAINER ID IMAGE COMMAND CREATED STATUS PORTS NAMES ce03099cfffa mariadb "docker-entrypoint.s…" 43 seconds ago Up 39 seconds 3306/tcp mariadbdemo
To list all running and stopped containers, use
docker ps -a command.
To get just the running container IDs;
docker ps -q
Checking MariaDB Container Logs
You can use
docker logs <name-or-container-id> command;
docker logs mariadbdemo
docker logs ce03099cfffa
Accessing MariaDB Docker Container
Your MariaDB docker container is now running in the background. You can access it by:
- Launching the interactive shell of the container
- Logging into MariaDB Docker container using mysql client from your host via the docker network.
To launch an interactive bash shell for the MariaDB docker container, use the
docker exec -it <name-of the container|container-id> <shell>.
docker exec -it mariadbdemo bash
This takes you to container interactive bash shell;
You can as well login to your MariaDB container using mysql client on your host.
For this, you need to install MySQL client. For example, on Ubuntu systems, you can install MySQL client by running the command
apt install mysql-client
Next, obtain the IP address assigned to your MariaDB container. To obtain an IP address of the container, use the
docker inspect <name-of-the-container|container-id> command which provides a complete details about the container.
docker inspect mariadbdemo | grep IPAddress
"SecondaryIPAddresses": null, "IPAddress": "172.17.0.2", "IPAddress": "172.17.0.2",
In this case, our MariaDB container is assigned an IP address of 172.17.0.2.
To use the MySQL host client to connect to our container;
mysql -u root -p -h 172.17.0.2
The command assumes that the container is listening on a default port, 3306.
You will need to use the password that you specified with the
MYSQL_ROOT_PASSWORD variable when running the container above.
Enter password: password Welcome to the MySQL monitor. Commands end with ; or \g. Your MySQL connection id is 5 Server version: 5.5.5-10.5.4-MariaDB-1:10.5.4+maria~focal mariadb.org binary distribution Copyright (c) 2000, 2020, Oracle and/or its affiliates. All rights reserved. Oracle is a registered trademark of Oracle Corporation and/or its affiliates. Other names may be trademarks of their respective owners. Type 'help;' or '\h' for help. Type '\c' to clear the current input statement. mysql>
Within the shell, you can now administer your MariaDB as you would when running on a host.
NOTE: The IP address assigned to your docker container is dynamic and if you happen to restart the container, it will be assigned a new/different IP address within the docker network.
If you have some external applications that needs to access your database running on MariaDB container, you need to expose the container port for external via the host system. By default, the container is only accessible within the host system
For example, our MariaDB container is listening on the default port 3306.
If you check your listening ports on your host for MariaDB port, you wont find any;
ss -altnp | grep 3306
To expose a container port, use the
docker run options,
-p <host-port>:<container-port>. See example command below to expose MariaDB container port 3306 via the host using the same port;
docker run --name mariadbdemoport -p 3306:3306 -e MYSQL_ROOT_PASSWORD=password -d mariadb
If you need to use the same names for the container, just stop the existing container and remove it and relaunch new container using the same name.
Let us verify the port exposure
CONTAINER ID IMAGE COMMAND CREATED STATUS PORTS NAMES 3489ce131cce mariadb "docker-entrypoint.s…" 4 minutes ago Up 2 seconds 0.0.0.0:3306->3306/tcp mariadbdemoport ce03099cfffa mariadb "docker-entrypoint.s…" About an hour ago Up 40 seconds 3306/tcp mariadbdemo
If you check on the PORTS column, you realize for our new container, the container port is exposed on port 3306 on the host and is listening on all interfaces;
If you need to specify the IP address of the host, use
Checking the listening ports on the host again;
ss -altnp | grep 3306
LISTEN 0 4096 *:3306 *:*
If you need to map the container port to a dynamic host port, use the option;
docker run --name mariadbdemo-dport -p 3306 -e MYSQL_ROOT_PASSWORD=password -d mariadb
CONTAINER ID IMAGE COMMAND CREATED STATUS PORTS NAMES bee9f036aedd mariadb "docker-entrypoint.s…" 8 seconds ago Up 3 seconds 0.0.0.0:32768->3306/tcp mariadbdemo-dport 3489ce131cce mariadb "docker-entrypoint.s…" 12 minutes ago Up 7 minutes 0.0.0.0:3306->3306/tcp mariadbdemoport ce03099cfffa mariadb "docker-entrypoint.s…" About an hour ago Up 8 minutes 3306/tcp mariadbdemo
As you can see, the container port is exposed on dynamic port 32768.
You can always find what dynamic port the container port is mapped to using the
docker port command;
docker port mariadbdemo-dport
3306/tcp -> 0.0.0.0:32768
Setting Persisting Data Volume for MariaDB Docker Container
When a container is removed, all if its data it had written to its internal volumes are removed as well. To ensure data is persistent across container deletes, you can map MariaDB Docker container internal volume to some host directory.
To bind an internal Docker volume to an external host volume, use the
-v <host-directory>:<container-directory> option of
docker run command.
The default data directory for MariaDB container is
For example, if I want the container data to be written to my host directory
/opt/mariadb/data, the first create the directory and run a container mapping the data directories using the
mkdir -p /opt/mariadb/data
docker run --name mariadbdemo-volume -v /opt/mariadb/data:/var/lib/mysql -e MYSQL_ROOT_PASSWORD=password -d mariadb
Therefore, any container data that is written to the container data directory,
/var/lib/mysql, will be written to the data directory on host,
/opt/mariadb/data at the same time.
Stop, Pause, Restart Remove Docker Container
To stop a running container, use the
docker stop command;
docker stop [option] <name|id>
docker stop mariadbdemo
You can stop all containers using their ids;
docker stop $(docker ps -q)
Once you are done with a container, you can choose to remove it;
docker rm [option] <name|id>
docker rm mariadbdemo
To force removal;
docker rm --force mariadbdemo
To pause the container;
docker pause mariadbdemo
docker restart mariadbdemo
To list docker volumes;
docker volume ls
Find specific docker container volume using
docker inspect command.
Remove specific volume;
docker volume rm volume-name
That marks the end of our guide on how to install and run MariaDB as a Docker Container.