Deploying MariaDB on Unraid

Most self-hosted applications need a database to store their data. Rather than running a separate database inside every container, a better approach is to deploy one shared MariaDB instance that all your services can connect to. This tutorial walks you through deploying MariaDB on Unraid using Docker Compose and setting it up as a shared resource on core_net.

Executive Summary

#

By the end of this tutorial you will have a MariaDB (an open-source relational database, a type of software that stores and retrieves structured data) container running on your Unraid server. It will store its data in a persistent volume so data survives container restarts, use environment variables for credentials, and be reachable by name from any other container on core_net. Every subsequent tutorial in this series that needs a database will connect to this shared instance.

Prerequisites

#

Implementation

#

Step 1: Understand what MariaDB is and why you need it

#

MariaDB is a relational database management system (RDBMS). An RDBMS stores data in structured tables with rows and columns, similar to a spreadsheet, but designed for fast querying and reliable storage at scale. MariaDB is a community-developed fork of MySQL, which means it is compatible with MySQL in almost every way while being fully open source.

Many popular self-hosted applications require a database to function. Applications like Vaultwarden, Mealie, and LuckPerms all need somewhere to store their data persistently. Running a single shared MariaDB instance is more efficient than spinning up a separate database for each app.

In this setup, MariaDB will:

• Run as a container named mariadb on core_net
• Be reachable from other containers using the hostname mariadb
• Store all data in /mnt/user/appdata/mariadb on your Unraid server
• Use a root password and a default database you define in the .env file

Step 2: Create the stack directory

#

Create the directory for the database stack:

mkdir -p /mnt/user/compose/database

This stack will eventually hold MariaDB, PostgreSQL, and Redis as sibling services. Grouping them together keeps your compose directory organized.

Step 3: Create the appdata directory

#

MariaDB stores its database files on disk. Create the directory where this data will live:

mkdir -p /mnt/user/appdata/mariadb

This path will be mounted into the container as a volume. When the container is stopped, updated, or recreated, the data remains on disk and is remounted automatically.

Step 4: Add the stack to Compose Manager Plus

#

1. In the Unraid web UI, click the Docker tab.
2. Scroll down to the Compose section and click Add New Stack.
3. Set the Stack Name to database.
4. Add a description like Shared database services: MariaDB.
5. Click Advanced Options and set the Indirect Path to /mnt/user/compose/database/.
6. Click Create.

The stack editor will open. You will write the compose file and .env file in the next steps.

Step 5: Write the compose file

#

Click the Compose tab in the stack editor. Clear any placeholder content and paste the following:

services:
  mariadb:
    image: mariadb:11
    container_name: mariadb
    restart: unless-stopped
    environment:
      MYSQL_ROOT_PASSWORD: ${MYSQL_ROOT_PASSWORD}
      MYSQL_DATABASE: ${MYSQL_DATABASE}
      MYSQL_USER: ${MYSQL_USER}
      MYSQL_PASSWORD: ${MYSQL_PASSWORD}
      TZ: ${TZ}
    volumes:
      - ${APPDATA_ROOT}/mariadb:/var/lib/mysql
    networks:
      - core_net

networks:
  core_net:
    external: true

A few notes on this configuration:

Step 6: Write the .env file

#

Click the .ENV tab. Paste the following, replacing the placeholder values:

TZ=America/Phoenix
APPDATA_ROOT=/mnt/user/appdata
MYSQL_ROOT_PASSWORD=change_this_root_password
MYSQL_DATABASE=shared
MYSQL_USER=dbuser
MYSQL_PASSWORD=change_this_db_password

Replace both passwords with strong, unique values before saving. The root password gives full control over all databases. The user password is what individual apps will use to connect. Use a password manager to generate and store these.

Replace America/Phoenix with your timezone. A full list is available at en.wikipedia.org/wiki/List_of_tz_database_time_zones.

Click Save All when done.

Step 7: Start the stack

#

Close the editor. Back on the Docker tab, right-click the database stack row and select Pull & Up. Confirm by clicking Update in the dialog.

The progress terminal will show MariaDB pulling its image layers and then starting. The first boot takes slightly longer than subsequent starts because MariaDB initializes the database files from scratch. When you see the container listed as started in the Docker tab, MariaDB is ready.

Step 8: Verify MariaDB is running

#

Click the mariadb container row in the Docker Containers section and select Logs. You should see output ending with a line similar to:

[Note] mariadbd: ready for connections.

This confirms the database server started successfully and is accepting connections.

Step 9: Verify connectivity from another container

#

The real test is confirming that another container on core_net can reach MariaDB by name. Open a terminal and run a temporary container on core_net to test the connection:

docker run --rm --network core_net mariadb:11 \
  mariadb -h mariadb -u dbuser -p shared

When prompted, enter the MYSQL_PASSWORD value you set in the .env file. If you see a MariaDB [shared]> prompt, the connection is working. Type exit to close it.

Note: If you do not want to test from the command line, you can verify connectivity later when you deploy Adminer in Post #13, which provides a web-based UI for connecting to MariaDB.

Step 10: Enable Autostart

#

On the Compose section of the Docker tab, toggle the Autostart switch on the database stack row. This ensures MariaDB starts automatically when Unraid boots, before any application containers that depend on it.

Order matters. Make sure the core stack (which creates core_net) is also set to Autostart and appears above the database stack in the list. Compose Manager Plus starts stacks in the order they are listed.

Lab Notes & Troubleshooting

#

Container exits immediately after starting. Check the logs with the container log viewer. The most common cause is a missing or malformed environment variable, particularly MYSQL_ROOT_PASSWORD. MariaDB refuses to start without it.

“Access denied for user” error when connecting. Double-check that the username and password in your connection string exactly match what is in the .env file. Passwords are case-sensitive.

“Can’t connect to server” error from another container. Confirm the connecting container is on core_net by running docker network inspect core_net and checking the Containers section. Also confirm the hostname in the connection string is mariadb, which matches the container_name in the compose file.

Data is gone after recreating the container. Verify that APPDATA_ROOT in your .env file points to a real path on your server and that the /mnt/user/appdata/mariadb directory exists and is not empty. The volume mount is what makes data persist.

I need to create additional databases for other apps. Connect to MariaDB using the test command from Step 9 and run:

CREATE DATABASE app_name;
GRANT ALL PRIVILEGES ON app_name.* TO 'dbuser'@'%';
FLUSH PRIVILEGES;

Replace app_name with the name of the database you need.

Summary

#

You now have a shared MariaDB instance running on core_net that any container on the same network can reach using the hostname mariadb. Data persists in /mnt/user/appdata/mariadb across container restarts and updates. Every application in this series that needs a MySQL-compatible database will connect to this instance rather than running its own.

Next Step: Deploying PostgreSQL on Unraid