MAILWIZZ • DOCKER

How to Install MailWizz on Docker: Complete Guide

By Abhishek Sharma · Published 2026-08-21 · Last reviewed 2026-08-21

Abhishek SharmaEditor & email infrastructure writerView author profile →

Quick answer: Containerize MailWizz with PHP-FPM, a web server and MySQL using persistent volumes, while keeping cron and upgrades operationally safe. This guide focuses on the installation layer and deliberately separates application setup from email delivery, authentication and reputation.

Before you start

Docker can make a MailWizz deployment reproducible, but containerizing a PHP application does not remove the operational work. You still need persistent application files, a persistent database, scheduled MailWizz commands, a reverse proxy, HTTPS, backups and a safe upgrade path. The biggest mistake is treating the MailWizz container like a disposable stateless web container while its configuration and uploaded assets are stored inside the container filesystem.

Important: installation instructions can change between software releases. Use the version bundled with your license and compare the vendor's current requirements before copying commands into production. Where this article uses an adapted Caddy or Docker pattern, it is clearly labeled rather than presented as vendor certification.

What you need

Linux VPS with Docker Engine and Docker Compose.
A DNS hostname and public ports 80/443.
MailWizz license/package.
Persistent volumes for application data and MySQL.
A reverse proxy such as Caddy or Nginx.
A reliable cron/scheduler mechanism.
A delivery provider or SMTP/MTA.

Architecture

Internet → reverse proxy → PHP container → MailWizz volume → MySQL volume → delivery service

Keeping these layers separate makes troubleshooting easier. If the web dashboard works but campaigns do not send, the problem may be in cron, the queue, the delivery server or the provider rather than in the web server. Conversely, a 502 or 500 error normally belongs to the web/PHP layer.

Step-by-step installation

1. Design the containers

Separate the web/PHP runtime from MySQL and the public reverse proxy. You can use PHP-FPM behind Nginx or Caddy. Keep the database on a named volume and keep MailWizz's writable application directories persistent.

2. Prepare Docker networking

Create an internal network for PHP and MySQL and expose only the reverse proxy to the public internet. Do not publish MySQL on 0.0.0.0 unless you have a specific reason and firewall rules protecting it.

3. Build the PHP image

Install the PHP extensions required by your exact MailWizz version. Pin the PHP base image and document the package versions so a rebuild does not unexpectedly change the runtime.

4. Mount MailWizz persistently

Mount the application directory from a volume or host bind mount. Make sure upgrades can replace application files without destroying uploads or configuration. Keep the database completely separate from the application volume.

5. Create the database service

Use MySQL/MariaDB with a persistent volume and strong credentials supplied through a secret mechanism where practical. Do not commit database passwords into a public compose file.

6. Add the reverse proxy

Expose only Caddy/Nginx. The proxy forwards PHP/web requests to the application container. If using Caddy, use its php_fastcgi pattern only when PHP-FPM and the shared filesystem layout are correct.

7. Run the installer

Start the database and application services, wait for the database to become ready, then open the HTTPS hostname and complete the MailWizz installer. Verify that the application can write to its required directories.

8. Solve cron deliberately

MailWizz needs scheduled commands. In Docker, choose either a host cron that runs docker compose exec commands, a dedicated scheduler container, or another reliable scheduler. The important requirement is that the commands run at the frequencies shown by MailWizz's backend cron list.

Cron reminder: Scheduled email applications are not complete when the dashboard loads. Confirm the scheduled jobs actually execute and produce expected logs before sending a real campaign.

9. Configure delivery and bounces

Add delivery, bounce and feedback-loop servers inside MailWizz. Docker does not provide email delivery by itself. Treat the application container and the delivery layer as separate systems.

10. Back up and test upgrades

Back up both the database and persistent application data. Test an upgrade on a staging copy before changing the production image or files. After upgrades, rerun the MailWizz cron and delivery tests.

Post-install configuration

Once the installer finishes, resist the temptation to immediately import a large list and launch a campaign. First configure the sending layer, domain authentication, bounce handling and unsubscribe behavior. Your application can be perfectly healthy while the email infrastructure is not ready for production.

1. Configure the sending service

Use a delivery service or MTA that is appropriate for your sending volume and compliance requirements. Record the exact SMTP/API endpoint, credentials, region and encryption settings. Never publish credentials in screenshots, tutorials, public repositories or support tickets.

2. Authenticate the sending domain

Publish the SPF, DKIM and DMARC records required by your chosen delivery service. If the provider gives you DKIM CNAME records, use those exact values. Avoid creating multiple conflicting SPF records. Start DMARC in a monitoring mode when you are still mapping legitimate senders, then tighten the policy once authentication is verified.

3. Configure bounces and complaints

A campaign system should not keep treating permanently failing addresses as healthy subscribers. Configure the application's bounce/complaint workflow and monitor the resulting logs. If your provider exposes feedback-loop events, connect them where the application supports it.

4. Test with a small list

Send a controlled test to addresses you own at more than one mailbox provider. Check authentication results, rendering, unsubscribe behavior, tracking, bounce handling and queue processing. Only after the end-to-end workflow passes should you increase campaign volume.

Common mistakes to avoid

Installing a PHP version without checking the application's current compatibility requirements.
Using the database root account inside the application.
Making the entire application directory world-writable.
Putting passwords or AWS credentials into a public repository.
Assuming a successful login means scheduled jobs are working.
Sending a large campaign before SPF/DKIM/DMARC and bounce handling are verified.
Treating the application as the email delivery server when it actually relies on an external SMTP/API provider.
Skipping backups before upgrades.

Troubleshooting

Database connection fails on first boot

The app may start before MySQL is ready. Use a health check/retry strategy rather than assuming container startup order means database readiness.

Uploads disappear after recreation

The files were stored inside the container rather than a persistent volume. Move writable application data to persistent storage.

Cron does nothing

Verify the host/container path and PHP binary. Run the MailWizz cron command interactively inside the PHP container first.

Reverse proxy returns 502

Confirm the PHP-FPM service name/port and that the proxy and PHP container share the required application files.

Upgrade breaks the app

Restore the database and application backup, then reproduce the upgrade in staging. Pin image versions rather than automatically pulling a new PHP image.

Security checklist

Use SSH keys where possible and disable unnecessary remote access.
Keep the operating system, PHP runtime and application patched.
Use a dedicated database account.
Keep MySQL private unless remote access is explicitly required.
Use HTTPS for the administration interface.
Protect application configuration and secret files.
Back up the database and uploaded/application data.
Test restoring a backup rather than assuming it is usable.
Monitor disk, RAM, CPU, queue depth and application logs.

When should you choose this installation method?

Docker is useful when you already understand container operations and want reproducible environments. It is not automatically simpler than a VPS install. For a first MailWizz installation, traditional Nginx/PHP-FPM or cPanel may be easier; Docker becomes more attractive when you need repeatable deployments, isolation or a documented infrastructure-as-code workflow.

Final checklist

☐ DNS resolves to the server
☐ Supported PHP/runtime is installed
☐ Database and dedicated user created
☐ Application installer completed
☐ Correct file permissions applied
☐ HTTPS works
☐ Cron/worker jobs execute
☐ Sending service connected
☐ SPF/DKIM/DMARC verified
☐ Bounce/complaint processing tested
☐ Unsubscribe tested
☐ Backup created and restore plan documented
☐ Small end-to-end test campaign completed

Related installation guides

Sources & references

This guide uses the following vendor or platform documentation. Where a deployment method is an adaptation rather than vendor documentation, that distinction is stated in the article.

Editorial note: This guide was reviewed on 13 August 2026 for structure, source alignment and internal consistency. Software vendors can change requirements, commands and supported versions; verify the current release documentation before production deployment.