Connecting a MediaWiki container managed by Podman to a native MariaDB instance requires explicit network configuration because rootless containers cannot access services bound only to localhost. The primary failure occurs when the database refuses connections from the container’s isolated network namespace, resulting in a "Connection refused" error during the web installer or runtime initialization.
Understanding Rootless Network Isolation
By default, Podman runs containers in a user namespace that maps to your regular user ID rather than root. This security feature creates a separate network stack for each container. When you install MariaDB natively on your host machine (e.g., via
systemctl start mariadb), it typically listens on
127.0.0.1 (localhost) for security reasons. However, the Podman container does not share this loopback interface directly. From inside the container,
127.0.0.1 refers to the container itself, not the host where MariaDB is running. Therefore, attempting to connect using
localhost or
127.0.0.1 will always fail because no database service exists inside the MediaWiki container.
To resolve this, you must route traffic from the container to the host’s actual IP address. In rootless Podman environments, the host is accessible via a special DNS name or IP address provided by the CNI (Container Network Interface) plugin. Most modern distributions use
host.containers.internal as the hostname that resolves to the host’s internal IP address reachable from within the container. Alternatively, you can use the IP address assigned to the host’s virtual ethernet device, often found at
10.0.2.2 depending on the backend driver.
Configuring the Database Host
When setting up MediaWiki, you will be prompted for the database server address. Instead of entering
localhost, enter
host.containers.internal. This ensures that the connection attempt leaves the container and hits the native MariaDB instance on the host. If you are using an older version of Podman or a specific CNI setup that does not support this DNS entry, you may need to identify the host IP manually. You can find this by running
ip addr show on the host and looking for the IP associated with the bridge network, or by checking the
/etc/hosts file inside the container if it has been populated correctly.
For users managing complex reverse proxy setups, such as those involving Traefik, network visibility becomes even more critical. Understanding how containers communicate through proxies can prevent similar connectivity issues in production environments. For more details on container networking with reverse proxies, see
Setting Up Traefik for Reverse Proxy and Container Network on Tech Support Site.
Adjusting MariaDB Bind Addresses
Even if the network path is correct, MariaDB might still reject the connection if its configuration restricts incoming connections to localhost only. By default, many Linux distributions configure MariaDB to listen exclusively on
127.0.0.1 in the
my.cnf or
mariadb.conf.d files. To allow connections from the Podman container, you must modify this binding setting.
Open the MariaDB configuration file, typically located at
/etc/my.cnf.d/mariadb-server.cnf or
/etc/mysql/mariadb.conf.d/50-server.cnf. Look for the
[mysqld] section and find the
bind-address directive. Change this value from
127.0.0.1 to
0.0.0.0. This tells MariaDB to accept connections on all available network interfaces, including the virtual bridge used by Podman. After saving the file, restart the MariaDB service using
sudo systemctl restart mariadb.
If you prefer not to open MariaDB to all interfaces, you can specify the exact IP address of the Podman bridge network in the
bind-address field. This provides a tighter security posture while still allowing the necessary communication. Always ensure that the firewall on your host machine allows inbound traffic on port 3306 from the container’s subnet if external firewalls are active.
Verifying User Permissions and Authentication
Once the network and binding issues are resolved, you must ensure that the MySQL/MariaDB user configured in MediaWiki has the correct permissions to connect from the host’s perspective. When you created the database user for MediaWiki, you likely specified the host as
'localhost'. In MySQL terminology,
'localhost' implies a local socket connection, which does not work over TCP/IP networks like the one Podman uses.
You need to create or alter the user to allow connections from the host IP or any host. Run the following commands in your MariaDB client:
CREATE USER 'mediawiki_user'@'%' IDENTIFIED BY 'your_password';
GRANT ALL PRIVILEGES ON mediawiki_db.* TO 'mediawiki_user'@'%';
FLUSH PRIVILEGES;
The
'%' wildcard allows the user to connect from any IP address, including the Podman container. If you want to be more restrictive, replace
'%' with
'host.containers.internal' or the specific IP address of the host as seen from the container. Note that some newer versions of MariaDB use caching_sha2_password by default, which might cause compatibility issues with older PHP versions. If you encounter authentication errors, consider changing the password plugin to
mysql_native_password during user creation.
Common Pitfalls and Debugging Steps
If you still face connection issues, verify that the MariaDB service is actually running and listening on the expected port. Use
ss -tlnp | grep 3306 on the host to confirm the port is open and bound to
0.0.0.0 or the correct interface. Additionally, check the Podman container logs using
podman logs <container_name> for detailed error messages. Common errors include "Access denied" (indicating wrong credentials or host restrictions) and "Can't connect to MySQL server" (indicating network or binding failures).
Another frequent issue arises from SELinux policies on systems like CentOS or Fedora. If SELinux is enforcing, it may block the container from accessing the host’s network resources or the database files. You can check SELinux denials using
audit2allow or temporarily set it to permissive mode to test if it is the culprit. Remember to restore proper labels rather than disabling SELinux permanently.
For cases where MariaDB fails to start entirely due to permission errors on data directories, refer to our guide on resolving startup failures. See
MariaDB Refused to Start: Permission Denied Error Solved for troubleshooting steps related to data directory ownership and permissions.
Frequently Asked Questions
Why does MediaWiki say "Connection refused" even though MariaDB is running?
This error usually means the network path is blocked or the service is not listening on the expected interface. Verify that MariaDB is bound to
0.0.0.0 and that you are using
host.containers.internal instead of
localhost in the MediaWiki configuration.
Can I use Docker networking commands with Podman?
Podman is largely compatible with Docker CLI commands, but network namespaces differ between rootful and rootless modes. While
docker network commands work similarly, rootless Podman manages networks differently, often relying on CNI plugins. Use
podman network ls and
podman network inspect to manage networks in a rootless environment.
Is it safe to bind MariaDB to 0.0.0.0?
Binding to
0.0.0.0 exposes the database to all network interfaces, which increases the attack surface. It is safer to bind to the specific IP of your Podman bridge network or use a firewall rule to restrict access to port 3306 only from the container’s subnet.
How do I find the IP address of my Podman bridge network?
Run
podman network inspect podman (or your custom network name) and look for the
Subnet and
Gateway fields. The gateway IP is often the address you should use if
host.containers.internal is not resolving correctly.
What if I get an "Access Denied" error after fixing the network?
This indicates a credential or permission issue. Ensure the MySQL user is allowed to connect from the host IP (
'user'@'host.containers.internal' or
'user'@'%') and not just from
'user'@'localhost'. Also, verify that the password matches exactly, including case sensitivity.