Basic Installation
Last edited by Susan Ottwell on Jul 16, 2014.
Beginning Setup
After you've downloaded MODX Revolution, upload the .zip file to your server. On the server itself, either through your control panel extraction script or in the server's file manager, extract the file to its own directory. Copy or move all the files within the new extracted MODX version directory to the directory that you wish to install MODX into. You may delete the extracted folder and its contents, as well as the MODX .zip file once your installation is complete.
Installing MODX With An Existing Site
Development sites often begin in a subdirectory, and then are moved to the root directory when completed. The subdirectory method is useful if you've got an existing site that must remain available during development, or for subdomain MODX installations. It is also possible to leave MODX in a subdirectory and use .htaccess to rewrite your urls to the root.
Existing Static HTML Site
If your existing site is static html with an index.html or similar start page, you can install MODX into the root folder alongside your static site while developing. When you are ready to go live, rename or move your static html files and MODX will take over. Do not enable Friendly URL's if using this method until after your html files have been moved or renamed. As always, back up your existing site prior to installing MODX Revolution or making any changes to your current file structure.
Existing Other CMS or Dynamically Driven Site
Do not install MODX Revolution into a directory that contains another dynamically driven site or CMS until that site is removed. Use the subdirectory method to develop MODX in this case.
Pre-DNS Transfer Installation to Temporary Directory
If your host provides a temporary installation folder to develop in prior to DNS transfer, once your DNS has been transferred you will need to reference the Moving Your Site to Another Server page and update the configuration files: core/config/config.inc.php, /config.core.php, /connectors/config.php, and /manager/config.core.php paths to point to your new root directory.
Installing MODX Revolution
Start the install process by loading your web browser and running the setup script by navigating to the setup/ folder.
From there you will be asked to choose a language, and be presented with a welcome screen. Click Next when you're ready.
Install Options
After this, you'll be presented with a screen with some Install Options:
The New Installation option should be the only available option for you to choose. If you need to adjust the file permissions for your webserver, you can do so in the textfields below. Most servers will be fine with the default values.
When you're finished, click Next to proceed.
Database Options
From here, you will get a form asking you for your database information:
- Add in your database hostname, which is the URL at which your database is located. For most users, this will be 'localhost'.
- Enter your database user name. On some hosts, your database username is prefixed with the site owner directory name such as siteOwner_modxDatabase. In this case, the entire database name must be entered. Check your database tool in your control panel, or the database itself for such a prefix.
- Your username may also be prefixed with the same site owner directory name. If so, you must prefix your username here the same. i.e. siteOwner_databaseUserName.
- Enter your password.
- Also, if you want, you can specify a different table prefix here. This tells MODX to prefix the tables with this value - this is useful should you want to make multiple MODX installations on one database.
- When finished, click the 'Test database server connection and view collations' link. Should you have any errors, they will show below. If you do have errors, check to make sure your database username and password are correct. Also, if your user does not have access to create a database, you might need to do that manually.
If you have your MySQL server on a different port, specify it like so: "my.database.com;port=3307", with the ;port= appending the IP/hostname.
If you are running your MySQL server with networking disabled, you can specify the socket name like this: ";unix_socket=MySQL".
Support for Microsoft SQL Server was introduced in MODX Revolution 2.1
Depending on your SQL Server's network configuration, there are different ways you may specify your host.
- Named pipe: (local)/SQLEXPRESS
- Tcp/ip: 127.0.0.1,2301 (IP, port)
Due to the way that the PDO driver for SqlSrv works, you may not get an error message or a response back after clicking 'Test database server connection and view collations'. If this happens, it is an indication that there is a problem connecting to the database, authenticating or selecting the database itself. After verifying your settings, click the Back button to go to the previous page, and then Next to get back to the Database Options page.
Collations and Charsets
This will then popup another form for setting your database charset and collation:
For most users you can leave these values at what they are. However, if you need to change them, make sure the collation matches the charset. Click the 'Create or test selection of your database.' after you've finished.
MODX has only been tested with SQL Server's Latin1 character set.
Creating an Administrator User
This form will now present you with a few fields for setting up your administrator user. Specify a username that you want to be the administrator username.
From there, put in your email (or the email of your administrator) and specify a password. Click next when you're finished.
Pre-Installation Checks
MODX will then proceed with a list of checks to verify that your system is ready for installing. If any of these fail, you'll need to proceed with the directions that it suggests to make sure your environment meets the Server Requirements and has the correct directories writable.
Once you're ready, and all the checks pass, click 'Install' to proceed.
- Make sure the directories "/core/packages","/core/cache", "/core/import", and "/core/export" are writable.
- Make sure your php.ini setting sets memory_limit to 128M, and max_execution_time to 120
- Create a blank file "/core/config/config.inc.php" and make it writable. DO NOT COPY config.inc.tpl! Just make it a blank file!
- Post a message in the Revolution forum regarding your issue. State your server setup and installation info, and we'll try and help you find a solution.
Post-Installation Summary
MODX will then let you know if any errors occurred during install, and prompt you to attempt reinstallation should any of those errors have occurred.
When install is successful, click 'Next' to proceed, and you'll be presented with one final option:
MODX recommends that you make sure to remove the setup/ directory after installing, to safeguard your site from anyone else trying to run setup on your site. You can do this by clicking the 'Check this to DELETE the setup directory from the filesystem.' checkbox.
When ready, click 'Login' to be presented with the Login form for the manager interface. You're finished!
Additional Info
Some other special cases:
WAMPServer 2.0i
Please see this article: Problems with WAMPServer 2.0i
MAMP on MacOSX
MAMP (including latest 1.8.4) works fine with MODX Revolution, with one exception. You cannot use eAccelerator as the caching system, as the drivers compiled with MAMP are faulty with regards to PDO and will cause Apache kernel errors. Select the 'xCache' caching drivers to remedy this.
Debian
Debian uses outdated MySQL drivers for its PHP build that will need to be updated; please see the MODX Revolution on Debian article for more information.
Vista and XAMPP
There have been reported problems with installing Revolution on 64-bit Vista with XAMPP. We cannot guarantee a working solution on that OS and setup at this time.
Installing Packages
For information on installing 3rd-party packages, see the How to Install Packages article.
See Also
- MODX Revolution on Debian
- Lighttpd Guide
- Problems with WAMPServer 2.0i
- Installation on a server running ModSecurity
- MODX and Suhosin
- Nginx Server Config
- YouTube video by a MODX Ambassador
Suggest an edit to this page on GitHub (Requires GitHub account. Opens a new window/tab).