mautic-stack

Maintained by Kopexa — GRC and compliance automation. Built on our hardened kopexa-grc/images.

Always up-to-date, hardened Mautic for Docker and Kubernetes.

• Image ghcr.io/kopexa-grc/mautic — Mautic 7 on the hardened php-apache base: no shell, no package manager, non-root (uid 65532), read-only root filesystem, rebuilt daily, signed (cosign), SBOM + SLSA provenance, multi-arch (amd64/arm64).
• Helm chart oci://ghcr.io/kopexa-grc/charts/mautic — web, queue workers, cron jobs, Valkey for cache and shared sessions, optional MariaDB, Ingress or Gateway API, restic backups, SAML single sign-on (Keycloak, Google Workspace, Entra ID, …), ingress and egress NetworkPolicies, Pod Security "restricted", validated values (values.schema.json).
• AI assistants via MCP — built-in MCP server at /mcp for Claude, ChatGPT and other clients, with standard OAuth 2.1 login (PKCE, dynamic client registration) against Mautic itself. The assistant reads contacts, segments, emails, campaigns and statistics, creates emails and campaigns unpublished and edits campaign flows, including running campaigns (live, see the docs). It works with the user's Mautic permissions and never publishes or sends directly.
• Built-in extensions — Postal bounce handling, Kopexa email themes with a deliverability gate, a Kopexa landing page theme (mobile first), double opt-in, Symfony mailer bridges (docs/plugins.md).
• Automatic updates — Renovate opens a PR for every Mautic release on Packagist as soon as it is out; patch releases are merged automatically once the end-to-end tests pass. Security fixes are picked up immediately, everything else (extensions, CI tooling) once a week.

Quick start (Kubernetes)

helm install mautic oci://ghcr.io/kopexa-grc/charts/mautic \
  --namespace mautic --create-namespace \
  --set mautic.siteUrl=https://mautic.example.com

The first start installs Mautic automatically (init container). Get the generated admin password:

kubectl -n mautic get secret mautic -o jsonpath='{.data.admin-password}' | base64 -d; echo

Expose it with your ingress controller or Gateway API:

# values.yaml
ingress:
  enabled: true
  className: nginx            # or traefik, haproxy, …
  hosts:
    - host: mautic.example.com
      paths: [{path: /, pathType: Prefix}]
  tls:
    - secretName: mautic-tls
      hosts: [mautic.example.com]

# … or Gateway API (Envoy Gateway, Cilium, Istio, NGINX Gateway Fabric, …)
httpRoute:
  enabled: true
  parentRefs: [{name: public, namespace: gateway-system, sectionName: https}]
  hostnames: [mautic.example.com]

Configure a mailer (Symfony Mailer DSN), ideally from a Secret:

kubectl -n mautic create secret generic mautic-mailer \
  --from-literal=mailer-dsn='smtp://user:password@smtp.example.com:587'

mautic:
  mailer:
    existingSecret: mautic-mailer
    fromEmail: marketing@example.com
    fromName: Example

Production

The bundled MariaDB is meant for evaluation and small installations: a single instance, no replication, no automatic failover. For production:

mariadb:
  enabled: false
externalDatabase:
  host: mautic-db.databases.svc   # managed DB or e.g. mariadb-operator
  database: mautic
  username: mautic
  existingSecret: mautic-db       # key: password
backup:
  enabled: true
  repository: s3:https://s3.eu-central-1.amazonaws.com/my-backups/mautic
  existingSecret: mautic-backup   # RESTIC_PASSWORD, AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY

Every connection field can also come straight from an operator's or secret manager's Secret, with your own key names — e.g. a mariadb-operator Connection secret and bucket credentials from an ObjectBucketClaim:

externalDatabase:
  existingSecret: mautic-connection
  secretKeys: {host: host, port: port, database: database, username: username, password: password}
backup:
  enabled: true
  configMapEnv:
    RESTIC_REPOSITORY: {name: mautic-backup-config, key: RESTIC_REPOSITORY}
  secretEnv:
    RESTIC_PASSWORD:       {name: mautic-backup, key: restic-password}
    AWS_ACCESS_KEY_ID:     {name: mautic-bucket, key: AWS_ACCESS_KEY_ID}
    AWS_SECRET_ACCESS_KEY: {name: mautic-bucket, key: AWS_SECRET_ACCESS_KEY}

Mautic supports MySQL/MariaDB only (no PostgreSQL, so no CloudNativePG).

See docs/production.md (sizing, scaling, storage, upgrades), docs/backup.md (backup and restore), docs/mcp.md (connect Claude, ChatGPT and other AI assistants via MCP), docs/oauth.md (OAuth 2.1 authorization server), docs/extensions.md (our extensions: repositories and releases), docs/postal.md (sending via Postal, bounce webhooks on /mailer/callback), docs/preferences.md (email preferences: topics instead of unsubscribe-all) and docs/sso.md (SAML single sign-on).

How the chart is laid out

Component	Kind	Command
web	Deployment	Apache + mod_php; init container installs/migrates
worker	Deployment	messenger:consume email hit (restarts hourly)
cron	one CronJob per job	mautic:segments:update, campaigns:update, campaigns:trigger, broadcasts:send, reports:scheduler, …
mariadb	StatefulSet (optional)	official mariadb:11.4
backup	CronJob (optional)	mariadb-dump → restic (+ uploads)

Everything is configurable in values.yaml: resources, probes, affinity, tolerations, topology spread, extra env/volumes/sidecars/init containers, per-job schedules, PDB, HPA and extraObjects for anything else. The chart renders plain manifests, so it also works with helm template | kustomize.

Built-in extensions

Double opt-in, plus API transports for SES, Postmark, Brevo, Mailgun, SendGrid and Mailjet next to SMTP (e.g. Postal) — curated, pinned and updated by Renovate. See docs/plugins.md.

Docker / Compose

docker run -d --name mautic -p 8080:8080 --read-only --tmpfs /tmp --tmpfs /app/var \
  -v mautic-config:/app/config -v mautic-media:/app/docroot/media/images \
  -e MAUTIC_DB_HOST=db -e MAUTIC_DB_NAME=mautic -e MAUTIC_DB_USER=mautic \
  -e MAUTIC_DB_PASSWORD_FILE=/run/secrets/db-password \
  -e MAUTIC_SITE_URL=https://mautic.example.com \
  -e MAUTIC_ADMIN_PASSWORD_FILE=/run/secrets/admin-password \
  ghcr.io/kopexa-grc/mautic:7

Run init once before web (or as a separate service), plus worker and console <command> for queues and cron. The image commands and all environment variables are documented in docs/configuration.md.

Verify

cosign verify ghcr.io/kopexa-grc/mautic:7 \
  --certificate-identity-regexp '^https://github.com/kopexa-grc/mautic-stack/\.github/workflows/image\.yml@refs/heads/main$' \
  --certificate-oidc-issuer https://token.actions.githubusercontent.com

Differences from the official Mautic image

Both ship Mautic 7 (the official mautic/mautic image has 7.x-apache and 7.x-fpm tags); this image follows the same releases, updated by Renovate. The differences:

• Built-in extensions: OAuth 2.1 + MCP server for AI assistants, Postal bounces, Kopexa email themes, double opt-in, mailer API bridges (see docs/plugins.md).
• Valkey for cache and shared sessions, and a Helm chart with web, worker, cron jobs, backups and network policies.
• Hardened base: no shell/package manager, non-root, read-only rootfs, setuid-free, CIS-aligned Apache config, uploads cannot execute PHP.
• Configuration via environment and *_FILE secrets; automatic install.
• No ext-imap: removed from PHP 8.4 core and built on an unmaintained library. IMAP bounce processing is therefore unavailable — use your mail provider's webhooks. See docs/limitations.md.

License

Packaging (Dockerfile, chart, scripts): Apache-2.0. Mautic itself is GPL-3.0; the image contains Mautic and the packages of its base image under their own licenses (see the SBOM attached to each image). This project is not affiliated with or endorsed by Mautic or Acquia.

---

Made with care by Kopexa · kopexa-grc on GitHub