Install MODX 3.1.2 Advanced Core Relocation Fix 503 Error

Installing MODX 3.1.2-pl in advanced mode with core relocation outside public_html requires downloading the advanced zip, extracting setup/ to your web root, creating a writable external core directory, and pre-configuring the three config.core.php files with the new MODX core path. This prevents the common Error 503 “Site temporarily unavailable; missing dependencies” by ensuring setup can unpack the compressed core and generate config.inc.php. Access /setup after these tweaks, specify your custom core path in the advanced options, and complete database setup—worked flawlessly before, so permissions or path mismatches are likely culprits now.

Contents

• Prerequisites for MODX 3.1.2 Advanced Installation
• Step-by-Step Advanced Installation with Core Relocation
• Pre-Configuring Core Paths to Avoid Issues
• Troubleshooting MODX Error 503
• Post-Installation Verification and Best Practices
• Sources
• Conclusion

Prerequisites for MODX 3.1.2 Advanced Installation

Think your server is ready? Double-check these first. MODX 3.1.2-pl demands PHP 7.4 or higher (ideally 8.1+ by 2026 standards), MySQL 5.7+ or MariaDB 10.2+, and extensions like PDO, ZIP, and GD—missing ZIP kills advanced unpacking. Your host must allow directory creation outside public_html, like /home/youruser/modx-core/, with full write permissions (755 for dirs, 644 for files).

Download modx-3.1.2-pl-advanced.zip from the official site—it’s slimmer because the core/ is compressed, perfect for relocation. Extract it temporarily: you’ll upload setup/ to public_html/setup/ and handle core separately. No full core/ dump to web root yet; that’s what setup builds.

Permissions snag many folks. Set public_html/setup/ to 755, and your external core dir to 777 temporarily (tighten later). Database? Create one via cPanel or CLI: CREATE DATABASE modx_db CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;. Got that? Good—now the real work.

Step-by-Step Advanced Installation with Core Relocation

Here’s where it gets interesting. Unlike traditional installs, advanced mode lets you point core outside public_html during setup, boosting security—no core exposure to web hacks.

1. Prep directories: Create /home/youruser/modx-core/ (or wherever outside public_html). chmod 755 /home/youruser/modx-core/ and own it to your web user (e.g., chown www-data:www-data on Apache).

2. Upload setup/: Extract the advanced zip locally, upload only setup/ to public_html/setup/. Skip dumping core/ anywhere yet.

3. Tweak config.core.php files (crucial—details next section): Edit root/config.core.php, manager/config.core.php (create manager/ dir if missing), and connectors/config.core.php. Add <?php define('MODX_CORE_PATH', '/home/youruser/modx-core/');.

4. Hit /setup: Browse to mysite.ru/setup. It unpacks core to your specified path, prompts for DB details, admin user, etc. In “Advanced Configuration,” confirm or set the core path—it’ll match your define.

5. Finalize: Setup writes core/config/config.inc.php, tests connections. If green, click “Install.” Redirects to manager login. Delete setup/ post-success.

Previously worked? You likely had core partially moved; now with fresh advanced zip, missing pre-config triggers 503. This mirrors MODX advanced docs, where setup handles unpacking if paths align.

Stuck mid-way? Server logs (/var/log/apache2/error.log) spill the beans—often “file not found” on config.inc.php.

Pre-Configuring Core Paths to Avoid Issues

Why pre-edit config.core.php? Pre-install, MODX hunts for core/config/config.inc.php. None exists, boom—503. But advanced setup creates it after unpacking.

The fix? Mimic post-install paths early. Create these files if absent:

• public_html/config.core.php:

<?php
define('MODX_CORE_PATH', '/home/youruser/modx-core/');

• public_html/manager/config.core.php (create manager/ first):

<?php
define('MODX_CORE_PATH', '/home/youruser/modx-core/');

• public_html/connectors/config.core.php (create connectors/):

<?php
define('MODX_CORE_PATH', '/home/youruser/modx-core/');

Also, touch an empty core/config/config.inc.php in your external dir: touch /home/youruser/modx-core/config/config.inc.php && chmod 644 it. Writable? chmod 755 /home/youruser/modx-core/config/.

For post-move tweaks (if partially installed), run SQL like:

UPDATE modx_workspaces SET path = '/home/youruser/modx-core/' WHERE id = 1;

As shared in MODX forums on core relocation. Reload /setup after—dependencies resolve.

Troubleshooting MODX Error 503

Error 503 “Site temporarily unavailable; missing dependencies” screams path or permission woes. You’ve seen it before install; here’s the hit list.

• No config.inc.php: Create empty one in core/config/, chmod 644. MODX Cookbook nails this—setup populates it.

• Permissions: core/config/ at 755, parent dirs traversable. Apache/Nginx? Check mod_security or .htaccess blocking /setup.

• Wrong core path: Verify all three config.core.php match. Test: php -r "echo defined('MODX_CORE_PATH') ? MODX_CORE_PATH : 'Nope';" in CLI.

• Unpacked core fail: Advanced needs ZIP extension. phpinfo() it. Ubuntu fix: apt install php-zip.

• Logs first: Tail error_log. “PDO not found”? Install/enable. GitHub issue #14844 notes reload post-install fixes transients, but pre-install? Paths.

• Host quirks: Shared hosting? Ask support for mod_php vs FPM paths. Migrating? Clear caches, regen via setup.

From Stack Overflow thread, 755 on core/config/ sealed it. And another forum post: Just hit /setup directly, not root.

Quick win? FTP core/ from a traditional zip temporarily, run setup, then relocate with SQL/config updates.

Post-Installation Verification and Best Practices

Installed? Don’t celebrate yet. Login to manager (mysite.ru/manager). Green? Run System > Refresh (cache clear). Test frontend chunk.

Core relocation perks: Hides /core/ from web, slashes attack surface. Tighten: chmod 755 modx-core/, 644 files, .htaccess deny all on manager/connectors.

Updates? Composer or manual—core stays external. Backups: Rsync core/ + DB dump.

Best practice: Use MODX 3.x install docs for version pins. Staging? Dockerize with volumes for core.

Edge case from community thread: Post-move, regen configs via setup “Check Installation.”

You’re set—secure, fast MODX humming.

Sources

1. Cooking with MODX - 503 Error
2. Move core directory after install MODX Revolution
3. MODX3 Error 503 Service temporarily unavailable after the installation
4. Advanced Installation - Installation MODX Documentation
5. Getting error Error 503 Site temporarily unavailable when download MODX revolution live to localhost
6. Installation - Getting Started MODX Documentation
7. Error 503 Site temporarily unavailable
8. Moving site 503 error - Support MODX Community

Conclusion

Nail MODX 3.1.2-pl advanced installation by pre-defining the external MODX core path in config.core.php files, ensuring writable dirs, and creating a placeholder config.inc.php—this sidesteps Error 503 every time. Follow the steps, check logs religiously, and you’ll have a secure setup with core safely tucked away. Questions? Dive into manager diagnostics or community—MODX rewards the persistent.