1. Getting Started
      1. Video Quick-Start Series
      2. Server Requirements
        1. MySQL 5.0.51 Issues
      3. Installation
        1. Basic Installation
          1. MODx Revolution on Debian
          2. Problems with WAMPServer 2.0i
          3. Lighttpd Guide
          4. Installation on a server running ModSecurity
          5. MODX and Suhosin
          6. Nginx Server Config
        2. Successful Installation, Now What Do I Do?
        3. Successful Installation, Now What Do I Do?
        4. Advanced Installation
        5. Git Installation
        6. Command Line Installation
          1. The Setup Config Xml File
        7. Troubleshooting Installation
        8. Using MODx Revolution from SVN
      4. An Overview of MODX
        1. Glossary of Revolution Terms
          1. Explanation of Directory Structure
        2. Roadmap
        3. MODX Revolution Framework Structure Ideology
    2. FAQs & Troubleshooting
      1. CMP Development FAQs & Troubleshooting
    3. Making Sites with MODx
      1. Structuring Your Site
        1. Resources
          1. Content Types
          2. Named Anchor
          3. Static Resource
          4. Symlink
            1. Using Resource Symlinks
          5. Weblink
        2. Templates
        3. Chunks
        4. Using Snippets
      2. Tag Syntax
      3. Customizing Content
        1. Template Variables
          1. Creating a Template Variable
          2. Adding a Custom TV Type - MODX 2.2
          3. Bindings
            1. CHUNK Binding
            2. DIRECTORY Binding
            3. EVAL Binding
            4. FILE Binding
            5. INHERIT Binding
            6. RESOURCE Binding
            7. SELECT Binding
          4. Template Variable Input Types
          5. Template Variable Output Types
            1. Date TV Output Type
            2. Delimiter TV Output Type
            3. HTML Tag TV Output Type
            4. Image TV Output Type
            5. URL TV Output Type
          6. Adding a Custom TV Input Type
          7. Adding a Custom TV Output Type
          8. Creating a multi-select box for related pages in your template
          9. Accessing Template Variable Values via the API
        2. Properties and Property Sets
        3. Input and Output Filters (Output Modifiers)
          1. Custom Output Filter Examples
      4. Commonly Used Template Tags
        1. Date Formats
    4. Administering Your Site
      1. Settings
        1. System Settings
          1. access_category_enabled
          2. date_timezone
          3. access_context_enabled
          4. access_resource_group_enabled
          5. allow_duplicate_alias
          6. allow_forward_across_contexts
          7. allow_multiple_emails
          8. allow_tags_in_post
          9. archive_with
          10. automatic_alias
          11. auto_check_pkg_updates
          12. auto_check_pkg_updates_cache_expire
          13. auto_menuindex
          14. base_help_url
          15. blocked_minutes
          16. cache_action_map
          17. cache_context_settings
          18. cache_db
          19. cache_db_expires
          20. cache_db_session
          21. cache_default
          22. cache_disabled
          23. cache_format
          24. cache_handler
          25. cache_json
          26. cache_json_expires
          27. cache_lang_js
          28. cache_lexicon_topics
          29. cache_noncore_lexicon_topics
          30. cache_resource
          31. cache_resource_expires
          32. cache_scripts
          33. cache_system_settings
          34. clear_cache_refresh_trees
          35. compress_css
          36. compress_js
          37. concat_js
          38. container_suffix
          39. cultureKey
          40. custom_resource_classes
          41. default_per_page
          42. default_template
          43. editor_css_path
          44. editor_css_selectors
          45. emailsender
          46. emailsubject
          47. enable_dragdrop
          48. error_page
          49. extension_packages
          50. failed_login_attempts
          51. feed_modx_news
          52. feed_modx_news_enabled
          53. feed_modx_security
          54. feed_modx_security_enabled
          55. fe_editor_lang
          56. filemanager_path
          57. filemanager_path_relative
          58. filemanager_url
          59. filemanager_url_relative
          60. forgot_login_email
          61. friendly_alias_lowercase_only
          62. forward_merge_excludes
          63. friendly_alias_max_length
          64. friendly_alias_restrict_chars
          65. friendly_alias_restrict_chars_pattern
          66. friendly_alias_strip_element_tags
          67. friendly_alias_translit
          68. friendly_alias_translit_class
          69. friendly_alias_translit_class_path
          70. friendly_alias_trim_chars
          71. friendly_alias_urls
          72. friendly_alias_word_delimiter
          73. friendly_alias_word_delimiters
          74. friendly_urls
          75. friendly_url_prefix
          76. friendly_url_suffix
          77. global_duplicate_uri_check
          78. hidemenu_default
          79. link_tag_scheme
          80. mail_charset
          81. mail_encoding
          82. mail_smtp_auth
          83. mail_smtp_helo
          84. mail_smtp_hosts
          85. mail_smtp_keepalive
          86. mail_smtp_pass
          87. mail_smtp_port
          88. mail_smtp_prefix
          89. mail_smtp_single_to
          90. mail_smtp_timeout
          91. mail_smtp_user
          92. mail_use_smtp
          93. manager_date_format
          94. manager_direction
          95. manager_favicon_url
          96. manager_language
          97. manager_lang_attribute
          98. manager_theme
          99. manager_time_format
          100. modx_charset
          101. new_file_permissions
          102. new_folder_permissions
          103. password_generated_length
          104. password_min_length
          105. phpthumb_allow_src_above_docroot
          106. phpthumb_cache_maxage
          107. phpthumb_cache_maxfiles
          108. phpthumb_cache_maxsize
          109. phpthumb_cache_source_enabled
          110. phpthumb_document_root
          111. phpthumb_error_bgcolor
          112. phpthumb_error_fontsize
          113. phpthumb_error_textcolor
          114. phpthumb_far
          115. phpthumb_imagemagick_path
          116. phpthumb_nohotlink_enabled
          117. phpthumb_nohotlink_erase_image
          118. phpthumb_nohotlink_text_message
          119. phpthumb_nohotlink_valid_domains
          120. phpthumb_nooffsitelink_enabled
          121. phpthumb_nooffsitelink_erase_image
          122. phpthumb_nooffsitelink_require_refer
          123. phpthumb_nooffsitelink_text_message
          124. phpthumb_nooffsitelink_valid_domains
          125. phpthumb_nooffsitelink_watermark_src
          126. phpthumb_zoomcrop
          127. principal_targets
          128. proxy_auth_type
          129. proxy_host
          130. proxy_password
          131. proxy_port
          132. proxy_username
          133. publish_default
          134. rb_base_dir
          135. rb_base_url
          136. request_controller
          137. request_param_alias
          138. request_param_id
          139. resource_tree_node_name
          140. resource_tree_node_tooltip
          141. richtext_default
          142. search_default
          143. server_offset_time
          144. server_protocol
          145. session_cookie_domain
          146. session_cookie_lifetime
          147. session_cookie_path
          148. session_cookie_secure
          149. session_handler_class
          150. session_name
          151. settings_version
          152. signupemail_message
          153. site_name
          154. site_start
          155. site_status
          156. site_unavailable_message
          157. site_unavailable_page
          158. strip_image_paths
          159. symlink_merge_fields
          160. tree_default_sort
          161. tree_root_id
          162. tvs_below_content
          163. udperms_allowroot
          164. ui_debug_mode
          165. unauthorized_page
          166. upload_maxsize
          167. use_alias_path
          168. use_browser
          169. use_editor
          170. use_multibyte
          171. welcome_screen
          172. which_editor
          173. which_element_editor
          174. xhtml_urls
      2. Using Friendly URLs
      3. Contexts
        1. Creating a Subdomain from a Folder using Virtual Hosts
        2. Using One Gateway Plugin to Manage Multiple Domains
      4. Customizing the Manager
        1. Customizing the Manager via Plugins
        2. Form Customization Profiles
        3. Form Customization Sets
          1. Customizing Tabs via Form Customization
          2. MODX GitHub Contributor's Guide
        4. Manager Templates and Themes
      5. MODX GitHub Integrator's Guide
      6. Security
        1. Hardening MODX Revolution
        2. Policies
          1. ACLs
          2. Permissions
            1. Permissions - Administrator Policy
            2. Permissions - Resource Policy
          3. PolicyTemplates
        3. Resource Groups
        4. Roles
        5. Security Standards
        6. Security Tutorials
          1. More on the Anonymous User Group
          2. Creating a Second Super Admin User
          3. Giving a User Manager Access
          4. Making Member-Only Pages
          5. Restricting an Element from Users
        7. Troubleshooting Security
          1. Resetting a User Password Manually
        8. User Groups
        9. Users
      7. Installing a Package
        1. Troubleshooting Package Management
      8. Upgrading MODX
        1. Upgrading to Revolution 2.0.5
        2. Upgrading from 2.0.x to 2.1.x
        3. Upgrading from Versions Earlier than 2.0.5
        4. Upgrading to 2.2.x
        5. Upgrading to Revolution 2.0.0-rc-2
        6. Troubleshooting Upgrades
        7. Upgrading from MODx Evolution
          1. Functional Changes from Evolution
      9. Moving Your Site to a New Server
      10. Media Sources
        1. Adding a Media Source
        2. Assigning Media Sources to TVs
        3. Media Source Types
          1. Media Source Type - File System
          2. Media Source Type - S3
        4. Securing a Media Source
          1. Creating a Media Source for Clients Tutorial
      11. Dashboards
        1. Assigning a Dashboard to a User Group
        2. Creating a Dashboard Widget
        3. Dashboard Widget Types
          1. Dashboard Widget Type - File
          2. Dashboard Widget Type - HTML
          3. Dashboard Widget Type - Inline PHP
          4. Dashboard Widget Type - Snippet
        4. Managing Your Dashboard
    5. Developing in MODx
      1. Code Standards
      2. Overview of MODx Development
        1. Developer Introduction
          1. Getting Started Developing
        2. Extras Directories
        3. Setting up a Development Environment
      3. Basic Development
        1. Plugins
          1. System Events
            1. OnBeforeCacheUpdate
            2. OnBeforeChunkFormDelete
            3. OnBeforeChunkFormSave
            4. OnBeforeDocFormDelete
            5. OnBeforeDocFormSave
            6. OnBeforeEmptyTrash
            7. OnBeforeManagerLogin
            8. OnBeforeManagerLogout
            9. OnBeforeManagerPageInit
            10. OnBeforePluginFormDelete
            11. OnBeforePluginFormSave
            12. OnBeforeSaveWebPageCache
            13. OnBeforeSnipFormDelete
            14. OnBeforeSnipFormSave
            15. OnBeforeTempFormDelete
            16. OnBeforeTempFormSave
            17. OnBeforeTVFormDelete
            18. OnBeforeTVFormSave
            19. OnBeforeUserActivate
            20. OnBeforeUserFormDelete
            21. OnBeforeUserFormSave
            22. OnBeforeWebLogin
            23. OnBeforeWebLogout
            24. OnCacheUpdate
            25. OnCategoryBeforeRemove
            26. OnCategoryBeforeSave
            27. OnCategoryRemove
            28. OnCategorySave
            29. OnChunkBeforeRemove
            30. OnChunkBeforeSave
            31. OnChunkFormDelete
            32. OnChunkFormPrerender
            33. OnChunkFormRender
            34. OnChunkFormSave
            35. OnChunkRemove
            36. OnChunkSave
            37. OnContextBeforeRemove
            38. OnContextBeforeSave
            39. OnContextFormPrerender
            40. OnContextFormRender
            41. OnContextRemove
            42. OnContextSave
            43. OnDocFormDelete
            44. OnDocFormPrerender
            45. OnDocFormRender
            46. OnDocFormSave
            47. OnDocPublished
            48. OnDocUnPublished
            49. OnEmptyTrash
            50. OnFileManagerUpload
            51. OnHandleRequest
            52. OnInitCulture
            53. OnLoadWebDocument
            54. OnLoadWebPageCache
            55. OnManagerAuthentication
            56. OnManagerLogin
            57. OnManagerLoginFormPrerender
            58. OnManagerLoginFormRender
            59. OnManagerLogout
            60. OnManagerPageAfterRender
            61. OnManagerPageBeforeRender
            62. OnManagerPageInit
            63. OnPageNotFound
            64. OnPageUnauthorized
            65. OnParseDocument
            66. OnPluginBeforeRemove
            67. OnPluginBeforeSave
            68. OnPluginEventRemove
            69. OnPluginFormDelete
            70. OnPluginFormPrerender
            71. OnPluginFormRender
            72. OnPluginFormSave
            73. OnPluginRemove
            74. OnPluginSave
            75. OnPropertySetBeforeRemove
            76. OnPropertySetBeforeSave
            77. OnPropertySetRemove
            78. OnPropertySetSave
            79. OnResourceGroupBeforeRemove
            80. OnResourceGroupBeforeSave
            81. OnResourceGroupRemove
            82. OnResourceGroupSave
            83. OnRichTextBrowserInit
            84. OnRichTextEditorInit
            85. OnRichTextEditorRegister
            86. OnSiteRefresh
            87. OnSiteSettingsRender
            88. OnTemplateVarBeforeRemove
            89. OnTemplateVarBeforeSave
            90. OnTemplateVarRemove
            91. OnTemplateVarSave
            92. OnUserActivate
            93. OnUserBeforeRemove
            94. OnUserBeforeSave
            95. OnUserChangePassword
            96. OnUserFormDelete
            97. OnUserFormSave
            98. OnUserNotFound
            99. OnUserRemove
            100. OnUserSave
            101. OnWebAuthentication
            102. OnWebLogin
            103. OnWebLogout
            104. OnWebPageComplete
            105. OnWebPageInit
            106. OnWebPagePrerender
        2. Snippets
          1. Adding CSS and JS to Your Pages Through Snippets
          2. How to Write a Good Chunk
          3. How to Write a Good Snippet
          4. Templating Your Snippets
        3. xPDO
      4. Advanced Development
        1. Caching
          1. Setting up Memcache in MODX
        2. Custom Manager Pages
          1. Custom Manager Pages in 2.3
          2. Actions and Menus
            1. Action List
          3. Custom Manager Pages Tutorial
          4. MODExt
            1. MODx.combo.ComboBox
            2. MODx.Console
            3. MODx.FormPanel
            4. MODx.grid.Grid
            5. MODx.grid.LocalGrid
            6. MODx.msg
            7. MODx.tree.Tree
            8. MODx.Window
            9. MODExt Tutorials
              1. 1. Ext JS Tutorial - Message Boxes
              2. 2. Ext JS Tutorial - Ajax Include
              3. 3. Ext JS Tutorial - Animation
              4. 4. Ext JS Tutorial - Manipulating Nodes
              5. 5. Ext JS Tutorial - Panels
              6. 7. Ext JS Tutoral - Advanced Grid
              7. 8. Ext JS Tutorial - Inside a CMP
            10. MODExt MODx Object
        3. Custom Resource Classes
          1. Creating a Resource Class
            1. Creating a Resource Class - Step 2
            2. Creating a Resource Class - Step 3
            3. Creating a Resource Class - Step 4
        4. Extending modUser
        5. From the Command Line (CLI)
        6. Internationalization
          1. Adding a Translation
        7. MODx Services
          1. modFileHandler
          2. modMail
          3. modRegistry
        8. Namespaces
        9. Package Management
          1. Creating a 3rd Party Component Build Script
          2. Providers
          3. Transport Packages
        10. Using runProcessor
        11. Validating Requests: Tokens and Nonces
      5. Other Development Resources
        1. Summary of Legacy Code Removed in 2.1
        2. API Reference
        3. Class Reference
          1. modChunk
            1. modChunk.getContent
            2. modChunk.setContent
          2. modUser
            1. modUser.addSessionContext
            2. modUser.changePassword
            3. modUser.endSession
            4. modUser.getSessionContexts
            5. modUser.getSettings
            6. modUser.hasSessionContext
            7. modUser.isAuthenticated
            8. modUser.isMember
            9. modUser.loadAttributes
            10. modUser.removeSessionContext
            11. modUser.removeSessionContextVars
            12. modUser.removeSessionCookie
          3. modX
            1. modX.addEventListener
            2. modX.checkForLocks
            3. modX.checkSession
            4. modX.executeProcessor
            5. modX.getAuthenticatedUser
            6. modX.getCacheManager
            7. modX.getChildIds
            8. modX.getChunk
            9. modX.getConfig
            10. modX.getContext
            11. modX.getEventMap
            12. modX.getLoginUserID
            13. modX.getLoginUserName
            14. modX.getParentIds
            15. modX.getParser
            16. modX.getPlaceholder
            17. modX.getRegisteredClientScripts
            18. modX.getRegisteredClientStartupScripts
            19. modX.getRequest
            20. modX.getResponse
            21. modX.getService
            22. modX.getSessionState
            23. modX.getTree
            24. modX.getUser
            25. modX.getVersionData
            26. modX.handleRequest
            27. modX.hasPermission
            28. modX.initialize
            29. modX.invokeEvent
            30. modX.lexicon
            31. modX.makeUrl
            32. modX.parseChunk
            33. modX.regClientCSS
            34. modX.regClientHTMLBlock
            35. modX.regClientScript
            36. modX.regClientStartupHTMLBlock
            37. modX.regClientStartupScript
            38. modX.reloadConfig
            39. modX.removeAllEventListener
            40. modX.removeEventListener
            41. modX.runProcessor
            42. modX.runSnippet
            43. modX.sendError
            44. modX.sendErrorPage
            45. modX.sendForward
            46. modX.sendRedirect
            47. modX.sendUnauthorizedPage
            48. modX.setDebug
            49. modX.setPlaceholder
            50. modX.setPlaceholders
            51. modX.switchContext
            52. modX.toPlaceholder
            53. modX.toPlaceholders
            54. modX.unsetPlaceholder
            55. modX.unsetPlaceholders
        4. Loading MODx Externally
        5. Reserved Parameters
    6. Case Studies and Tutorials
      1. Developing an Extra in MODX Revolution
        1. Developing an Extra in MODX Revolution, Part II
        2. Developing an Extra in MODX Revolution, Part III
      2. Developing an Extra in MODX Revolution - MODX 2.1 and Earlier
        1. Developing an Extra in MODX Revolution, Part II - MODX 2.1 and Earlier
        2. Developing an Extra in MODX Revolution, Part III - MODX 2.1 and Earlier
      3. PHP Coding in MODx Revolution, Pt. I
        1. PHP Coding in MODx Revolution, Pt. II
        2. PHP Coding in MODx Revolution, Pt. III
      4. Using Custom Database Tables in your 3rd Party Components
      5. Creating a Blog in MODx Revolution
      6. Loading Pages in the Front-End via AJAX and jQuery Tabs
      7. Reverse Engineer xPDO Classes from Existing Database Table
      8. Integrating a Template into MODX Tutorial
      9. Quick and Easy MODX Tutorials
        1. Automated Server-Side Image Editing
      10. Adding Custom Fields to Manager Forms
      11. Managing Resources and Elements via SVN
    7. MODX Community Information
      1. Becoming a Core Contributor
      2. Filing Bug Reports
      3. Getting a MODx Account
      4. Using GitHub

Moving Your Site to a New Server

Welcome to the MODX Documentation. It is an ongoing effort of the MODX community. If you would like to participate or if you notice any errors or missing content, please let us know.

MODX Revolution is a database-driven web application, so moving it to a new server involves the typical porting over of both the database and all the site's files. In Revolution, it's more or less the same process, but there are couple extra tidbits to watch out for due to Revolution's thorough caching mechanisms and how certain server-specific data is stored in its database.

Following is the official documentation of how to move your site to a new location. Normally, the move is to a new server, but the steps here also apply if you move your site to a new folder on your current web server.

Tip
It's not required, but it's a very good idea to turn off Friendly URLs (FURLS) in the Manager, if you have them on, and rename .htaccess to ht.access on your site before performing any of the steps below. Do the reverse as your last step after everything is working at the new location (rename ht.access to .htaccess and turn on FURLS). It takes a big potential source of confusion out of the picture during the transition.

Log into the Manager: Clear your Cache and Sessions

Before doing anything else, it would be wise to empty all of the cached content.

  • Log into the manager, then: Site --> Clear Cache
  • Clear your sessions: Security --> Flush All Sessions

The first benefit of this is a smaller download / upload file.

The safest and surest method to clear the cache is to clear it manually.  Do this by deleting all the contents contained within the core/cache folder.  This process is typically fastest when performed in the server's file manager, as opposed to FTP.

Packaging up your Files

Any time you pack up a site and move, it's best to package the files into "boxes" – when you move out of your apartment, you put everything into boxes; the same concept is true with files: package them. If you simply drag and drop files from one server to another using a GUI interface, chances are good that the GUI will omit hidden files such as the vital .htaccess file. Besides, transferring hundreds of files via FTP can take a long time because each file must often undergo some sort of authentication; in other words copying over a hundred 1 megabyte files takes a lot longer than copying over a single 100 megabyte file.

On a UNIX style system, you can create a compressed file using the tar command:

tar -czf /path/to/backups/modx_revo_site.tar.gz /path/to/modx_doc_root/
Forget me Not
A good mnemonic for the "-czf" option is Create Zip File.

Once you arrive on the other end, it's good to put the zipped file into its own directory before you extract it. The idea here is that if it explodes, it's easier to clean up the mess if it's contained in its own directory.

On a UNIX style system, you can unpackage a .tar.gz file using the following commands from a command line:

gunzip modx_revo_site.tar.gz
tar xvf modx_revo_site.tar

Once you've extracted the files, you can move the whole directory into the correct place. Again, be careful about moving files in bulk: you might inadvertently forget to copy those hidden files. It's better to rename or move the containing directory instead.

Change File Ownership

Sometimes the group and user ownership will change when moving from one host to another. Make sure that the files are owned and accessible to the web server. You will have to check the server configuration to ascertain the correct settings, or simply ask the host for the details. A simpler method may be to simply look at the ownership placed on the tar.gz file when it was uploaded to the server. FTP software will almost always set the proper ownership on an uploaded file.

Writable: 777 or 755?

Some of the folders need to be may writable. Depending on the security configuration of the service this may need to be 755 or 777. The tar.gz file should retain the old server permissions -- but those may not work on the new server.

Dumping your Database

Please note that MODX can run on multiple database drivers, currently MySQL and sqlsrv. The following section is MySQL specific, however you should be able to do the same with similar commands for sqlsrv.

You can dump your MySQL database using a GUI tool such as phpMyAdmin, or you can run the command-line mysqldump utility.

mysqldump -u username -p your_revo_db > /path/to/backups/my_revo_db.sql

If you use mysqldump, be sure you use a username that has SELECT and LOCK permissions on all your MODX Revolution database tables – usually it's best to simply use the same username and password that are defined in your configuration file (/core/config/config.inc.php). Remember that mysqldump will prompt you for the password after you execute this command: when you type it (or paste it), you won't see anything in the terminal window.

On the new server, you can simply use the "mysql" command to slurp the dump file into the new target database:

mysql -u username -p target_db < my_revo_db.sql

You can also use phpMyAdmin, but remember that web-based tools like this are subject to the same memory limits as PHP, so you're usually better off using a command-line tool if possible.

Database Dump with phpMyAdmin

Many server control panels offer database backup and compression tools as well.

Updating your Config Files

Once you've deployed files to the new server, you need to update the main configuration file: core/config/config.inc.php. You have to update paths to 6 different resources. Open the file and update the values for the following variables doing a find and replace:

/* PATHS */
$modx_core_path= '/path/to/modx_doc_root/core/';
$modx_processors_path= '/path/to/modx_doc_root/core/model/modx/processors/';
$modx_connectors_path= '/path/to/modx_doc_root/connectors/';
$modx_manager_path= '/path/to/modx_doc_root/manager/';
$modx_base_path= '/path/to/modx_doc_root/';
$modx_assets_path= '/path/to/modx_doc_root/assets/';

/* HOST (used for command-line PHP stuff) */
$http_host='yoursite.com';

If you are also moving your site into or out of a subfolder, be sure to update the variables such as $modx_connectors_url, $modx_manager_url, and $modx_base_url. They should generally
end with a slash (e.g., $modx_base_url='/' for a site not in a subfolder).

Permissions
Before you can edit your config file, you may need to loosen up the permissions. After you've edited it, be sure you restore the read-only permissions on the file.

There are also 3 additional configuration files that contain two PHP constants:

define('MODX_CORE_PATH', '/path/to/modx_doc_root/core/');
define('MODX_CONFIG_KEY', 'config');
  • /config.core.php
  • /connectors/config.core.php
  • /manager/config.core.php

Make sure you update the paths in these files as well.

Update your Database

Don't Forget the Database
MODX stores some path data in its database! When you move servers, you may have to update the workspaces table, otherwise the manager page may show a white page.

Please note that MODX can run on multiple database drivers, currently MySQL and sqlsrv. The following section is MySQL specific, however you should be able to do the same with similar commands for sqlsrv.

Sometimes developers structure their development and production servers to use the exact same path information, but often the file path information will change when we move our MODX web site to a new server.

To see the path information that is stored inside the MODX database, type the following query into phpMyAdmin, the MySQL command line, or any other application that allows you to execute queries on your database:

SELECT `path` FROM `your_revo_db`.`workspaces`;

Change "your_revo_db" to your database name, and add an appropriate prefix to the "workspaces" table if necessary, e.g. `modx_workspaces`.

If the path on the new server is different than on the old server, you will need to update this record. You can edit it using a GUI editor (like SQL-Yog or phpMyAdmin), or you can execute the following command (again, you need to customize the query depending on your database, prefix, and the path to your data):

UPDATE `your_revo_db`.`workspaces` SET path='/path/to/modx_doc_root/core/' WHERE id='1';

Update .htaccess

When you change servers, you frequently wind up changing domain names. Make sure you update any references to the domain name in your .htaccess file(s).

On the New Server

Log into the manager on the new server to verify that it works. Upon entry, you may experience:

Could not find action file at: /path/to/manager/controllers/default/welcome.php

That's because the old path is still cached; MODX Revolution caches a lot of information in the database and on the file system, so once you've gotten the files and database transferred over to the new server, make sure you clear your site's cache once again, and manually refresh the manager page.

If the cache and session information was not cleared before the move you will need to do so, if you encounter errors within the manager after moving the site.

Sometimes clearing the site cache in the manager won't fix all path issues and it is nessesary to remove all folders/files inside the core/cache folder by FTP or command line.

Re-run setup

Whenever changes are made to a MODX Revolution site in regards to installs, upgrades, or change of location it is important to re-run the domain.com/setup script. This should assist in solidifying the movement process due to the actions taken during its process.

  • Make sure you are running the setup version from the same version of MODX Revolution you will be using.
  • Get the transferred site functional before attempting any version upgrades.

Download Previous Versions of MODX Revolution

Updating your Extras settings

Some extras, such as Gallery, store information on where certain files can be found in their own settings. To take Gallery as the example, it stores the path to its assets, core, files and phpthumb folders on the filesystem. Depending on your setup these will change when moving and in order to keep using these addons you will need to update those paths. While every addon can decide for itself where to store paths, one of the popular locations is in the system settings.

Go to System -> System Settings in your manager, and find the namespaces dropdown, as seen on the image to the right (click to enlarge). Open it and look for the extra of your choice, for instance Gallery. Not all extras specify system settings but most of them will show up on the list anyway. Now that you have found where these paths are stored you can update them to reflect the new location.

If you are using MODX Revolution 2.2, you may also need to check the extension_packages system setting (found under the System & Server area in the System Settings). This setting is used for custom resource classes (such as the Articles addon) and defines the path to its model - this may need to be updated after moving your site.

Troubleshooting / Errors

In progress... trying to document problems and solutions...

Setup Errors

You may encounter problems when re-running Setup on the new server. Sometimes re-running setup fails, but copying the files and database ends up with a working site. Remember: re-running setup is only necessary if you have loose-ends somewhere that broke during the transfer.

Class xPDODriver_ not found

This manifests itself as an error message like the following:

Fatal error: Class 'xPDODriver_' not found in /path/to/webroot/core/xpdo/xpdo.class.php on line 1823

This is usually a sign that your configuration file got mangled. Re-open your core/config/config.inc.php and verify that its contents are in place. A mangled config file contains placeholders instead of values.

$database_type = '{database_type}';
$database_server = '{database_server}';
$database_user = '{database_user}';
$database_password = '{database_password}';
$database_connection_charset = '{database_connection_charset}';
$dbase = '{dbase}';
$table_prefix = '{table_prefix}';
$database_dsn = '{database_dsn}';
$config_options = {config_options};
$driver_options = {driver_options};

Installation Summary shows Incomplete Items

This can be a bad omen: the Installation Summary page does not describe messages. This can be a sign that permissions are not correct somewhere.

When that page is working correctly, you should see messages next to each "Ok":

Check your Database Encoding

It can be hugely problematic if your database on one server does not use the same encoding as the new server. Things like single-quotes etc. will get broken, and in some cases, you might even get a 500 error when trying to view your site.

Final thoughts

It would be wise to keep backups from the old server until the new site has undergone a couple of backup generations and everything has been verified.

If you run into trouble after successfully running Setup, try manually deleting all files in the core/cache directory and clearing your browser cache and cookies.

Your site should now be up and running in its new location!

Final Checkup
It's common for there to be problems during a site migration. There is a script available that will run tests on your MODX site to ensure that the configuration file is configured correctly. See the test_config.php script available as one of the MODX utility scripts here: https://github.com/craftsmancoding/modx_utils