VPS Tutorials
Mautic on a VPS: Docker roles, SMTP, campaigns and backups
Deploy Mautic with Docker, a supported database and Caddy. Configure web, cron and worker roles, campaign processing, SMTP authentication, consent and tracking, then test coherent backups and upgrades.

Mautic brings contact management, segments, email campaigns, forms and behavioral tracking into a self-hosted marketing platform. You control the deployment and automation rules, while taking responsibility for database operations, scheduled jobs, email reputation and recovery. Include VPS, email-provider and maintenance costs when comparing it with a managed service.
This guide uses Ubuntu 24.04, Docker Compose, a MySQL-compatible database and Caddy. The official Docker images for Mautic 5 and later use separate web, cron and worker roles. Choose a supported release and its matching examples; an older single-container recipe is not interchangeable with the current architecture.
| Resource | Test budget | Small-team planning budget |
|---|---|---|
| CPU | 2 vCPU | 4 vCPU or more |
| RAM | 2 GB | 4 GB or more |
| Disk | 30 GB SSD | 60 GB SSD or more |
| Host | Ubuntu 22.04/24.04 | Ubuntu 24.04 LTS |
| Domain | mautic.example.com | Dedicated marketing subdomain |
These are starting budgets, not throughput guarantees. Contact imports, campaign runs, reports and email workers can consume much more than the web interface. Check free -h, df -h and docker stats before sharing a VPS; see VPS sizing. Configure working A/AAAA records and keep the database private. Open only required management access and public 80/443 in the provider firewall.
sudo apt update
sudo apt install -y ca-certificates curl openssl
curl -fsSL https://get.docker.com | sudo sh
sudo usermod -aG docker "$USER"
newgrp docker
sudo mkdir -p /opt/mautic
sudo chown -R "$USER":"$USER" /opt/mautic
cd /opt/mautic
Review the convenience installer before running it as root, or use Docker's supported package method. Docker-group membership grants powerful host access.
openssl rand -hex 32
openssl rand -base64 32
Use independent random database credentials and any release-specific secrets. Keep actual values in protected configuration files, outside public repositories.
The following older service sketch shows the database and private web port. Do not use it unchanged for current official images: MAUTIC_DB_NAME and MAUTIC_RUN_CRON_JOBS are not substitutes for the currently documented database variable and container roles; mounting all of /var/www/html can also hide or retain application code across upgrades.
services:
db:
image: mariadb:10.11
restart: unless-stopped
command: --character-set-server=utf8mb4 --collation-server=utf8mb4_unicode_ci
environment:
MYSQL_DATABASE: mautic
MYSQL_USER: mautic
MYSQL_PASSWORD: change-a-long-password
MYSQL_ROOT_PASSWORD: change-a-root-password
volumes:
- db_data:/var/lib/mysql
healthcheck:
test: ["CMD", "healthcheck.sh", "--connect", "--innodb_initialized"]
interval: 10s
timeout: 5s
retries: 15
mautic:
image: mautic/mautic:latest
restart: unless-stopped
depends_on:
db:
condition: service_healthy
environment:
MAUTIC_DB_HOST: db
MAUTIC_DB_NAME: mautic
MAUTIC_DB_USER: mautic
MAUTIC_DB_PASSWORD: change-a-long-password
MAUTIC_RUN_CRON_JOBS: "false"
ports:
- "127.0.0.1:8080:80"
volumes:
- mautic_data:/var/www/html
volumes:
db_data:
mautic_data:
Use the official basic example as the complete starting point:
- Download the example and its .env and .mautic_env files into a dedicated directory; record the repository revision.
- In .env, replace MYSQL_DATABASE, MYSQL_USER, MYSQL_PASSWORD and MYSQL_ROOT_PASSWORD with your chosen database settings. Use a database release supported by that Mautic version; the current basic example uses MySQL rather than promising arbitrary MariaDB compatibility.
- In .mautic_env, set MAUTIC_DB_HOST=db, MAUTIC_DB_DATABASE to the database name, MAUTIC_DB_USER and MAUTIC_DB_PASSWORD consistently. Keep all three application services on the same credentials and configuration.
- Pin all three Mautic services to the same supported Apache image tag. The documented naming includes 6.0.6-apache; verify the release you intend to run. The image maintainers currently caution against their FPM/Nginx example unless you understand its configuration.
- Keep mautic_web, mautic_cron and mautic_worker. The latter two use DOCKER_MAUTIC_ROLE=mautic_cron and mautic_worker. Set DOCKER_MAUTIC_LOAD_TEST_DATA=false.
- Change web publication to 127.0.0.1:8080:80. Persist the example's config, var/logs and docroot/media files/images paths for every role, with the correct writable ownership. Do not publish the database.
The older startup commands assume a service named mautic; adapt the name when using the official template:
docker compose config
docker compose pull
docker compose up -d
docker compose ps
docker compose logs --tail=150 mautic
In that template's directory, the corresponding checks are:
docker compose config --quiet
docker compose pull
docker compose up -d
docker compose ps
docker compose logs --tail=100 mautic_web mautic_cron mautic_worker
A running web container alone does not establish healthy cron processing or queue consumption. Protect expanded Compose output because it can contain passwords.
ssh -L 8080:127.0.0.1:8080 root@SERVER_IP
For initial setup, open http://127.0.0.1:8080 on your workstation through the tunnel. Use db as the database host in the example network, not localhost. Complete production URL tests on the final HTTPS hostname.
- Set site identity, default time zone and language.
- Create a strong administrator password and enable MFA where the installed edition supports it.
- Configure the sender address and display name.
- Set public form, landing-page and tracking URLs.
- Create a test contact and campaign.
- Verify open/click behavior, unsubscribe and failure events with test recipients; privacy protections can make opens an unreliable engagement measurement.
sudo apt install -y caddy
sudo nano /etc/caddy/Caddyfile
mautic.example.com {
encode gzip zstd
reverse_proxy 127.0.0.1:8080
header {
Strict-Transport-Security "max-age=31536000; includeSubDomains"
X-Content-Type-Options "nosniff"
X-Frame-Options "SAMEORIGIN"
}
}
sudo caddy validate --config /etc/caddy/Caddyfile
sudo systemctl reload caddy
curl -I https://mautic.example.com
Have one gateway own public 80/443 and forward to private 8080. Match Mautic's public URL and trusted-proxy settings to the final hostname. Apply HSTS/includeSubDomains only where the affected names support HTTPS. See Caddy troubleshooting.
Choose a provider that explicitly permits your marketing traffic, rather than assuming any transactional relay permits campaigns. Avoid ordinary personal-mail passwords.
- Use a dedicated sender subdomain, such as mail.example.com.
- Configure SPF, DKIM and DMARC according to the sending provider.
- Verify PTR for the actual outbound SMTP IP; a relay provider normally manages that IP's reverse DNS, not your VPS.
- Include a clear, working unsubscribe mechanism.
- Start with small, permission-based batches and respect provider rate limits.
- Monitor hard bounces, complaints and unsubscribes; suppress invalid or opted-out addresses instead of retrying them indefinitely.
Send a direct test, then test an automated campaign. Inspect authentication results, provider logs, bounces and spam placement before increasing concurrency.
The official cron and worker roles are the preferred starting point for the current images. If you deliberately schedule commands on the host instead, first inspect the installed CLI and run each job manually as the application user.
crontab -e
This older schedule illustrates periodic execution, but is not a complete current campaign pipeline:
*/5 * * * * cd /opt/mautic && docker compose exec -T mautic php bin/console mautic:campaigns:trigger --no-interaction >/dev/null 2>&1
*/10 * * * * cd /opt/mautic && docker compose exec -T mautic php bin/console mautic:segments:update --no-interaction >/dev/null 2>&1
*/5 * * * * cd /opt/mautic && docker compose exec -T mautic php bin/console mautic:emails:send --no-interaction >/dev/null 2>&1
Segment refresh, campaign membership/update and campaign triggers are separate stages. Check the release's mautic:segments:update, mautic:campaigns:update and mautic:campaigns:trigger requirements and ordering; old email-queue commands may differ from Messenger-based workers. Use the CLI list and official cron files for the actual release. Run console commands as www-data in /var/www/html when the image requires it.
- Choose one scheduler owner: built-in cron role or deliberately managed host jobs.
- Prevent overlaps with locking and sensible processing limits.
- Stagger dependent jobs and measure completion time before shortening intervals.
- Retain protected logs and monitor exit failures rather than discarding all output as in the sketch.
- Use the worker role for configured asynchronous transports; monitor queue backlog independently of web health.
- Explain purposes, cookies and retention in the privacy notice.
- Require only form fields needed for the stated purpose.
- Record marketing consent separately from service notifications.
- Provide an operational process for access, export and deletion requests.
- Keep API keys, SMTP passwords and database credentials out of browser code.
- Use HTTPS and test cross-origin behavior and security headers.
Apply the rules relevant to the people whose data you process, including regional consent and tracking requirements. If using Cloudflare, bypass caching for authenticated sessions, forms and personalized tracking responses; never cache one contact's response for another.
The older backup example assumes a particular MariaDB client and volume name:
mkdir -p /opt/mautic/backups
docker compose exec -T db mysqldump -umautic -p"YOUR_DB_PASSWORD" mautic | gzip > /opt/mautic/backups/mautic-$(date +%F).sql.gz
docker run --rm -v mautic_mautic_data:/data -v /opt/mautic/backups:/backup alpine sh -c 'tar czf /backup/mautic-data-$(date +%F).tgz -C /data .'
cp .env docker-compose.yml /opt/mautic/backups/
Use the actual database's supported dump tool and protected credentials. Enable pipefail and check success before trusting a compressed file. Inspect mounts instead of guessing a Compose-prefixed volume name. For the current layout, save the database plus config, media, .env, .mautic_env, Compose and release identifiers; logs are useful operational evidence too. Quiesce campaign writes and workers for a coherent recovery point and physical file copies.
Keep encrypted offsite copies. Restore a matching version on a clean machine and verify administrator login, contacts, forms, campaigns, email templates and unsubscribe links. Keep sending/tracking jobs disabled or use test recipients during the drill to avoid duplicate campaigns. Follow the restore-drill guide.
docker compose config > /opt/mautic/backups/compose-$(date +%F).yaml
docker compose pull
docker compose up -d
docker compose ps
docker compose logs --tail=200 mautic
Pin the old and new versions, back up first, and test required migrations in a separate instance. Do not follow latest unattended. A database migrated forward may require restoring its pre-upgrade backup to roll back; changing only the image is insufficient.
docker compose ps
docker compose logs --tail=200 mautic
sudo journalctl -u caddy -n 100 --no-pager
ss -lntp | grep -E ':8080|:80|:443'
With the current template, inspect mautic_web instead of the older service name. Check private 8080, Caddy's upstream, the final public URL, proxy trust and HTTPS cookies.
Run the relevant command manually and inspect its exit status. Verify scheduler ownership, Docker access, application user, campaign-update stage, database locks and queue backlog. A shorter cron interval does not repair a failing job.
Look for overlapping host/container schedulers, multiple consumers with inconsistent configuration, provider limits and bounce/complaint records. Export necessary audit data before removing contacts; preserve unsubscribe history.
- Domain, HTTPS, login and form submissions work.
- SMTP, SPF, DKIM, DMARC and the sender IP's PTR are verified.
- Segments, campaign stages and queues run and are monitored.
- Database and internal ports stay private; administration has appropriate access restrictions.
- Configuration, database and media have encrypted offsite backups.
- A separate instance has passed a safe restore drill.
- Release, migration and rollback procedures are recorded.
Begin with a small test audience and validate the full consent-to-unsubscribe lifecycle before expanding a campaign.