What’s actually slowing this PC down?
Pick the symptom - the matching free tool is one click away.
Run Uptime Kuma as an app container and MariaDB as a separate db container on the same Docker Compose network. Set UPTIME_KUMA_DB_TYPE=mariadb, point the app at the hostname db on port 3306, and persist both /app/data and /var/lib/mysql in named volumes. Store passwords in Docker secrets or mounted files rather than writing them directly into compose.yaml.
Antihost offers Linux VPS plans with full root access, unlimited traffic on a 1 Gbps port and a 14-day free trial.
The configuration below gives you a durable deployment, explains MariaDB initialization behavior, and shows how to verify, back up, update, and troubleshoot the stack.
As an Amazon Associate I earn from qualifying purchases.
What the Compose topology looks like
Compose creates a private network for the project. Uptime Kuma uses the service name db as MariaDB’s DNS hostname; it must not use localhost, because localhost inside the app container refers to the app container itself. The host only needs to publish Uptime Kuma’s web port. MariaDB can remain reachable solely on the internal Compose network.
- app: the Uptime Kuma web interface and monitoring process.
- db: MariaDB, with its data directory mounted at
/var/lib/mysql. - uptime_kuma_data: a volume for Uptime Kuma’s configuration, monitor definitions, and other application data at
/app/data. - mariadb_data: a volume containing the MariaDB data directory.
- secrets: files supplied to both services at runtime so passwords do not appear as ordinary environment values.
You need Docker Engine with the Compose plugin, a host port available for the web UI (3001 in the example), enough disk space for two persistent volumes, and two different strong passwords: one for the MariaDB application account and one for the MariaDB root account.
#1 Best Overall
- Includes Raspberry Pi 4 4GB Model B with 1.5GHz 64-bit quad-core CPU (4GB RAM)
- Includes Pre-Loaded 32GB EVO+ Micro SD Card (Class 10), USB MicroSD Card Reader
- CanaKit Premium High-Gloss Raspberry Pi 4 Case with Integrated Fan Mount, CanaKit Low Noise Bearing System Fan
- CanaKit 3.5A USB-C Raspberry Pi 4 Power Supply (US Plug) with Noise Filter, Set of Heat Sinks, Display Cable - 6 foot (Supports up to 4K60p)
- CanaKit USB-C PiSwitch (On/Off Power Switch for Raspberry Pi 4)
Compose file for Uptime Kuma and MariaDB
Save this as compose.yaml. The image tags are examples: the configuration uses the major :2 tag for Uptime Kuma and MariaDB 11.7. Review and pin tags according to your release policy instead of silently following an unreviewed latest build.
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 two services share the database name, username, and application password. The MariaDB image creates those objects during first initialization, while Uptime Kuma reads the same application password from /run/secrets/db_password. No host port is published for MariaDB, so an external client cannot connect unless you deliberately add a port mapping.
Free tools Windows power users keep installed
One-click scans. No signup required.
Put credentials in secret files
- Create a directory beside
compose.yaml:mkdir -p secrets. - Write a long random password for the application account to
secrets/db_passwordand a different one for the root account tosecrets/db_root_password. Do not reuse either password elsewhere. - Restrict host permissions, for example with
chmod 600 secrets/db_password secrets/db_root_password, and ensure the files are excluded from version control. - Keep the filenames and paths consistent with the
file:entries and the_FILEvariables in the Compose file.
Compose also supports env_file, which is useful for non-secret settings. Passwords should instead use Docker secrets or file-based variables. The MariaDB image documents MYSQL_ROOT_PASSWORD_FILE and MYSQL_PASSWORD_FILE; Uptime Kuma documents file variants for password, username, and certificate-authority values.
Start the stack
- From the directory containing
compose.yaml, rundocker compose up -d. - Watch startup rather than assuming that
depends_onmeans the database is ready. Usedocker compose logs -f dband wait for MariaDB to finish initialization, then inspectdocker compose logs -f app. - Open
http://your-host:3001, or the host and port represented by your own port mapping, and complete Uptime Kuma’s first-run account setup. - If the app starts before MariaDB accepts connections, give the database time to become ready and restart only the app with
docker compose restart app. Keep the hostname asdb; changing it tolocalhostwill not fix a readiness delay.
The first launch may take longer while MariaDB creates the database and account. A successful Uptime Kuma setup should retain its configuration after an app restart because the data volume is mounted independently of the container filesystem.
Rank #2
- Broadcom BCM2711, quad-core Cortex-A72 (ARM v8) 64-bit SoC @ 1. 5GHz
- 2. 4 GHz and 5. 0 GHz IEEE 802. 11b/g/n/ac wireless LAN, Bluetooth 5. 0, BLE
- 2 × USB 3. 0 ports, 2 x USB 2. 0 Ports
- 2 × micro HDMI ports supproting up to 4Kp60 video resolution
- Micro SD card slot for loading operating system and data storage
Uptime Kuma MariaDB variables
These are the settings that establish the connection in the example. Keep the qualification attached to each value when adapting it to another Compose project.
| Variable | Example | Purpose |
|---|---|---|
UPTIME_KUMA_DB_TYPE |
mariadb |
Selects MariaDB instead of SQLite. |
UPTIME_KUMA_DB_HOSTNAME |
db |
Compose service hostname for MariaDB. |
UPTIME_KUMA_DB_PORT |
3306 |
MariaDB’s normal TCP port on the internal network. |
UPTIME_KUMA_DB_NAME |
kuma |
Database schema created by the MariaDB image on a new data directory. |
UPTIME_KUMA_DB_USERNAME |
kuma |
Application account used by Uptime Kuma. |
UPTIME_KUMA_DB_PASSWORD_FILE |
/run/secrets/db_password |
Reads the application password from a mounted secret file. |
UPTIME_KUMA_DB_POOL_MAX_CONNECTIONS |
10 by default | Maximum database-pool connections according to Uptime Kuma’s environment-variable table. Increase it only when workload and MariaDB capacity justify doing so. |
Uptime Kuma’s environment-variable documentation also lists optional SSL settings and _FILE variants for password, username, and CA values. Use those names when your database requires encrypted connections or when you want the username or CA material supplied as files. Do not invent a variable name from a generic MariaDB example; use the exact label documented for your Uptime Kuma release.
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 & 11Persistence and MariaDB initialization
Why both volumes are required
Mounting uptime_kuma_data:/app/data preserves Uptime Kuma’s monitors, notification settings, users, and application state. Mounting mariadb_data:/var/lib/mysql preserves the actual MariaDB database. Recreating either container without its corresponding volume can make the service appear empty even though the other container is intact.
Using MariaDB does not eliminate the need for durable storage. If you keep SQLite instead, Uptime Kuma’s installation guidance requires POSIX-compatible file locking; network filesystems such as NFS can cause problems. MariaDB changes the storage design, but it still needs a reliable persistent volume.
Rank #3
- Broadcom BCM2711, Quad core Cortex-A72 (ARM v8) 64-bit SoC @ 1.5GHz
- 1GB, 2GB, 4GB or 8GB LPDDR4-3200 SDRAM (depending on model)
- 2.4 GHz and 5.0 GHz IEEE 802.11ac wireless, Bluetooth 5.0, BLE Gigabit Ethernet
- 2 USB 3.0 ports; 2 USB 2.0 ports.
- Raspberry Pi standard 40 pin GPIO header (fully backwards compatible with previous boards)
Initialization variables are first-start settings
On an empty /var/lib/mysql, the MariaDB image uses MYSQL_DATABASE, MYSQL_USER, and the password variables to create the schema and account. Once the data directory contains a database, those variables do not reinitialize it or overwrite existing users and passwords. Editing compose.yaml later therefore does not change an already-initialized database.
If you need to change the application password, change it in MariaDB, update the secret file, and restart Uptime Kuma so both sides use the same credential. Merely changing MYSQL_PASSWORD_FILE in Compose is insufficient when the volume already exists.
Back up and restore the deployment
A useful backup plan covers both named volumes and a logical database export. Back up before changing image tags, changing credentials, or altering storage.
- Application volume: capture
uptime_kuma_datawith a Docker-volume backup method that preserves the files under/app/data. - MariaDB volume: capture
mariadb_datafor a complete physical copy, preferably while MariaDB is stopped or with a method that guarantees a consistent snapshot. - Logical export: run a MariaDB dump from the database container and store the resulting SQL file outside the container. Use the application account for normal data export or a privileged account when your recovery procedure requires it.
- Restore test: restore both volumes, start the stack in an isolated project, and confirm that monitors, users, and notification channels are present before trusting the backup.
Do not treat an export of only the MariaDB schema as a complete Uptime Kuma backup: the application volume contains configuration that is not represented by ordinary database rows.
Rank #4
- Vilros Complete Starter Kit for Pi 4 Includes Raspberry Pi 4 Model B Board and all the accessories you need to get started.
- 9-PART KIT WILL HAVE YOU READY TO GET UP AND RUNNING: Kit Includes 1. Raspberry Pi 4 Model B Board 2. Case With Easy to connect Built-in fan 3. 64GB Micro SD card Preloaded with RP OS 4. Vilros Pi 4 Compatible Power Supply with Inline on/off switch (power supply color may vary white/black) 5. Micro HDMI to Standard HDMI cable (5ft) 6. Micro SD to USB adapter to reflash card if desired 7. Neoprene Storage Bag to store all parts when not in use 8. Set of 4 Heatsinks 9. Vilros QuickStart Guide instruction booklet for Pi 4
- PASSIVE & ACTIVE COOLING: The included case is well-vented and the kit also includes a set of heatsinks with thermal stickers for easy application and a pre-installed fan to keep the board cool in any use.
- CONVENIENT ACCESSORIES: The power supply features an inline on/off switch neoprene bag that holds and protects all the parts when not in use and the QuickStart guide is updated and written for Raspberry Pi 4.
- IMPORTANT: Kit does NOT include Keyboard, Mouse or Monitor
Security hardening
- Keep the two secret files out of Git repositories, shared screenshots, and world-readable backup locations.
- Use separate passwords for the root and application accounts, and grant Uptime Kuma only the database account it needs.
- Publish port 3001 through your reverse proxy or firewall as appropriate. Do not publish port 3306 unless an external database client genuinely needs it.
- Pin image tags that you have reviewed. The example’s
mariadb:11.7andlouislam/uptime-kuma:2are not a promise that every future release is compatible with your deployment. - Protect the Uptime Kuma web interface with its own administrator account and, when exposed beyond a trusted LAN, TLS and network access controls.
MariaDB versus SQLite for Uptime Kuma
Uptime Kuma officially supports both database types. The choice is operational rather than a documented performance ranking; the available guidance does not publish a benchmark comparing them.
| Decision factor | SQLite | MariaDB |
|---|---|---|
| Operational complexity | One application service and one database file. | Two services, credentials, readiness, and database upgrades to manage. |
| Concurrency behavior | File-based locking; concurrent access depends on a filesystem with working POSIX locks. | Client/server connections with a configurable pool; the documented default pool maximum is 10. |
| Backup and restore | Protect the SQLite file and Uptime Kuma data together, while preserving file consistency. | Protect both named volumes and consider a logical MariaDB dump. |
| Filesystem requirements | Requires reliable POSIX file-lock support; problematic network filesystems should be avoided. | Uses MariaDB’s data directory in its own persistent volume. |
| When a separate service is acceptable | Best when a single-container deployment is the priority. | Useful when you already operate MariaDB, need a client/server database, or prefer database administration separate from the app. |
Troubleshooting branches
The app reports that it cannot connect
- Confirm the value is
UPTIME_KUMA_DB_HOSTNAME=db, notlocalhostor the host’s IP address. - Check that both services are on the same Compose project network and that the service is actually named
db. - Read the database logs and wait for readiness before restarting the app.
- Verify that the secret file exists on the host and is mounted at the exact path used by
UPTIME_KUMA_DB_PASSWORD_FILE.
Authentication fails after editing the password
Determine whether mariadb_data already existed. If it did, MariaDB will not apply the new initialization password. Change the account password inside MariaDB through an intentional credential-rotation procedure, then update the secret consumed by Uptime Kuma.
Quick wins for a faster PC:
Fix the driver behind crashes, sound loss and screen glitchesFind Drivers →Repair Windows errors before they cause bigger problemsFix Now →Scan for outdated or missing drivers - takes under a minuteDriver Scan →The database appears to reset or the monitors disappear
Inspect the mounts with docker compose config and confirm that the named volumes are still attached. Avoid commands or cleanup procedures that remove volumes unless you have a verified backup. A newly created volume is an empty database, so the initialization variables will create a fresh kuma schema and account.
Port 3001 is already in use
Change only the host side of the mapping, for example '8080:3001', then browse to port 8080. The container still listens on 3001, and the database settings do not change.
Best Value
- Includes Raspberry Pi 4 4GB Model B with 1.5GHz 64-bit quad-core CPU (4GB RAM)
- CanaKit 3.5A USB-C Power Supply with Noise Filter (UL Listed) specially designed for the Raspberry Pi 4 (5-foot cable)
- CanaKit USB-C PiSwitch (On/Off Power Switch)
- Set of 3 Aluminum Heat Sinks for the Raspberry Pi 4
SQLite locking errors appear in another deployment
If you are not using MariaDB and retain SQLite, move /app/data to a local disk or a volume that provides functioning POSIX locks. NFS and similar filesystems can violate the locking behavior SQLite expects.
Updating image tags safely
- Export the MariaDB database and back up both named volumes.
- Review the release notes and compatibility of the new Uptime Kuma and MariaDB tags.
- Change the tags in
compose.yamldeliberately, then pull and recreate the services with Docker Compose. - Watch MariaDB complete its startup before checking Uptime Kuma, and test a monitor, login, and notification channel.
- Keep the previous image tags available until the restored deployment has passed your checks.
Never delete the named volumes as part of an ordinary image upgrade. Container replacement and data replacement are separate operations.
Recommended Free Tools
Production checklist
- Uptime Kuma uses
UPTIME_KUMA_DB_TYPE=mariadb. - The database hostname is the Compose service name, such as
db. - The app and database use matching database name, username, and application password.
- Passwords are delivered through secrets or mounted files, not committed in plain text.
/app/dataand/var/lib/mysqlare persistent, backed-up volumes.- You have tested restoring both volumes and, ideally, a logical MariaDB dump.
- MariaDB is not publicly exposed unless there is a specific operational reason.
- Image tags are reviewed and changed through a backup-and-test process.
Bottom line
A two-service Compose project is the dependable way to run Uptime Kuma with MariaDB: use db for internal DNS, mount both data directories, initialize MariaDB only on a new volume, and supply credentials through secret files. Once readiness checks, backups, and image-tag reviews are part of your routine, the deployment is straightforward to operate and recover.
Quick Recap
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.
