Deploying MODX

Introduction

MODX is a creative content management system and application framework that gives developers and designers complete freedom to build exactly what they envision. Unlike restrictive CMS platforms, MODX provides a blank canvas approach, allowing you to create any type of website without fighting against predefined structures.

Built with PHP and using MySQL/MariaDB for storage, MODX Revolution (the latest major version) offers a powerful templating system, custom resource types, and an extensive extras ecosystem. The platform is known for producing clean, semantic HTML without bloating your markup with unnecessary elements.

Key highlights of MODX:

Creative Freedom: No forced themes or layouts; build exactly what you want
Clean Output: Generates semantic HTML without bloat
Powerful Templating: Template Variables, Chunks, and Snippets for flexible content
Context System: Multi-site management from a single installation
User Management: Granular access controls and user groups
Media Manager: Built-in file and image management
Multilingual: Full support for multilingual websites
SEO Friendly: Clean URLs, meta management, and performance optimization
Extensible: Hundreds of Extras (plugins) available
REST API: Headless CMS capabilities with REST API
Active Community: Large developer community and extensive documentation
Open Source: GPLv2 licensed with commercial-friendly terms

This guide walks through deploying MODX on Klutch.sh using Docker, configuring your CMS, and building your website.

Why Deploy MODX on Klutch.sh

Deploying MODX on Klutch.sh provides several advantages:

Simplified Deployment: Klutch.sh automatically detects your Dockerfile and builds MODX without complex configuration.

Persistent Storage: Attach persistent volumes for your database, uploads, and configuration. Your content survives restarts.

HTTPS by Default: Klutch.sh provides automatic SSL certificates, ensuring secure access to your website.

GitHub Integration: Connect your configuration repository directly from GitHub for automated deployments.

Scalable Resources: Allocate CPU and memory based on traffic expectations.

Environment Variable Management: Securely store database credentials through Klutch.sh’s environment variable system.

Custom Domains: Assign a custom domain to your MODX website.

Always-On Availability: Your website remains accessible 24/7.

Prerequisites

Before deploying MODX on Klutch.sh, ensure you have:

A Klutch.sh account
A GitHub account with a repository for your MODX configuration
Basic familiarity with Docker and containerization concepts
Understanding of PHP-based content management systems
(Optional) A custom domain for your website

Understanding MODX Architecture

MODX uses a structured yet flexible architecture:

Core: The MODX core containing the framework, processors, and API.

Manager: The administrative interface for content management.

Connectors: API endpoints for manager-core communication.

Elements: Templates, Chunks, Snippets, Plugins, and Template Variables.

Resources: Your content pages organized in a tree structure.

Packages: Extras and add-ons extending functionality.

Preparing Your Repository

To deploy MODX on Klutch.sh, create a GitHub repository containing your configuration.

Repository Structure

modx-deploy/
├── Dockerfile
├── config/
│   └── config.inc.php
├── README.md
└── .dockerignore

Creating the Dockerfile

Create a Dockerfile in the root of your repository:

FROM php:8.1-apache

# Install dependencies
RUN apt-get update && apt-get install -y \
    libpng-dev \
    libjpeg-dev \
    libfreetype6-dev \
    libzip-dev \
    unzip \
    wget \
    && rm -rf /var/lib/apt/lists/*

# Configure PHP extensions
RUN docker-php-ext-configure gd --with-freetype --with-jpeg
RUN docker-php-ext-install pdo pdo_mysql gd zip

# Enable Apache modules
RUN a2enmod rewrite

# Download and install MODX
WORKDIR /var/www/html
RUN wget -q https://modx.com/download/direct/modx-3.0.3-pl.zip \
    && unzip modx-3.0.3-pl.zip \
    && mv modx-3.0.3-pl/* . \
    && rm -rf modx-3.0.3-pl modx-3.0.3-pl.zip

# Set permissions
RUN chown -R www-data:www-data /var/www/html

# Configure PHP
RUN echo "upload_max_filesize = 64M" >> /usr/local/etc/php/conf.d/modx.ini \
    && echo "post_max_size = 64M" >> /usr/local/etc/php/conf.d/modx.ini \
    && echo "memory_limit = 256M" >> /usr/local/etc/php/conf.d/modx.ini

# Expose web server port
EXPOSE 80

# Health check
HEALTHCHECK --interval=30s --timeout=10s --start-period=60s --retries=3 \
  CMD curl -f http://localhost/ || exit 1

Creating the .dockerignore File

Create a .dockerignore file:

.git
.github
*.md
LICENSE
.gitignore
*.log
.DS_Store
.env
.env.local

Environment Variables Reference

Variable	Required	Default	Description
`MODX_DB_HOST`	Yes	-	Database host
`MODX_DB_NAME`	Yes	-	Database name
`MODX_DB_USER`	Yes	-	Database username
`MODX_DB_PASSWORD`	Yes	-	Database password
`MODX_TABLE_PREFIX`	No	modx_	Database table prefix
`MODX_ADMIN_USER`	Yes	-	Initial admin username
`MODX_ADMIN_PASSWORD`	Yes	-	Initial admin password
`MODX_ADMIN_EMAIL`	Yes	-	Admin email address

Deploying MODX on Klutch.sh

Once your repository is prepared, follow these steps to deploy:

Push Your Repository to GitHub

Initialize your repository and push to GitHub:

git init
git add Dockerfile .dockerignore README.md
git commit -m "Initial MODX deployment configuration"
git remote add origin https://github.com/yourusername/modx-deploy.git
git push -u origin main

Create a New Project on Klutch.sh

Navigate to the Klutch.sh dashboard and create a new project. Give it a descriptive name like “modx” or “website”.

Create a New App

Within your project, create a new app. Connect your GitHub account if you haven’t already, then select the repository containing your MODX Dockerfile.

Configure HTTP Traffic

In the deployment settings:

Select HTTP as the traffic type
Set the internal port to 80

Set Environment Variables

In the environment variables section, add:

Variable	Value
`MODX_DB_HOST`	Your database host
`MODX_DB_NAME`	`modx`
`MODX_DB_USER`	Your database user
`MODX_DB_PASSWORD`	Your database password
`MODX_ADMIN_USER`	`admin`
`MODX_ADMIN_PASSWORD`	Your secure admin password
`MODX_ADMIN_EMAIL`	`admin@example.com`

Attach Persistent Volumes

Add the following volumes:

Mount Path	Recommended Size	Purpose
`/var/www/html/core/cache`	2 GB	MODX cache files
`/var/www/html/assets`	10 GB	Uploaded media and assets
`/var/www/html/core/packages`	2 GB	Installed extras

Deploy Your Application

Click Deploy to start the build process. Klutch.sh will:

Detect your Dockerfile automatically
Build the container image
Attach the persistent volumes
Start the MODX container
Provision an HTTPS certificate

Complete Setup

Access https://example-app.klutch.sh/setup/ to complete the MODX installation wizard. Enter your database credentials and admin information.

Remove Setup Directory

After installation, remove the setup directory for security:

Access the MODX manager at https://example-app.klutch.sh/manager/

Initial Setup and Configuration

Creating Templates

Design your page layouts:

Navigate to Elements > Templates
Click Create New Template
Add your HTML structure with MODX tags
Use placeholders for dynamic content
Save and assign to resources

Example template:

<!DOCTYPE html>
<html>
<head>
    <title>[[*pagetitle]] | [[++site_name]]</title>
    [[*head]]
</head>
<body>
    <header>[[getChunk? &chunkName=`header`]]</header>
    <main>[[*content]]</main>
    <footer>[[getChunk? &chunkName=`footer`]]</footer>
</body>
</html>

Template Variables

Add custom fields to resources:

Navigate to Elements > Template Variables
Create new Template Variable
Set input type (text, image, dropdown, etc.)
Assign to templates
Access in templates with [[*tvname]]

Creating Chunks

Build reusable content blocks:

Navigate to Elements > Chunks
Create chunks for headers, footers, navigation
Include in templates with [[$chunkname]]
Pass parameters for dynamic content

Create dynamic menus:

Install the pdoTools extra
Use pdoMenu or Wayfinder
Configure menu settings
Style with CSS

Example:

[[pdoMenu?
    &parents=`0`
    &level=`2`
    &tplOuter=`@INLINE <nav><ul>[[+wrapper]]</ul></nav>`
    &tpl=`@INLINE <li><a href="[[+link]]">[[+menutitle]]</a>[[+wrapper]]</li>`
]]

Installing Extras

Package Management

Install additional functionality:

Navigate to Extras > Installer
Click Download Extras
Search for needed packages
Install and configure

Popular Extras

Essential extras for most sites:

pdoTools: Improved snippets for resources and navigation
FormIt: Form processing and validation
Gallery: Photo gallery management
MIGX: Custom database tables and management
Ace: Code editor for templates
ClientConfig: Client-editable settings
SEO Suite: SEO optimization tools

Production Best Practices

Security Recommendations

Remove Setup: Delete /setup/ after installation
Strong Passwords: Use strong passwords for all accounts
Manager Access: Restrict manager access by IP if possible
Regular Updates: Keep MODX and extras updated
Backup Regularly: Back up files and database

Performance Optimization

Enable Caching: Configure MODX caching settings
Optimize Images: Compress uploaded images
CDN Integration: Use CDN for static assets
Database Optimization: Regular database maintenance
PHP OpCache: Ensure OpCache is enabled

Backup Strategy

Protect your website:

Database Backups: Regularly back up MySQL database
File Backups: Back up assets and core/packages directories
Configuration: Export system settings
Offsite Storage: Store backups externally

Troubleshooting Common Issues

White Screen/Errors

Symptoms: Site displays blank or error page.

Solutions:

Check PHP error logs
Verify database connection
Clear MODX cache manually
Check file permissions

Manager Access Problems

Symptoms: Cannot access /manager/ interface.

Solutions:

Verify admin credentials
Check session configuration
Clear browser cookies
Review access policies

Extras Not Installing

Symptoms: Package installation fails.

Solutions:

Check write permissions on packages directory
Verify PHP memory limits
Check network connectivity to MODX repository
Review transport package logs

Additional Resources

Conclusion

Deploying MODX on Klutch.sh gives you a powerful, flexible content management system with complete creative freedom. The combination of MODX’s template-driven approach and Klutch.sh’s deployment simplicity means you can focus on building your vision rather than fighting with infrastructure.

With clean HTML output, powerful templating, and an extensive extras ecosystem, MODX handles everything from simple websites to complex web applications. Whether you’re a developer seeking ultimate control or an agency needing a flexible client platform, MODX on Klutch.sh provides the reliable, always-available foundation you need.

Deploying MODX

Introduction

Why Deploy MODX on Klutch.sh

Prerequisites

Understanding MODX Architecture

Preparing Your Repository

Repository Structure

Creating the Dockerfile

Creating the .dockerignore File

Environment Variables Reference

Deploying MODX on Klutch.sh

Initial Setup and Configuration

Creating Templates

Template Variables

Creating Chunks

Building Navigation

Installing Extras

Package Management

Popular Extras

Production Best Practices

Security Recommendations

Performance Optimization

Backup Strategy

Troubleshooting Common Issues

White Screen/Errors

Manager Access Problems

Extras Not Installing

Additional Resources

Conclusion