Ghost MailConfig Gateway

MailConfig is a powerful, enterprise-ready side-car plugin for Ghost CMS that elegantly injects a fully visual Email Transport configuration dashboard directly into the native Ghost Admin panel—without ever altering a single line of Ghost's core source code.

This plugin is architected for Zero-Compromise Security, meaning it is fully compliant with strict Kubernetes Pod Security Standards (PSS), stateless deployments, and containerized lifecycle management.

✨ Key Features

• Visual Configuration Dashboard: Configure custom SMTP or Mailgun settings seamlessly inside the Ghost Admin UI.
• Send Test Email: Verify your email transport settings instantly with a single click using the integrated diagnostic tool.
• Mailgun EU Region Support: Full native support for routing through European Mailgun domains (api.eu.mailgun.net).
• Secure Secret Masking & UI Polish: API keys and passwords are masked (••••••••) on the frontend to prevent XSS credential theft, featuring a built-in visibility toggle for UX convenience.

Architecture & Security Highlights

• Zero Security Regressions: Operates strictly within Ghost's native security perimeter. No core files are touched, and authentication/CSRF protections remain intact.
• Strict Root-Hardening Compliance: Fully supports readOnlyRootFilesystem: true via atomic write resolution to persistent mounted volumes.
• Dropped Capabilities: Runs perfectly in restricted Kubernetes environments with runAsNonRoot: true (UID 1000) and capabilities: drop: ["ALL"]. No elevated privileges required.
• Automated Zero-Downtime Hot-Reloads: Eliminates manual ghost restart operations in Docker/Kubernetes by utilizing a secure file-system watcher (Supervisor Pattern).
• Idempotent Teardowns: Safe and robust uninstallation. Automatically hands over routing adapters to other installed plugins or cleanly wipes configurations without crashing Ghost on reboot.
• Multi-Plugin Coexistence: Dynamically negotiates the scheduling.active boot sequence, allowing it to seamlessly coexist with other extensions (like Ghost FormBuilder).

🚀 Deployment & Installation

1. Local / Bare-Metal Environments (Ghost-CLI)

If you are running Ghost locally or on a standard VM using the Ghost-CLI:

Install:

# Run this inside your Ghost root directory
npm install ghost-mailconfig

Note: The automated installer will detect your .ghost-cli environment and automatically run ghost restart in the background for you!

Uninstall: If your local NPM blocks lifecycle scripts (e.g., allow-scripts warnings), run the teardown script manually before uninstalling:

node "node_modules/ghost-mailconfig/scripts/uninstall.js"
npm uninstall ghost-mailconfig

(The teardown script automatically triggers a local ghost restart).

2. Standard Docker Containers

To support zero-downtime hot-reloads inside Docker without killing the container, you must use the Supervisor Pattern.

Custom Dockerfile:

FROM ghost:5-alpine
WORKDIR /var/lib/ghost

# Copy the supervisor script (see documentation for script contents)
COPY ghost-supervisor.js /var/lib/ghost/ghost-supervisor.js

# Pre-install the plugin
RUN npm install @sakthi10122004/mailconfig

USER node
# Override default CMD to use the Supervisor
CMD ["node", "ghost-supervisor.js"]

When you install or uninstall the plugin dynamically inside a running container via npm, it will safely touch the .reload-trigger file, and the Supervisor will execute a zero-downtime micro-restart.

3. Highly Restricted Kubernetes / Helm (Production)

For enterprise clusters enforcing readOnlyRootFilesystem: true, you must symlink the config.production.json to your persistent volume (/var/lib/ghost/content/data/config.production.json) using an initContainer.

The plugin's atomic writer will natively resolve the symlink and write securely to the Persistent Volume Claim (PVC) without triggering EROFS (Read-Only File System) kernel panics.

Example Helm Security Context:

securityContext:
  readOnlyRootFilesystem: true
  allowPrivilegeEscalation: false
  runAsUser: 1000
  runAsGroup: 1000
  runAsNonRoot: true
  capabilities:
    drop: ["ALL"]

Usage

1. Open your Ghost Admin interface.
2. Open your Settings sidebar (the gear icon).
3. Click the newly injected Installed Plugins option near the bottom of the navigation pane.
4. Select the Mail Transport plugin and hit Open.
5. Punch in your credentials (toggle the eye icon to verify them) and hit Save Settings.
6. Hit Send Test Email to verify your configuration works instantly!