Skip to content
Klutch.sh Docs

Deploying a Mautic App

Introduction

Mautic is an open-source marketing automation platform built on PHP. Deploying Mautic with a Dockerfile on Klutch.sh delivers reproducible builds, managed secrets, and persistent storage for configs and media—all managed from klutch.sh/app. This guide covers installation, repository prep, a production-ready Dockerfile, deployment steps, Nixpacks overrides, and sample API usage.

Prerequisites

  • A Klutch.sh account (sign up)
  • A GitHub repository containing your Mautic setup and Dockerfile (GitHub is the only supported git source)
  • A MySQL/MariaDB database (deploy as a Klutch.sh TCP app on port 8000 and connect on 3306)
  • SMTP credentials for outbound emails
  • Domain ready for your Mautic instance

For onboarding, see the Quick Start.

Architecture and ports

  • Mautic runs on PHP/Apache; set the internal container port to 8080 and choose HTTP traffic.
  • Database runs separately on TCP; connect on 3306.
  • Persistent storage is required for config, media, and cache.

Repository layout

mautic/
├── Dockerfile                # Must be at repo root for auto-detection
├── config/                   # Mautic configs (persist)
├── media/                    # Uploaded assets (persist)
├── var/cache                 # Cache (persist recommended)
└── README.md

Keep secrets out of Git; store them in Klutch.sh environment variables.

Installation (local) and starter commands

Validate locally before pushing to GitHub:

Terminal window
docker build -t mautic-local .
docker run -p 8080:8080 --env-file .env mautic-local

Dockerfile for Mautic (production-ready)

Place this Dockerfile at the repo root; Klutch.sh auto-detects it (no Docker selection in the UI):

FROM mautic/mautic:latest


# Ensure Apache listens on 8080 inside the container
ENV APACHE_HTTP_PORT_NUMBER=8080


WORKDIR /var/www/html


# Copy custom plugins/themes if present
COPY plugins ./plugins


# Set correct permissions for persistent dirs
RUN mkdir -p ./config ./media ./var/cache && \
    chown -R www-data:www-data ./config ./media ./var/cache ./plugins


EXPOSE 8080
CMD ["apache2-foreground"]

Notes:

  • Add PHP extensions via docker-php-ext-install if your plugins require them.
  • Keep config/, media/, and var/cache writable; mount them as volumes.

Environment variables (Klutch.sh)

Set these in Klutch.sh before deploying:

  • MAUTIC_DB_HOST=<db-host>
  • MAUTIC_DB_USER=<db-user>
  • MAUTIC_DB_PASSWORD=<db-password>
  • MAUTIC_DB_NAME=<db-name>
  • MAUTIC_DB_TABLE_PREFIX=mautic_ (optional)
  • MAUTIC_TRUSTED_PROXIES=0.0.0.0/0
  • MAUTIC_CACHE_PATH=/var/www/html/var/cache
  • SMTP: MAUTIC_MAILER_FROM_NAME, MAUTIC_MAILER_FROM_EMAIL, MAUTIC_MAILER_HOST, MAUTIC_MAILER_PORT, MAUTIC_MAILER_USER, MAUTIC_MAILER_PASSWORD, MAUTIC_MAILER_ENCRYPTION
  • Optional URL: MAUTIC_URL=https://example-app.klutch.sh
  • APACHE_HTTP_PORT_NUMBER=8080

If you deploy without the Dockerfile and need Nixpacks overrides (PHP):

  • NIXPACKS_PHP_VERSION=8.2
  • NIXPACKS_START_CMD=apache2-foreground

Attach persistent volumes

In Klutch.sh storage settings, add mount paths and sizes (no names required):

  • /var/www/html/config — configuration and secrets.
  • /var/www/html/media — uploaded assets and files.
  • /var/www/html/var/cache — cache (recommended for performance).

Ensure these directories are writable.

Deploy Mautic on Klutch.sh (Dockerfile workflow)

  1. Push your repository—with the Dockerfile at the root—to GitHub.
  2. Open klutch.sh/app, create a project, and add an app.
  3. Select HTTP traffic and set the internal port to 8080.
  4. Add the environment variables above, including database and SMTP settings.
  5. Attach persistent volumes for /var/www/html/config, /var/www/html/media, and /var/www/html/var/cache with sizes that match your content and cache needs.
  6. Deploy. Complete the web-based installer at https://example-app.klutch.sh and connect it to your database.

Sample API usage

Obtain an access token (password grant example):

Terminal window
curl -X POST "https://example-app.klutch.sh/oauth/v2/token" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "client_id=<client_id>&client_secret=<client_secret>&grant_type=password&username=<user>&password=<pass>"

Create a contact:

Terminal window
curl -X POST "https://example-app.klutch.sh/api/contacts/new" \
  -H "Authorization: Bearer <access_token>" \
  -H "Content-Type: application/json" \
  -d '{"firstname":"Alex","lastname":"Doe","email":"alex@example.com"}'

Health checks and production tips

  • Add an HTTP probe to /index.php or /healthcheck (if enabled).
  • Enforce HTTPS at the edge; forward traffic internally to port 8080.
  • Keep plugins/themes updated and test upgrades in staging first.
  • Monitor database connections and storage; resize volumes before they fill.
  • Store secrets only in Klutch.sh and rotate them regularly.
  • Configure cron/queue processing within the container if required by your campaign cadence.

Mautic on Klutch.sh combines reproducible Docker builds with managed secrets, persistent storage, and flexible HTTP/TCP routing. With the Dockerfile at the repo root, port 8080 configured, and MySQL/MariaDB connected, you can deliver marketing automation without extra YAML or workflow overhead.