The Coding Pad

Welcome to Part 2 of the MODx Revolution for complete beginners series. In the last post, I briefly introduced this series.  In this installment, we’re going to get hands on by going through the process of installing MODx Revolution so that we can start building our site.  The process of installing Revolution is pretty straightforward, and as long as you have ensured that your server meets the installation requirements, you should have no problems proceeding with the install smoothly.  Should you run into problems, the MODx Revolution documentation covers some common problems that should give you a good starting point for troubleshooting your install.

So far:

Part 1: Introduction to MODx Revolution

There are three ways to install MODx Revolution – Basic, Advanced, and from Git. For this tutorial we’re going to do the basic installation, which is more than sufficient. But if you want to geek out go ahead and check the other options out, see link at end of post.

Throughout this series we are going to be building a MODx Revolution resource website and we will use it as a place to test out different snippets and gather information about MODx and all that good jazz.  As always, I will use a lot of screenshots as I go so that even if you’re not following these tutorials as I create them and my links look nothing like your evolving website, you can still compare your website with my screenshots.

1. Download MODx and Upload to Server

We’ll start out by downloading the MODx install archive file which is found at http://modx.com/software/open-source-cms/modx-revolution/.  At the time of this writing the most recent version is 2.0.0 pl (EDIT: This tutorial series has now been updated to cover 2.2.0 pl2 – February 8, 2012).  You can either download the normal package or the advanced package.  I will be working with the normal package.  We will then upload these files to our hosting environment.  There are two ways to do this:

• Unzip the files and upload them using FTP
• Upload the zip file itself and unarchive it directly on your server.

I prefer the second option since it works faster.

Once you have the files uploaded, your directory structure should look something like the following:

You can read more about the MODx directory structure in the official manual, see link at end of post.

2. Create the Database and Database User

Our files are now uploaded and ready to go. The next step is to create a database and database user.  How you do this will vary depending on your hosting environment and what control panel and tools are provided for you. If you’re unsure of how to proceed, check with your host or search google for information specific to your setup.  If you’re using Wampserver, you can look at http://codingpad.maryspad.com/2009/11/14/creating-projects-databases-users/.

• Ensure that the user you assign to your newly created database has all privileges on the database.
• Note the name of the database and user and user password as you will need these on the next step
• Some hosts prefix the names of databases and/or users with a name specific to your account, so make sure you make note of this.
• If you don’t have the option to do so while creating your database, it’s a good idea before proceeding with the install to check your database character set and collation and set them to utf8 and utf_general_ci respectively (you can do this using phpmyadmin or whichever database admin tool your host provides). I have found that the server I am currently hosting on defaults to the utf8 character set but whenever I create a database the collation is set to latin_swedish, so it pays to check and rectify any mismatches.  More about character sets and collation at the end of the post.

3. Install MODx Revolution

Once you have the files uploaded and your database and database user ready, it’s time to proceed with the install.  In your browser, navigate to the setup folder in the location where you uploaded the MODx files by appending /setup to your site url.

You will then be presented with the first screen initiating the installation process:

3.1 Select Language

Select your language from the dropdown list and click on Setup to proceed to the next step.

3.2 Select Installation Type

At this stage we have the option to select what kind of install we want. Since this is a new website we’ll go with the New Installation option.  If we were upgrading from a previous version of Revolution then we would use one of the Upgrade options.  If you need to, you can modify the folder permission settings in the Advanced Options section, but for most environments the default settings should work fine.

3.3 Connecting to the Database Server and Detecting Collations

In the next step, MODx now needs to connect to the database we created.

• The first field, Database type, refers to the type of database you have. In most cases this will be mysql, but make sure you select the correct option based on what your server supports.
• The second field, Database host, will usually default to localhost, and in most cases you don’t need to change that, unless your hosting company has it set up differently.

 

• In the Database login field, enter the name of your database user that you created, and remember to add a prefix if your host adds one, as mentioned before
• Then enter the password you gave the user in the Database password field.
• The name of the database you created goes in the Database name field, and remember again to add the prefix if there is one.
• Finally, there is the Table prefix field, which by default is set to modx_. You can change this if you wish to, but usually there is no need to.

Once you click on “Test database server connection and view collations”, the MODx installer will attempt to connect to your database and detect the database collations.  If all is set correctly, you should then get a success message that indicates that connection to the database server was successful and collations were set.

The installer now needs to test the selection of the database we created. You notice that the installer can also create the database for you, but not all servers will allow this, so I generally prefer to create the database beforehand and simply select it at this stage.  If we click on the “Create or test selection of your database” we get a success message indicating that our database was successfully found, and we can now create our main admin user and proceed with the installation.

NB: This is one of the points at which most installs seem to hit a snag. I’ve found that the best way to avoid getting stuck at this point is to ensure that you create your database with the correct character set and collation, and to ensure your server meets the recommended requirements for running Revolution.

3.4 Creating Admin User

This step is pretty straightforward and self-explanatory. Here you create your default admin user account, the one you will use to log into the site to start your sitebuild.  Make sure that you remember the username and password you enter here as you will need them later on

3.5 Pre Installation Tests and Installation

Once you enter the user information, clicking Next initiates the Pre-Installation tests.  In this step the MODx installer checks to make sure your server is set up correctly for Revolution to run. If all is good, you should get green check marks on every item on the summary page, indicating that you’re ready to go.  If there are any issues, they will be marked in red and you need to rectify them before you can proceed.

The more common snags have to do with the MySQL server version, folder permissions, and memory settings.  Check with your hosting company to see if these can be rectified.  Checking the MODx community forums may also yield workarounds and solutions to your specific server issues.

Assuming that everything checks out fine, we can now scroll down the page and click the “Install” button.  The install should continue successfully and we get the message that the Core has installed.  You can click the Toggle links to see the success message and warnings (if any).

We then click Next to proceed to the next step to finalize the install.

3.6 Completing the Installation

This final stage reminds us to delete the Setup folder. It is strongly recommended that you do this for security reasons, as you don’t want anyone attempting to run the install again on your site. If you check this box the installer will delete the setup folder from your system.

Once you check this box, click on Login, and the files will be deleted from your server and you’ll be taken to the your site’s login screen.

Ah, sweet success .  You can now log into your site manager using the administrator information that you created in step 3.4.  The manager backend opens up with a Welcome screen with some helpful information, and if you close that you then have access to the MODx Revolution manager (partial view below):

If you navigate to the front view of your website you will find a blank page. And if you right-click anywhere on the page to view source, you notice that there’s really nothing much there.  My source simply looks like this:

As you can see, MODx Revolution gives us basically a blank slate to start with, which is great because there are no constraints as to what our design or layout can be, among other things.

Notes for MODx Evolution Users

If you’re coming from Evolution, you’ll notice a couple of things:

1. There is no option to install a Sample site. You can however get this from the repository using Package management
2. Similarly, there is no default template installed
3. There are no default snippets, chunks, modules, or plugins.

We will be grabbing all these via Package Management and adding them as needed.

In the next installment, we will do some basic site configuration, add some content, and briefly explore the manager as we start to build out our site, so stay tuned, subscribe to the feed, and leave comments with questions, suggestions, corrections, or just to say hey!

More Reading:

MODx Revolution Installation -  http://rtfm.modx.com/display/revolution20/Installation
Explanation of MODx Revolution Directory Structure – http://rtfm.modx.com/display/revolution20/Explanation+of+Directory+Structure
Database Character sets and collation – http://dev.mysql.com/doc/refman/5.0/en/charset-database.html

Go to Part 3: MODX Revolution Basic Configuration and Installing Extras

No related posts.

Related posts brought to you by Yet Another Related Posts Plugin.