Crashes, No Sound, or Screen Glitches?
Random freezes, missing sound and display glitches usually trace back to one bad driver. Find and replace yours safely.Free scan · under a minutePC Slower Than It Used to Be?
A free scan shows the junk files, broken settings and background clutter dragging Windows down - then fixes them in one click.Free scan · Windows 10 & 11iTechGuides is reader-supported. When you buy through links on our site, we may earn an affiliate commission. As an Amazon Associate I earn from qualifying purchases. Learn more
Antihost offers Linux VPS plans with full root access, unlimited traffic on a 1 Gbps port and a 14-day free trial.
Run Uptime Kuma and MariaDB as two Compose services: the application connects to the database at the Compose hostname db, while named volumes persist Uptime Kuma data and MariaDB files. Set UPTIME_KUMA_DB_TYPE=mariadb, provide the database connection variables, and keep passwords in Docker secrets or mounted files rather than plain Compose values.
The configuration below gives you a reproducible deployment, explains initialization behavior, and shows how to troubleshoot startup, persistence, and credential problems.
How the Uptime Kuma–MariaDB Compose layout works
Docker Compose creates a private network for the services in one project. In this guide, the Uptime Kuma service is called app and the MariaDB service is called db. Docker’s internal DNS resolves db to the MariaDB container, so Uptime Kuma must use db as its database hostname. Using localhost would point back to the Uptime Kuma container itself, not to MariaDB.
The application listens on container port 3001. Mapping 3001:3001 publishes it on port 3001 of the Docker host; you can change only the host-side number if another service already uses that port. MariaDB does not need a host-port mapping because Uptime Kuma reaches it over the private Compose network.
#1 Best Overall
Services and persistent data
- app: Runs the
louislam/uptime-kuma:2image, publishes the web interface, and mounts a volume at/app/data. - db: Runs MariaDB and mounts a volume at
/var/lib/mysql, the database server’s data directory. - Named volumes: Keep monitoring configuration and database files when containers are recreated or upgraded.
- Secrets: Supply the MariaDB application and root passwords through files mounted under
/run/secrets.
Prerequisites before you start
- A host with Docker Engine and the Docker Compose plugin, so the
docker composecommand is available. - Permission to create Docker volumes, containers, and a local directory for secret files.
- A free host port, such as 3001, for the Uptime Kuma web interface.
- Two strong, different passwords: one for the MariaDB application user and one for the MariaDB root account.
- A backup location for both named volumes. Backing up only MariaDB does not preserve Uptime Kuma’s application data, and backing up only
/app/datadoes not preserve the external database.
Do not put the secret files in a publicly readable directory or commit them to source control. Restrict their host permissions before starting the stack.
Create password files without putting passwords in Compose
Create a project directory and a secrets directory, then use a hidden-input prompt to write each password. This avoids placing the password directly in shell history or in compose.yaml.
mkdir -p uptime-kuma-compose/secrets
cd uptime-kuma-compose
umask 077
read -r -s DB_PASSWORD
printf '%s' "$DB_PASSWORD" > secrets/db_password
printf 'n'
read -r -s DB_ROOT_PASSWORD
printf '%s' "$DB_ROOT_PASSWORD" > secrets/db_root_password
unset DB_PASSWORD DB_ROOT_PASSWORD
chmod 600 secrets/db_password secrets/db_root_passwordUse separate values for the two prompts. The files should contain only the password text; a trailing newline is normally harmless, but keeping the file content to the password itself avoids ambiguity.
Compose file for Uptime Kuma and MariaDB
Save this as compose.yaml in the project directory:
services:
app:
image: louislam/uptime-kuma:2
ports:
- '3001:3001'
volumes:
- uptime_kuma_data:/app/data
environment:
UPTIME_KUMA_DB_TYPE: mariadb
UPTIME_KUMA_DB_HOSTNAME: db
UPTIME_KUMA_DB_PORT: 3306
UPTIME_KUMA_DB_NAME: kuma
UPTIME_KUMA_DB_USERNAME: kuma
UPTIME_KUMA_DB_PASSWORD_FILE: /run/secrets/db_password
depends_on:
- db
secrets:
- db_password
db:
image: mariadb:11.7
environment:
MYSQL_ROOT_PASSWORD_FILE: /run/secrets/db_root_password
MYSQL_PASSWORD_FILE: /run/secrets/db_password
MYSQL_USER: kuma
MYSQL_DATABASE: kuma
volumes:
- mariadb_data:/var/lib/mysql
secrets:
- db_password
- db_root_password
volumes:
uptime_kuma_data:
mariadb_data:
secrets:
db_password:
file: ./secrets/db_password
db_root_password:
file: ./secrets/db_root_passwordThe example uses the major Uptime Kuma :2 tag and the MariaDB 11.7 tag shown in the documented deployment pattern. Treat tags as an explicit release decision: review release notes and pin versions according to your change-control policy instead of silently following an unreviewed moving tag.
What each database variable does
| Variable | Purpose | Value in this example |
|---|---|---|
UPTIME_KUMA_DB_TYPE |
Selects the database driver. | mariadb |
UPTIME_KUMA_DB_HOSTNAME |
Internal hostname of the database service. | db |
UPTIME_KUMA_DB_PORT |
MariaDB TCP port on the Compose network. | 3306 |
UPTIME_KUMA_DB_NAME |
Database schema Uptime Kuma uses. | kuma |
UPTIME_KUMA_DB_USERNAME |
MariaDB account used by Uptime Kuma. | kuma |
UPTIME_KUMA_DB_PASSWORD_FILE |
Reads the application password from a mounted secret file. | /run/secrets/db_password |
Uptime Kuma also accepts the direct password variable UPTIME_KUMA_DB_PASSWORD. The file form is preferable when the value is sensitive. The environment-variable documentation also provides file variants for the username and for the TLS certificate-authority value, allowing those values to be mounted rather than written directly in the Compose environment block.
MariaDB initialization variables
MYSQL_DATABASE creates the named database, while MYSQL_USER and MYSQL_PASSWORD_FILE create the application account and set its password during first initialization. MYSQL_ROOT_PASSWORD_FILE sets the root account password. These variables are initialization instructions, not an ongoing configuration-management system.
Start the stack and complete first-run setup
- Check that
compose.yamland both files undersecrets/are present, and verify that the secret files are mode 600 or otherwise inaccessible to unintended users. - Start both services in the background:
docker compose up -d - Inspect service state:
docker compose ps - Open
http://HOSTNAME-OR-IP:3001in a browser, replacing the host name or address with the Docker host. Complete Uptime Kuma’s first-run account setup. - If the application starts before MariaDB is ready, inspect both logs and allow the database initialization to finish before diagnosing credentials:
docker compose logs app docker compose logs db
depends_on establishes startup ordering but does not prove that MariaDB is accepting connections. A short period in which the database initializes, followed by an application connection retry or restart, is different from a persistent authentication or hostname error.
Persistence, upgrades, and backups
Why both volumes are required
Mount /app/data for Uptime Kuma and /var/lib/mysql for MariaDB. Removing either volume can make the deployment appear to lose data even though the containers themselves start normally. Container recreation does not remove named volumes, but an explicit volume deletion does.
Initialization happens only for a new MariaDB directory
MariaDB’s official image applies MYSQL_DATABASE, MYSQL_USER, and password initialization variables when the data directory is empty. Once mariadb_data contains an initialized database, changing those variables in compose.yaml does not rewrite the existing users, passwords, or schema. To change an existing password, use MariaDB account-management procedures inside the running database; do not expect an environment edit to perform that change.
The Tool Desk
Outbyte PC Repair FREERepair Windows errors before they cause bigger problemsFix Now →Outbyte Driver Updater FREEFix the driver behind crashes, sound loss and screen glitchesFind Drivers →Back up and restore as a pair
Back up the Uptime Kuma volume and the MariaDB volume, or use a database-aware dump for MariaDB alongside a copy of /app/data. Test restoration on an isolated Compose project before relying on the backup. A backup that has never been restored is an assumption, not a recovery plan. Stop writers or use a consistent database backup method so the database copy is transactionally usable.
Upgrade discipline
- Review the release notes for both images before changing tags.
- Take fresh backups of both data stores.
- Record the current image tags and Compose file.
- Upgrade one controlled change at a time and inspect logs after startup.
- Keep the previous image tags available for a rollback plan, while recognizing that database migrations may require a tested downgrade strategy.
Using secrets and environment files safely
Compose supports ordinary environment entries and an env_file for convenient non-secret settings. Those mechanisms are useful for values such as a port or pool limit, but a password in an env file is still a password in a host file that may be copied, logged, or accidentally committed. Docker secrets and the MariaDB image’s *_FILE variables keep sensitive values in mounted files instead.
For Uptime Kuma, use UPTIME_KUMA_DB_PASSWORD_FILE rather than UPTIME_KUMA_DB_PASSWORD. Where supported by the Uptime Kuma environment table, the corresponding file forms can be used for the database username and certificate-authority value. For MariaDB, use MYSQL_ROOT_PASSWORD_FILE and MYSQL_PASSWORD_FILE as shown above.
Connection tuning and TLS options
The default database pool maximum is 10 connections according to Uptime Kuma’s environment-variable table. Leave that default unless monitoring volume and MariaDB capacity justify a change; increasing a pool consumes more database connections and does not automatically improve probe latency.
Uptime Kuma supports optional MariaDB SSL settings. Configure the documented SSL key, certificate, and certificate-authority values when your database requires encrypted or verified TLS connections. If the certificate authority is sensitive or operationally managed as a file, use the documented CA file variant instead of embedding certificate content in Compose. Ensure the mounted path exists inside the app container, not merely on the Docker host.
Troubleshooting by symptom
The app reports that it cannot resolve the database host
Confirm that the hostname is exactly the Compose service name, db in this file. Do not use localhost, the host’s IP address, or a name that exists only in your local DNS. Check that both services belong to the same Compose project and that the database container is running.
Best Value
Authentication fails after editing a password
Check which volume is mounted at /var/lib/mysql. If it already contains data, MariaDB will not reapply the initialization variables. Verify the existing account password using an authorized administrative procedure, update the Uptime Kuma secret file, and recreate or restart the application container so it reads the new file.
The database or user was not created
Read the database logs and inspect the contents of the initialized volume state. An interrupted first start, an unreadable secret file, or a reused non-empty volume can prevent the expected initialization behavior. Do not delete the volume casually: that destroys the existing database. Preserve it and resolve the initialization or account issue deliberately.
Recommended Free Tools
The app starts but data disappears after recreation
Run docker compose config and verify that both named volumes are declared and mounted at the expected paths. A typo in a volume name can create a new empty volume, making the deployment look reset while the original data still exists elsewhere.
SQLite is being considered instead
Uptime Kuma supports both SQLite and MariaDB. SQLite is simpler because it avoids a separate database service, but the official installation guidance warns that it depends on POSIX file-lock support and can be problematic on filesystems such as NFS. If you retain SQLite, place its data on a local directory or volume with working file locks. MariaDB adds service, credential, and backup complexity, yet separates database storage and is a better fit when you have accepted that operational overhead.
| Decision factor | SQLite | MariaDB |
|---|---|---|
| Operational complexity | One application service and one data path. | Application plus a database service, credentials, and readiness checks. |
| Concurrency behavior | Single-file locking makes filesystem behavior important. | Server-based connections support multiple clients and separate connection management. |
| Backup workflow | Protect the SQLite data file or Uptime Kuma data volume. | Protect both the database using a consistent method and the Uptime Kuma data volume. |
| Filesystem requirement | Requires reliable POSIX file locks; NFS can be problematic. | MariaDB stores files in its own container volume, but that volume still needs durable storage and backups. |
| When it fits | A small, single-host deployment where a separate database is unnecessary. | A deployment where a dedicated database service and its operational work are acceptable. |
The official documentation does not establish a performance benchmark showing that one option is universally faster. Choose based on storage behavior, recovery practices, concurrency needs, and whether operating MariaDB is justified for your installation.
Quick Recap
Operational checklist
- Use
dbas the internal hostname and port 3306 unless your MariaDB service is intentionally changed. - Persist
/app/dataand/var/lib/mysqlwith named volumes or equivalently durable storage. - Keep application and root passwords separate, stored in restricted secret files.
- Remember that MariaDB initialization variables affect a new data directory only.
- Review logs and database readiness before changing credentials.
- Back up and test restoration of both data stores before image upgrades.
- Review image tags rather than silently adopting an untested build.
Product prices and availability are accurate as of the date/time indicated and are subject to change. Any price and availability information displayed on Amazon at the time of purchase will apply.
Do these 3 things before closing this tab:
1Fix the driver behind crashes, sound loss and screen glitches2Repair Windows errors before they cause bigger problems3Scan for outdated or missing drivers - takes under a minute
