200ms/mariadb_dev2 repository overview

⁠MariaDB Dev^2 container

This project is a source of 200ms/mariadb_dev2 docker image. 200ms/mariadb_dev2 belongs to a set of images that can be described as "Dev^2 suit". The idea behind this is to develop Docker images and complementing tools aimed to ease development and testing of LAMP applications.

The main goals are:

• Eliminate password hassle and boring tasks (e.g. manual account creation)
• Provide debugging out-of the box
• Add network insight capabilities

200ms/mariadb_dev2 is build on a top of Docker official 'mariadb' image. But it extends it by an extra scripting providing commands for import/export etc.

MariaDB is a community driven fork of MySQL. MySQL/MariaDB is a common database choose for multiple web projects due to its performance. MariaDB maintains high compatibility with MySQL.

Docker image can be pulled with:

docker pull 200ms/mariadb_dev2

Other images I developed as a part of 'Dev2 suit':

• 200ms/phpapache_dev2⁠ - Apache server with XDebug pre-configured and more, in fact this image is derivative of 200ms/phpapache_dev2.
• 200ms/wpapache_dev2⁠ - Wordpress with WPC-CLI and more
• 200ms/prestashop_dev2⁠ - Prestashop with helper scripts

⁠NOTE 1: 200ms/mariadb_dev2 image has NOT been tested on other OS then Linux. Therefore at this point only this OS is supported. See requirements regarding FUSE⁠

⁠NOTE 2: Some functionalities are under development, however current version is very useful support for my everyday work as developer. Feature requests, bug reports regarding this image can be reported here: BitBucket⁠

⁠FUSE and extra permissions

This image internally uses Dev2FS⁠ that requires Linux FUSE⁠ module to be loaded but also elevated privileges for each Docker container based on this image. It might be required to modprobe fuse prior to using all features of the image. Moreover it is required to run container with:

docker ... --cap-add SYS_ADMIN --device /dev/fuse ...

parameters. Or in the case of docker-compose.yaml:

services:
  proj:
    ...
    cap_add: ['SYS_ADMIN']
    devices: /dev/fuse
    ...

This elevates container's permissions allowing FUSE based Dev2FS to work.

Dev2FS has been developed to fix mismatch of shared file permissions, therefore it is actually one of the key elements of Dev2 suit.

⁠Special directory

200ms/mariadb_dev2 does permission remapping of shared files to avoid situations such as having shared files with 'mysql' uid that differ from standard permissions of a regular Linux user (usually 1000). The concept of 'Dev2 suit' is to make development smooth, thus container cares about setting appropriate privileges, so Developer can spare pointless sudo chown me:me ... commands. But a bit care must be payed before: that is to add these two docker arguments and make sure host system has FUSE kernel module loaded.

It is recommended to share host directory named for instance 'share' with

/dbdump

container's path. It is the way of sharing database import/export files with proper uid:gid guaranteed by Dev2FS.

⁠Launch

To run container issue:

docker pull 200ms/mariadb_dev2

# go to your project's directory and `mkdir *share*`
mkdir ./share
# and run container:
docker run --cap-add SYS_ADMIN --device /dev/fuse \
           -it -v $(pwd)/share:/dbdump \
           200ms/mariadb_dev2

In a case above, if 'share' directory is not created by user, Docker will do it anyway but with 'root' permissions assigned. To have a proper permissions set in a project shared directories must by simply created by a user.

⁠Default values

Container, if no settings has been overwritten (via environment variables⁠) will run with the following defaults:

• Database name: mydb
• root database user password:
• 'administrative' database user: admin /
• 'regular' database user: user / - NOTE: NOT IMPLEMENTED

administrative (admin) DB account is granted with:

• DB structure creation/modification permissions (CREATE TABLE ..., DROP TABLE ...)

• and data modification permissions: INSERT INTO ..., SELECT * ..., DELETE FROM ....

regular (user) account is limited to perform data modification operations only.

Application should use 'admin' or 'user' account depending on what suits best.

⁠Usage

MySQL credentials can be checked by calling:

docker exec <cont. name> d2mydb.sh info

If '/dbdump' volume is shared (and db dump file is located inside), database can be imported with the following command:

docker exec <cont. name> d2mydb.sh import <.sql, .sql.gz, .sql.bz2 or .sql.xz file>

Or, simpler:

docker exec <cont. name> d2mydb.sh restore

In this case the last .sql file from the list of files sorted in ascending order is loaded. It's user's responsibility to care about appropriate naming schema to ensure that the latest (desired for majority of cases) file is sorted as last, e.g.:

20240103-1032-dump.sql.gz  20240109-1443-dump.sql.gz

Database can be dumped with:

docker exec <cont. name> d2mydb.sh dump <database name> <optional file name>

or, all db's:

docker exec <cont. name> d2mydb.sh dumpall <optional file name>

If file name is skipped, default one with date stamp will be created.

for more options see:

docker exec <cont. name> d2mydb.sh help

⁠Environment Variables

Settings such as db name or credentials are available via environmental variables.

Prior to container creation, variables can be overwritten, but if skipped default values will apply.

⁠MARIADB_DATABASE / MYSQL_DATABASE / DB_NAME (default: 'mydb')

Name of the database that is to be created automatically.

[comment]: <>#### MARIADB_ADMIN / MYSQL_ADMIN / DB_ADMIN (default: 'admin') [comment]: <> [comment]: <>Name of the MariaDB user granted with a full access to created database. [comment]: <>This user is intended to be used by an application for application accounts authorized for administrative tasks. [comment]: <>An example of such a task is plugin installation - that usually requires structure altering (CREATE TABLE ...).

⁠MARIADB_USER / MYSQL_USER / DB_USER (default: 'admin')

Name of the MariaDB user granted with a full access to created database.

[comment]: <> #### MARIADB_USER / MYSQL_USER / DB_USER (default: 'user') [comment]: <> Database username granted with limited access to created database. Access includes only data modification: [comment]: <>- SELECT [comment]: <>- INSERT [comment]: <>- UPDATE [comment]: <>- DELETE [comment]: <>This user is intended to be used by an application for application accounts of regular users, or no-registered users. [comment]: <>An example is posting a comment that requires at least one database INSERT instruction.

⁠MARIADB_PASSWORD / MYSQL_PASSWORD / DB_PASS (default: )

Password for MARIADB_USER user.

⁠MARIADB_ROOT_PASSWORD / MYSQL_ROOT_PASSWORD / DB_ROOT_PASS (default: )

MariaDB's root password.

⁠MARIADB_ALLOW_EMPTY_ROOT_PASSWORD (default: NOT SET)

Set to a non-empty value, like yes, to allow container on setting-up blank password for root user. In this case MARIADB_ROOT_PASSWORD is not set with a random password, if it has been set by user it's value is ignored.

⁠MARIADB_RANDOM_ROOT_PASSWORD (default: NOT SET)

Set to non-empty value, like yes, to generate random initial password for root user. If this variable is set random password will be generated by original MariaDB docker image scripts, thus not available for Dev2.

⁠DBDUMPDIR (default: /dbdump)

Path to database dump directory. If this directory exists database import/export files are shared here.

⁠Example

Bellow more practical for dev. projects example of usage in docker-comose.yaml file:

networks:
  d2-net:
    external: false

services:
# Application container
#  ...
  db:
    image: 200ms/mariadb_dev2
    networks:
      - d2-net
    # you need it?
    ports:
      - 3306:3306
    volumes:
      - ./data:/dbdump
    cap_add: ['SYS_ADMIN']
    devices:
      - /dev/fuse