In this chapter, you'll learn what you need to get your own concrete5 site up and running on your local computer. You don't need to have a lot of experience with Apache, PHP, and MySQL configuration as we're going to use Bitnami, which will install all necessary components in almost no time.
Before you can start working with concrete5, you have to set up an environment, where you can test and play around with concrete5 to get used to it. If you have a web hosting account, you can install concrete5 there, but since that isn't always the case, we'll install everything concrete5 needs to work smoothly on your local Windows computer. We're assuming that you're working with Windows but instructions are available for those running Mac OS or Linux; most instructions work the same for all operating systems.
Bitnami installs a local web server, which we'll use to build and test the add-ons we're going to create. In the last chapter of this book, we're going to move the site from your local computer to a live web server.
There are a few tools you need, before you can start with the installation process. You probably already work with similar tools, but let's still make sure you've got everything before continuing.
concrete5 supports all major browsers as long as you're working with an up-to-date version. Please note: you can create a website which is viewable with an outdated browser, but the in-context editing system won't work correctly, unless you're using a modern browser.
Whether you use Firefox, Chrome, Safari, or Internet Explorer doesn't really matter. concrete5 works with any recent browser with JavaScript capability, but it's recommended to use the latest browser version since most concrete5 community members test new releases with the newest browsers.
Since we're going to edit PHP files you'll need a text editor. The requirements are quite small; you can pick almost any text editor you want. Just make sure it does support PHP syntax highlighting. Here are some possible editors:
PSPad (Windows only, free), http://www.pspad.com. A simple text editor with in-built FTP support. This can make a quick fix on your website even quicker.
TextWrangler (Mac OS only, free), http://www.barebones.com/products/textwrangler/. A very slick and clean text editor with extensive FTP support.
Notepad++ (Windows only, free), http://notepad-plus-plus.org/. A small and fast replacement for Windows notepad.
There are a lot more text editors, as mentioned previously; you can use almost any editor you want. If you're familiar with another product, just go with it. You won't find anything in this book where you need a special text editor feature.
The same with the file archive utility, there are plenty of tools out there and if you want, you can use the in-built extraction utility of Windows or Mac OS. If you're looking for something more advanced, you can go with 7-Zip at http://www.7-zip.org/ or IZArc at http://www.izarc.org/; both are free and do a good job.
Once more, there are lots of choices. You'll have to change file permissions later, so make sure your FTP client includes this option. A powerful and well known client is FileZilla, http://filezilla-project.org/. It's free as well and has a lot more features than we need.
If you think you've found all the tools you'd like to use to create your website, you're ready to install Bitnami. Bitnami is a WAMP stack which provides a lot of different tools needed to run your favorite open source web application on your computer. WAMP is the short form for: Windows, Apache, MySQL, and PHP. The more common term is LAMP and describes the same, but for Linux. It's basically a combination of different applications.
There's a stack for concrete5 that installs everything including concrete5 in no time, but since we want to have a look at the process of installing concrete5 as well, we're going to use the WAMP stack. If you're working with Mac OS or Linux, check Bitnami MAMP, or LAMP; the process is pretty much the same for all the operating systems.
concrete5 is a PHP application which uses PHP as its programming language in combination with a MySQL database. There are lots of possibilities to meet the requirements of concrete5. The preferred web server is Apache but IIS like any web server supporting PHP works as well, but only Apache is supported by the core team.
If you already have a server or a local Apache, PHP, and MySQL set up, you can skip this step and continue with the Downloading concrete5 section a few pages ahead. Otherwise, we are going to need to install Bitnami WAMP stack on your local computer by following these simple steps:
Go to http://bitnami.org/stacks/ and select the MAMP stack for Mac OS, WAMP for Windows, and LAMP for Linux. On the next page, click on Installer and double-click the
EXEas soon as it has been downloaded. You should see the following window or a dialog you have to confirm if files downloaded from the Internet aren't executed directly on your computer:
Click on Next to get to the next installation screen. Here you'll see a screen with a number of preselected components. We don't need them, as we're going to install concrete5 as our Content Management System (CMS) and framework. phpMyAdmin can't be unselected, but that's okay.
Click on Next once more and you'll be asked to specify the installation folder. You can keep the suggested value but feel free to change it if you prefer a different location. For this book, we used Version 5.4.10. Your version might be higher. Cause the WAMP folder will have the version number in the name, all follow-up.
Click on Next again and you'll be asked to enter the MySQL password for the user
root. It's important to keep it saved as this is the main user to access your database. You'll need this password later when we install concrete5.
There are a few more screens; click on Next and you'll have to enter the port number for Apache as well as MySQL in the following screen. You can keep the port number
80for Apache and3306for MySQL. However, it might be possible that another application is already using one or both of these ports, in which case you have to disable the existing application or use a different port number. It's not a problem if you change these numbers; just make sure that you remember the port numbers as you'll need them later when we install concrete5.
After you've clicked your way through all the screens and confirmed the launch process at the end, you should have a running MySQL server as well as a working Apache web server with all necessary components to run a concrete5 site on your local computer. Before we install concrete5, let's make a small change to the MySQL configuration. MySQL table names are not case sensitive on Windows. This will cause some problems if you want to move your site to a Linux server where MySQL is by default set up with case sensitive table names. If you don't feel comfortable with this change, it's not necessary, but recommended if you move your site to another server at some point.
To change this, if you work with concrete5, do the following:
Go to the directory where you've installed Bitnami and open the folder
mysql; it should look as follows:
The
my.inifile contains several settings related to MySQL. Open the file and insert the following line immediately after themysqldsection:lower_case_table_names = 0
The
mysqlsection should look like as follows:
Now that MySQL is properly configured, locate the manager tool in your start menu. You should be able to find it in All Programs | Bitnami WAMP Stack | Manager tool and open it. You should see the following dialog:
Select MySQL Database and click on the Restart button in the right pane. The buttons go gray. When the buttons return to their regular state the restart of MySQL is complete.
If everything worked you should be able to open your browser and enter
http://localhost/.
There's also one small change we have to make to the Apache configuration in order to make sure we can use a file called .htaccess, which allows concrete5 to change certain Apache configurations. Follow these steps:
Go to the directory where you've installed Bitnami and open the folder
apache2and thenconf.Within that directory, open the file called
httpd.conf.Look for a section which starts with
<Directory "C:/BitNami/wampstack-5.4.10-0/apache2/htdocs">and then look after a property calledAllowOverride. You'll have to change its value fromNonetoAll.The relevant part should look like as follows afterwards:
DocumentRoot "C:/BitNami/wampstack-5.4.10-0/apache2/htdocs" <Directory "C:/BitNami/wampstack-5.4.10-0/apache2/htdocs"> # # Possible values for the Options directive are "None", "All", # or any combination of: # Indexes Includes FollowSymLinks SymLinksifOwnerMatchExecCGI MultiViews # # Note that "MultiViews" must be named *explicitly* --- "Options All" # doesn't give it to you. # # The Options directive is both complicated and important.Please see # http://httpd.apache.org/docs/2.4/mod/core.html#options # for more information. # Options Indexes FollowSymLinks # # AllowOverride controls what directives may be placed in.htaccess files. # It can be "All", "None", or any combination of the keywords: # Options FileInfo AuthConfig Limit # AllowOverride All # # Controls who can get stuff from this server. # Require all granted </Directory>After you've saved the change, go to the Bitnami Manager tool, select the
Apache Web Serverprocess, and restart it.
The Bitnami WAMP Stack setup package installed a working web server, including PHP with the most commonly used modules and a MySQL database. This is what a lot of web applications need, and you can use this environment for other CMSs as well.
You've also had a quick look at one MySQL configuration file to avoid problems when moving your data to a Linux server. If you want to know more about this setting, the MySQL documentation is going to answer almost any question about table names: http://dev.mysql.com/doc/refman/5.5/en/identifier-case-sensitivity.html.
We also enabled support for .htaccess files in Apache. We'll need it later in this chapter when we enable pretty URLs.
Like any other software, concrete5 needs certain things to run. Try to answer the following questions.
Q1. Which of the following server-side programming language(s) has been used to build concrete5?
PHP
Microsoft ASP
Java
All of the above
Q2. Which of the following database(s) can you use with concrete5?
PostgreSQL
MySQL
Oracle
All of the above
Q3. Which of the following operating system(s) can you use to run concrete5?
Microsoft Windows
Mac OS X
Linux
All of the above
Q4. Name the web server(s) you can use to run concrete5:
Microsoft IIS
Nginx
Apache
lighttpd
Before we can install anything we have to get the latest concrete5 version from this URL: http://www.concrete5.org/developers/downloads/. After downloading the zip archive for concrete5, follow these steps:
Remove all the files and directories from Bitnami in the directory at
C:\BitNami\wampstack-5.4.10-0\apache2\htdocs.Open the ZIP archive, open the first directory in it, and extract all the files to
C:\BitNami\wampstack-5.4.10-0\apache2\htdocs.After you've extracted the ZIP file you should see a structure like that shown in the following screenshot:
You've downloaded and extracted the concrete5 CMS files. Depending on your archive utility it might have happened that empty folders like updates, files, and others haven't been created. Make sure your structure looks like the one shown in the preceding screenshot.
Before we continue, a few words about the file structure you've just created. It's important that you understand the structure of concrete5 before you start working with it. It's helpful to have a clear understanding about the structure so you can find your files easily. You'll later see that all add-ons in the marketplace follow this structure. Using the suggested structure helps to keep the structure clean, no matter who builds the concrete5 site or add-on.
It might look a bit bulky to have so many folders in the root of your website, but you'll realize that it makes perfect sense to have this structure the more you work with concrete5. We'll have a closer look at some of the directories later in this chapter.
Use phpMyAdmin, which is included in the Bitnami stack, to create the database:
Open
http://localhost/phpmyadmin/in your web server and you should see the following page:
Log in with the user
rootand the password you've entered during the installation process of Bitnami.Click on the Users tab and then on Add user and enter the following values:
Make sure you remember the password as you'll need it later when we install concrete5. Also make sure you select the radio button Create database with same name and grant all privileges. Click on Add user to confirm all values and continue creating the users and database.
We just created a new user called concrete5 as well as a database with the same name. There's one more change we have to make before we can use the new database for concrete5. In the left-hand column, select the new database and then click on Operations:
Change the value for Collation to
utf8_general_ciand confirm the change by clicking on Go. With this step, we made sure that our database and therefore concrete5 can work with non-Latin characters such as umlauts and even Japanese or Chinese characters.
To install concrete5 follow these steps:
Open your favorite browser and enter
http://localhost/. You should see the following installation screen:
There are a number of checks that make sure your environment supports all the necessary functions needed for concrete5 before installing it. Our Bitnami stack contains everything and therefore only shows you green icons. A few words about the required items:
PHP: Whenever possible, try to use the latest PHP version but make sure you run at least 5.2.4.
JavaScript enabled: The concrete5 interface uses a lot of JavaScript to make things easy and smooth to use. It won't be possible to edit any content if you disable JavaScript in your browser.
MySQL available: concrete5 needs a MySQL database; no other databases are supported.
Supports concrete5 request URLs: By default you'll see
index.phpin each concrete5 URL you open. To get rid of this, you need to have the Apache modulemod_rewrite, which we're going to deal with later in this chapter.Image manipulation available: There are a number of functions such as the creating of thumbnails, which need image libraries in PHP.
XML support: In concrete5 you'll have some XML files to describe data structures, which is why XML support is mandatory.
Writable files and configuration directories: Usually not a problem if you work with a WAMP stack on Windows. The web server must be able to write some files in your website's installation directory. We'll discuss this issue later, when we move the site to the production server.
Cookies enabled: Cookies are used in the log in process and must be enabled in your browser.
Once you've managed to get every icon to be green, click on Continue to Installation to get to this screen:
To install concrete5 you have to enter the following information:
Name Your Site: You can enter any name you want, which can be changed in the dashboard later.
Email Address: This is the admin mail address. Make sure it exists; this is where you'll receive a link to change the eventually forgotten admin password.
Password: This is the password for the user admin; make sure it's not too easy since admin is the main user with access to everything in concrete5.
You will also have to enter the following database information:
Server: Since the database is running on the same machine as the web server, just enter
127.0.0.1. If you changed the default MySQL port from3306to something else like3307, use127.0.0.1:3307.MySQL Username, MySQL Password, and Database Name: concrete5 or whatever you used when you created the user in phpMyAdmin.
Next is the Sample Content section. If you select Sample Content with Blog, concrete5 will create a few pages to play around with. Enable this; if you're new to concrete5, it will create some nice pages where you can see the different blocks you can use to build your website. You can remove those pages later.
If you've entered all the necessary information, click on Install concrete5!
A few seconds after you've clicked on Install concrete5 you should see a screen with a confirmation that your site is up and running. Navigate to the actual site available at http://localhost/ and you should see the following screen:
You might
wonder why we've used 127.0.0.1 and not localhost when connecting to the MySQL database. Both values would work, but it can happen that localhost is much slower because it resolves to an IPv6 address on Windows, in which case you'd run into a timeout first because MySQL doesn't support IPv6.
After you've successfully installed concrete5 you'll find a file called
site.php in the config directory. This is where the installation process has saved the information you've entered during the process. Here's how it looks:
<?php
define('DB_SERVER', '127.0.0.1');
define('DB_USERNAME', 'concrete5');
define('DB_PASSWORD', 'concrete5');
define('DB_DATABASE', 'concrete5');
define('PASSWORD_SALT', 'C8MKVa6UZveKlYxFGvmFFqspBAOR5hLjMf9Xsz');DB_SERVER,DB_USERNAME,DB_PASSWORD, andDB_DATABASEare obviously just database related. If the credentials to access your MySQL database have changed, this is where you have to modify them to make sure concrete5 can access your database.PASSWORD_SALT: This is a random string used in combination with the password to generate the password hashes found in the user table. Salts are used to complicate dictionary attacks and even if they are useless without a password, you should still not publish a real password salt to keep your site safe.
Q1. You'll often have to check or modify a few lines in the configuration file, so where can you find it?
<concrete5 installation directory>\config.php<concrete5 installation directory>\config\config.php<concrete5 installation directory>\config\site.php
There are a few different caching functions in concrete5 which can improve the performance of your site but also make things difficult if you keep changing the files. If you change a file without telling concrete5 anything about it, it will keep using the old values in the cache and not reflect the changes you've made. It's therefore recommended to disable all caches while working on a new site.
Follow these steps to disable all caches in concrete5:
Log in to concrete5 and type
cache settingsin the intelligent search box and select the first entry in the result.In the screen you can see now, select all the radio buttons labeled as Off and confirm the change by clicking on Save.
We just disabled the cache in concrete5 to avoid some potential problems with outdated results. In the last chapter when we upload the site, we'll enable the cache again!
When you browse to a subpage in your concrete5 site you'll notice an odd thing in every URL; there's index.php in it like in http://localhost/index.php/about/. Every request to a page in concrete5 is processed by index.php, this has several advantages. It's easier to check the permissions because there's a single point where the page rendering happens.
But even with these advantages you probably don't like to see index.php in every URL. Luckily it's rather easy to change it if your web server supports rewrite rules. Our Bitnami stack does, but only because we previously changed AllowOverride to All in the relevant section before. Now that we have everything needed for pretty URLs, here's what we have to do to get rid of index.php.
Follow these steps to get rid of the index.php from your URLs:
Log in to concrete5.
Click on the Intelligent Search box in the top-right corner.
Type
pretty, and while you type, concrete5 searches for the correct entry. Once found, click on Pretty URLs.Check Enable Pretty URLs and hit on Save; you should see the following screen:
concrete5 should have created a file called
.htaccessin the root of your website (C:\BitNami\wampstack-5.4.10-0\apache2\htdocs\.htaccess). This is the file where the rewrite rules are stored that removeindex.phpfrom the URLs.
Congratulations, you're done! concrete5 is running and you've also activated some options to improve the behavior of concrete5.
You've enabled pretty URLs, which uses the Apache mod_rewrite module to rewrite URLs. You can now open a subpage by entering http://localhost/about/ without having index.php in the address. In case you'd like to know more about this Apache feature, this is the official documentation:
http://httpd.apache.org/docs/2.2/mod/mod_rewrite.html
.htaccess
is a configuration file most commonly used by Apache to configure Apache modules on a directory level. It's a simple text file you can open with any text editor of your choice. If you haven't worked with Apache before, the content might be a bit confusing but concrete5 took care of it. You shouldn't have to modify anything on your own in this file.
Note
Pretty URLs can also be used with Microsoft IIS but you need to install a rewrite filter first.
If you want to try it on your own, you can find a solid and free rewrite filter at this address: http://iirf.codeplex.com/.
As mentioned previously, there are a lot of folders in concrete5. Most of these top level folders are empty—resist the temptation to delete these as they are required for customizations. To give you a head start, here's a short list of the most important folders:
Folder | Explanation |
|---|---|
| You can find custom blocks and block templates in this folder. You'll learn more about blocks in the next few chapters. |
| Probably the most important part, this is where all core files, the actual CMS is located. Never update anything in this folder. |
| The folder where concrete5 puts the configuration files. |
| The file manager stores your files in this directory. |
| This is where you have to put add-ons if you install them manually. |
| The concrete5 auto update feature puts the new core in this directory. Never update anything in this folder. |
There are a few more folders but you probably won't need them unless you dive deep into concrete5. There's one important thing to remember when working with concrete5: The directory concrete looks a lot like the root directory, but never change anything in the concrete directory. You'll find several directories in both places. That's because you can override a single file by placing it in the same structure in the top level.
Here's one example without going into too much detail. Later in this book, we're going to work with a block called content block, a few times. This block basically adds a formatted text to your page. The actual output is printed from this file: /concrete/blocks/content/view.php. How can we change that file without causing any problems with updates? Simply copy the file and place it here: /blocks/content/view.php. The structure is the same; there's just no concrete in the path. You'll have to create some directories first, but at the end, you just copy and paste a file and can then change
its content.
As we've mentioned previously, every request to a page in concrete5 is forwarded to index.php. You might be able to see this by looking at the URL which starts with index.php, but if you enabled pretty URLs, this is hidden by some Apache mod_rewrite instructions. No matter which option you're using, index.php
is always involved.
The actual logic is located in a file included by index.php, which you can find in concrete/dispatcher.php. Every time you request a page, the code of the dispatcher is executed. If you want to dig deeper into concrete5, you'll want to have a closer look at this file at some point. For now, let's just have a look at this quick summary of what happens in the dispatcher:
Initializing the error handling
Fetching all constants and configurations necessary for the site
Loading the database classes and establishing a connection
Creation of a session necessary to remember things such as login information
Loading all settings related to localization
Checking events that have to be run at some point
Parsing of the URL and fetching the correct object from the database related to the current URL
Rendering of the page object as well as all its blocks
You can find more information about the dispatcher flow on this page: http://www.concrete5.org/documentation/introduction/dispatcher-and-application-flow/.
You've reached the end of the first chapter!
You should now have a working concrete5 installation from where you'll learn how to work with concrete5
In case you have to check or modify your concrete5 configuration, you should know where to find the files
We've looked at the requirements to run concrete5
All the tools you'll need to go through this book should be installed on your computer
We're going to use this test site to build our own demo site including some block customization
