The old CasaOS tutorial still points in the right architectural direction—Nextcloud should use a real database for normal multi-user use—but the 2024 follow-up never solved its “Connection refused” error. The user had placed Nextcloud and MariaDB on bridge networking, yet the containers still could not connect.
The safer current pattern is to run both services in one Docker Compose project or one shared user-defined network and point Nextcloud at the MariaDB service name, not at a container IP that may change.
What the Source Thread Actually Confirmed
The original 2023 post linked to a tutorial. In 2024, another user reported SQLSTATE[HY000] [2002] Connection refused during the Nextcloud admin-account setup and suspected that the containers were not talking to each other. No later reply in the thread verified a fix.
That means “put both on bridge” should not be presented as a complete solution.
Use a Shared Compose Network and Service Name
The current Nextcloud MariaDB Compose example uses a MariaDB service named db and sets MYSQL_HOST=db for the Nextcloud container. Docker’s internal DNS then resolves the database by service name.
This is more durable than entering a temporary 172.x.x.x container address.
Match Database Credentials on Both Sides
Nextcloud needs the same database name, user and password that MariaDB creates. The current Nextcloud database guide recommends MariaDB for production-style deployments and documents the required database values.
If the hostname resolves but authentication fails, compare the MariaDB environment variables, Nextcloud values and database logs before recreating the stack.
Persist Both the Database and Nextcloud Data
Do not store MariaDB state only inside the container layer. Persist /var/lib/mysql and the Nextcloud application/data paths defined by the exact image you deploy. Back up the database together with the Nextcloud configuration and user data.
The Nextcloud deployment guide helps separate database/app storage from bulk user files.
Bottom Line
The forum’s “Connection refused” follow-up was unresolved. For a current CasaOS or ZimaOS deployment, use one Compose stack or one shared Docker network, connect Nextcloud to MariaDB by service name, keep credentials consistent, and persist both application and database storage.
