In Part I of this tutorial, we uploaded the MODX files to the server. Now, it’s time to create the MODX Database. If you ran the MODX setup script at this point, it would attempt to create the database for you. On some servers this will work, but even if it does, on many servers (including Arvixe) you’d end up with a Latin1 character set and a collation or latin1_swedish_ci. For odd historical reasons, this is the MySQL default. It can work if your language is English and you never need a foreign word on your site, but sooner or later, you’re going to need to use a word with an accented character that doesn’t play well with Latin1.
The recommended character set and collation for MODX is utf-8 and utf8_general_ci, so I always set up the MODX database ahead of time on order to make sure that the database uses that character set.
Creating the MODX Database
Log in to your Arvixe cPanel if you’re not there already (if you’re in File Manager, cPanel should still be open in another tab of your browser — just close the File Manager tab). Scroll down to the “Databases” section and click on the left-most icon: “MySQL Databases”. That will take you to a window where you can create the MODX database and a user for it.
Note: On some servers, you can create a database with PhpMyAdmin and you can select the character set and collation at that point. This is not possible on Arvixe and many other servers, but if it works on the server you’re using, feel free to do it and select utf8 for the character set and utf8_general_ci for the collation.
There are three things you’re going to want to write down as we work on this panel. The database name, the database user’s username, and the database user’s password. You can’t install MODX without them and they have to be exactly correct. All three are case-sensitive, so make sure to write them down correctly. Note that although you need them to install MODX, they are *not* the credentials you will use to log in to the MODX Manager.
Near the top of the dialog, you’ll see a blank where you can enter the name of a new database. Notice that there is a prefix for the name of the database, usually your own username. You can’t change it so it’s important to remember that the actual name of your database is that prefix, plus the name you choose for the database. If my username if bobray and I enter “modx”, the name of my database is bobray_modx.
Select a name for your database, then click on the “Create Database” button. On the next screen, you’ll see the full name of your database, write it down. Then, click on the
“Go Back” button to return to the previous screen. You should see the name of your database in the table.
Adding a User
At this point, your database doesn’t have any users, so there’s no way to use it. Let’s create a user for it. Near the center of the screen is a section for creating a user. Notice that on Arvixe, and many other hosts, there is also a prefix for the database username just like there was for the name of the database. This will be part of the username. Right under the “Add New User” line, enter a username for your user. Avoid obvious choices like “admin” or “webmaster.” This is a login you will very seldom use, so don’t worry too much about making it memorable and don’t use the username you plan to have for logging in to the MODX Manager (they should be different).
Note: If you use a password manager like LastPass or Roboform, it will probably fill the fields for you here. Just replace those entries.
Enter a strong password for the user (twice). You can click on the “Password Generator” button to get a strong password and then paste it into the password fields.
Write down the full username and the password (carefully) and then click on the “Create User” button. The next screen will show you the actual username and password. Double check them against what you wrote down, then click on the “Go Back” button.
At this point, it might seem like we’re done with the database but there are two more steps. The first is one that many users forget. We have a database and a user, but the two are not actually connected in any way. We still need to add the user to the database.
Adding the User to the Database
Just below the section we used above, there’s a place to add users to the database. The two drop-downs should be set correctly, but double-check to make sure that they contain the names of the user you just created and the database you just created. Click on the
“Add” button. On the next screen, you’ll see a table of permissions to give the user. Click on the “All Privileges” checkbox at the top of the table to check all the permissions. Once they’re all checked, click on the
“Make Changes” button, then on the “Go Back” button.
We have one last step to perform before running the MODX setup script. The database character set and collation are set to Latin1. We need to change that.
Setting the Character Set and Collation
Scroll to the very top and click on the “Home” link at the upper left. That will take us back to cPanel. Scroll down to the “Databases” section and click on the “PhpMyAdmin button (not the one we used before). This is fine for Arvixe, but note that on some servers you get to PhpMyAdmin on a somewhat obscure link on the “MySQL Databases” page or elsewhere.
PhpMyAdmin is an important tool for modifying databases. Under “General Settings” near the center of the screen, the “Server collection collation” should already be set to utf8_general_ci. Change it to that if it’s not.
At the upper left, you should see the name of your MODX database in the list. Select it to tell PhpMyAdmin which database we want to work on. On the next screen, you’ll see an empty table that would show a dizzying list of the MODX database tables if MODX were installed. If it were, we’d see that the collation column was set to the wrong character set. That’s why it’s important to do this first.
Click on the “SQL” tab at the top of the table. On the next screen, there’s blank window where you can enter any MySQL command and execute it on your database. Make sure you see the name of your MODX database at the top of the window. Paste the following code in the window. This has to be exactly right, so paste it, don’t type it:
ALTER DATABASE MyDatabase CHARSET utf8 COLLATE utf8_general_ci;
Important: Before executing the command, change “MyDatabase” to the actual name of your database (it’s written above the window, at the top left of the screen, and on the paper where you wrote it down).
Click on the “Go” button at the right of the SQL window. If you get an “Access Denied” message, it means the database name isn’t correct. You should see a message flash at the top of the window telling you that your query executed successfully.
That’s it for the database. Close the PhpMyAdmin tab of your browser and go to the cPanel tab. Log out using the button at the upper right.
On to Part III where we’ll actually install MODX.