In Part I of this tutorial, we uploaded the MODX files to the server. In Part II, we set up the database to prepare for MODX installation. Now, it’s time to actually install MODX by running the MODX setup script.
You will need to have the database name, and the name and the password of the database user we created in part II. You may also want to think about the username and password you will use to log in to the MODX Manager. For maximum security, it’s not a good idea to use the same ones.
To launch Setup, fire up your browser and put this in the address bar: yoursite.com/setup (replacing yoursite.com with the actual URL of your site). Press Enter, and you should see the opening setup screen.
Choose your preferred language and click on the “Select” button, then click on the “Next” button.
On the next screen, the “New Install” checkbox should be checked (unless you’re reinstalling or upgrading MODX). Under “Advanced Options” at the bottom, you’ll see MODX’s best guess about what the file and directory permissions should be. I’d advise you to leave these alone unless you’re sure they are wrong. Click on the “Next” button.
This is the screen where you’ll need to enter the information you wrote down. The database type and the database host are almost certainly correct (MySQL and localhost), so leave them alone. Enter the username of the database user we created earlier in the “Database login name” field. Enter the database user’s password in the Database Password.
In the Database Name field, delete what’s there and enter the database name you wrote down earlier.
The default “Table prefix” is ‘_modx’ and there’s very seldom any reason to change it. The only reason you might want a different prefix is if you have more than one install of MODX using the same database and that’s a fairly rare case.
The values on the screen now will be saved by MODX in the file core/config/config.inc.php (along with some other configuration information). You won’t have to enter them again, even if you upgrade MODX.
Testing the Database Connection
You may have noticed that there’s no “Next” button on this page. That’s because we’re not done here. MODX needs to check the database connection before proceeding.
Click on the “Test database server connection and view collations” link.
You should see a success message, a report of the MySQL version, and the character set and collation. If Part II of this tutorial went according to plan, you should see utf8 and uft8_general_ci. If you don’t, and you’re sure you set up everything that way in Part II, go ahead and change them to that, but check the tables in the database in PhpMyAdmin later to make sure those settings are correct.
There’s still no “Next” button, because we have one more step to perform. Click on the “Create or test selection of your database” link. You should see a success message and a form to enter your MODX credentials. If not, double-check the information above. In rare cases, you may have to contact your host to find out the database host name.
Once you see the success message, enter a username and email address in the first two fields. The username should generally not be anything obvious like ‘admin’ or ‘webmaster’. The username will show up in various places in the Manager and may also show in the front end of the site, so don’t choose anything that you’ll be embarrassed to have people see.
MODX and some MODX extras will use the email address you enter when sending you emails and sometimes as the from and reply-to fields of messages sent to users. You can override this in most cases, but it will be the default and it makes life easier if this is your main email address.
Enter a good, strong password in both password fields, but be careful &mdash the password must contain only numbers and letters (no punctuation, no spaces). If you use punctuation, the install will proceed normally, but you won’t be able to log in. It’s best to avoid common names, dictionary words, pet names, city names, addresses, Social Security numbers or words associated with you such as your street name or the name of a school you attended. There are now hacking bots that can try literally billions of passwords per second and are programmed to use dictionary words with random numbers to try and guess passwords. The longer the password is, the more secure it will be and it should definitely contain both numbers and letters.
Write down your username and password and keep them in a safe place. These are the credentials you’ll use to log in to the MODX Manager where you’ll do the work of creating your web site. Once you’ve entered them, click on the “Next” button.
You should see screen with a series of final checks, and hopefully, a green checkmark and a green “OK” next to each one. If any are not green, you’ll have to correct the problem described in the error message.
If everything is OK, click on the “Install” button. The installation will take a little time, so be patient. When it’s finished, you should see a screen where you can click on links to see Success messages and Warnings. If there are warnings, don’t be too concerned. They’re not uncommon and as long as they’re not in red, you can usually ignore them. Click on the “Next” button.
On this screen, you’ll see a “Login” button, but before you click on it, you need to decide whether to delete the setup directory. On your live site, you definitely don’t want to have the setup directory in place for security reasons. If you’re installing MODX under localhost on your personal computer, there’s not much reason to remove it. In any case, you want to keep a copy of the setup directory in case you need to reinstall this version of MODX some time in the future. You should still have the copy you created in Part I of this tutorial. Save it for future use.
Check or uncheck the checkbox that removes the setup directory, then click on the “Login” button. That will take you to the Manager’s Login screen.
Normally, you’ll get to this Login screen by putting yoursite.com/manager in the browser’s address bar (replacing yoursite.com with the URL of your site).
Enter the Manager Login username and password and click on the “Login” button.
If all went well, you’re looking at the MODX Manager. You’ll see a welcome message, and once you close that, the Dashboard. You may see some warnings here (though on Arvixe, everything was perfect at this point). On other servers, you may see a warning about the config file being writable or register_globals being on. These are security issues that you’ll want to correct. If register_globals is on, you may have to talk to your host about turning it off. If you left the setup directory in place, you’ll see a warning about that as well.
One final note, if you look at the Resource Tree on the left side of the Manager screen, you’ll see that there is only one resource. It’s called “Home”. If you click on it, you can edit it in the right-hand panel. You’ll see that it’s completely empty. If you visited your site at this point, you’d see the Home page, but it would be blank. In the Resource Content field on the right side, type this code:
Then, click on the “Save” button at the upper right. Now you can visit your site and you should be greeted with that message. Congratulations! You’re now an official MODXer!
When previewing a site I’m working on in MODX, I like to use another browser where I’m not logged in to the MODX Manager. When viewing the site in the same browser you’re using for the Manager, your login status is ambiguous and things won’t always appear as they would to a real visitor to your site.