Installation of SilverStripe 2.4

Exclusive offer: get 50% off this eBook here
SilverStripe 2.4 Module Extension, Themes, and Widgets: Beginner's Guide

SilverStripe 2.4 Module Extension, Themes, and Widgets: Beginner's Guide — Save 50%

Create smashing SilverStripe applications by extending modules, creating themes, and adding widgets

€20.99    €10.50
by Philipp Krenn | May 2011 | Beginner's Guides Linux Servers Open Source Web Development

SilverStripe is an incredibly powerful system, and yet so easy to use, once you know your way around it. However, getting started can be a little tricky—the installation in particular is sometimes a challenge for newcomers. This doesn't mean SilverStripe is hard to set up, but there are some common pitfalls.

To avoid those, in this article by Philipp Krenn, author of SilverStripe 2.4 Module Extension, Themes, and Widgets: Beginner's Guide, we'll take a look at how to:

  • Set up a development environment on Windows
  • Set up a live environment on Linux
  • Install SilverStripe itself

 

SilverStripe 2.4 Module Extension, Themes, and Widgets: Beginner's Guide

SilverStripe 2.4 Module Extension, Themes, and Widgets: Beginner's Guide

Create smashing SilverStripe applications by extending modules, creating themes, and adding widgets

        Read more about this book      

(For more resources on SilverStripe, see here.)

Setting up the environment

There are many possible scenarios and environments you might require, depending on the complexity of your project. However, we'll keep this short and simple:

  • We'll set up a development environment, which is based on Windows (Windows XP or newer) as it is the most common operating system on desktops and laptops.
  • We'll also set up one live or deployment environment, which is based on Linux as it is the most common operating system for web servers. We'll use Ubuntu in our example as it is freely available and widely used. If you prefer a different distribution some paths and commands will vary, but the general approach should be very similar.
  • In case you want to use a testing or staging environment as well, we'll assume that you simply reuse the previous setup—so we don't need to configure another system.

Now that we've decided on the general purpose of the systems and their operating systems, we'll need to choose between different implementations for setting up the web server and database. Specifically, whether to use prebuilt packages or select the components ourselves.

To demonstrate both approaches we'll use a prebuilt package on our development machine (as we want to get up and running quickly) and handpick the components on our live site, where we want to have maximum control. To keep our development and live environments closely related, we'll use the same applications for both—disqualifying Windows-only solutions:

On Windows there's also Microsoft's Web Platform Installer (http://www.microsoft.com/web/downloads/platform.aspx). It doesn't only include the web server, database and PHP, but also SilverStripe itself (http://www.microsoft.com/web/gallery/silverstripecms.aspx)—which can be downloaded on demand among many other web applications. However, as this is very different to our live site, we won't cover it. If you're looking for a, Windows-only solution this is nevertheless an interesting option as it is very easy to set up.

The Windows development system

Let's start off by setting up our development system, based on the freely available XAMPP package.

Time for action - installing XAMPP

We'll assume that the operating system is Windows XP or newer—for Linux, Mac OS X, and Solaris you should only need to get a different download file and do some minor variations of the steps described:

  1. Download the XAMPP package at http://www.apachefriends.org/en/xampp-windows.html. We're using the 7zip package as it doesn't require an installation, is compact to download and also portable: you can copy it to a USB drive and use the environment on any Windows computer.
  2. Extract the archive to a top-level folder on your internal drive (C:\ for example), or your portable external drive (U:\ for example). To do this, you'll need the free 7zip archive utility, which you can download at http://www.7-zip.org.
  3. Open up the file xampp/mysql/bin/my.ini and add the following line in the [mysqld] section:

    lower_case_table_names=2

    This setting is important for exchanging database dumps between Windows and Linux systems. As Windows paths are case insensitive, MySQL lowercases database and table names by default (as they are internally stored as folders and files), but only on Windows. On Linux proper cases are preserved, which leads to problems when using dumps on different platforms. The previous statement forces MySQL on Windows to behave like on Linux.

  4. Inside the XAMPP folder, start the file xampp-control.exe and use it to Start Apache, MySql and Mercury. XAMPP's control panel should look like this after starting the three applications:

    Installation of SilverStripe 2.4

  5. If a service doesn't start, check that its port is not already in use—this is the main reason for problems. To do this, open the command line tool and enter netstat-ao. This will show you the ports currently in use and the process IDs (PIDs) of the processes using them. Using Window's Task-Manager you can then find out the name of the process causing the problem, and stop or reconfigure it. The following screenshot illustrates this scenario—the web server cannot be started as Skype is already using port 80:

  6. After successfully starting all three services, navigate to http://localhost in your browser. This should redirect you to XAMPP's welcome page.

  7. In case you need to send e-mails for testing purposes, you'll need to perform two additional steps to configure your SMTP server:
    • Enable SMTP relaying of non-local mail. However, ensure that no one can access your mail server from outside or you might be abused as a spam relay (your router or firewall will protect you). In XAMPP's control panel, click on Admin... next to the Mercury label. Next go to Configuration, MercuryS SMTP Server and on the Connection control tab uncheck Do not permit SMTP relaying of non-local mail.
    • Provide a DNS server so domain names can be looked up: Under Configuration, MercuryE SMTP Client fill in the field Name server with your provider's DNS server.
  8. That's it for our general purpose development machine. In case you want to run automatic tests or generate translation files, you'll also need to install PHPUnit through PEAR:
    • While XAMPP includes PEAR and PHPUnit, the bundled versions are hopelessly outdated. Furthermore the update process doesn't work reliably, so we'll better start anew.
    • First remove xampp/php/PEAR/, xampp/php/pear.bat, xampp/php/pear.ini, xampp/php/peardev.bat and xampp/php/pear-update.bat.
    • Next enable PHP's cURL extension: Open xampp/php/php.ini, find the line ;extension=php_curl.dll and remove the leading semicolon.
    • Then download http://pear.php.net/go-pear.phar into xampp/php/.
    • Next install PEAR on the command line (start it as an admin user). Note that you must be in the folder xampp/php/ for the following commands to work:

      php go-pear.phar

    • Now we can use PEAR to update its channels and upgrade all packages:

      pear update-channels

      pear upgrade --alldeps

    • Finally you can install PHPUnit and all of its dependencies:

      pear channel-discover pear.phpunit.de

      pear channel-discover components.ez.no

      pear channel-discover pear.symfony-project.com

      pear install phpunit/PHPUnit

    • That's it, you've successfully installed PHPUnit!

The Linux live system

Next we'll set up our live system. Thanks to package managers this isn't much harder—you just shouldn't be afraid of the shell.

Time for action - installing the requirements by hand

In our example we're using Ubuntu, so we'll rely on its package manager Apt, abbreviation of Advanced Package Tool. Note that we won't only install the bare necessities, but also some more tools to make our system ready for production.

  1. Open the terminal and install the Apache HTTP Server together with PHP and PHP's GD library (needed for image manipulation) through the following commands. Note that all required dependencies are added automatically, though you may need to manually accept them:

    sudo apt-get install apache2 php5 php5-gd

  2. Next we'll install MySQL and its binding to PHP, again through the terminal. You'll be prompted for a password, which we'll need again later on.

    sudo apt-get install mysql-server php5-mysql

  3. Enable Apache's rewrite module, which SilverStripe requires to use pretty URLs:

    sudo a2enmod rewrite

  4. Edit the file /etc/apache/sites-available/default and replace the line AllowOverride None with AllowOverride All inside the <Directory /var/www/> block. This enables the rewrite module inside the /var/www/ folder.
  5. Install Alternative PHP Cache (APC), which will accelerate PHP programs—SilverStripe benefits a lot from this. While there are some alternatives, it is currently planned that APC will be included in PHP 6, which makes it sound like a future-proof decision for our installation:

    sudo apt-get install php-apc

    If you want to see APC in action, you'll need its management tool. By default it is located in the file /usr/share/doc/php-apc/apc.php.gz. Unpack and copy it to your web-root to see detailed statistics on how well it's working for you, but protect it against unauthorized access (you can set credentials inside the file).

  6. Edit the file /etc/php5/apache2/php.ini, using whatever text-editor you prefer (this can be quite a sensitive topic with programmers). Replace the line ;date.timezone = with date.timezone = US/New_York or your current location. See http://php.net/manual/en/timezones.php for all possible values. Note that removing the semicolon at the beginning is important, otherwise the line will be considered a comment.
  7. Restart the web server to apply all the settings we've just made:

    sudo /etc/init.d/apache2 reload

  8. Now it's time to test our installation. Go to the directory /var/www/ which is the default web-root directory:

    cd /var/www/

  9. It should already contain a file index.html, which you can view if you visit http://127.0.0.1 in your browser (or whichever IP address you can access your server under).
  10. However, this is only a static HTML file. To see if PHP is also working, first set the file permissions, assuming our current user is ubuntu (which we'll use to edit files) and the web server is run as www-data (which is the default). So we'll make our user the owner of the files with full permissions, and set the group to the one of the web server with read and execute permissions only:

    sudo chown ubuntu:www-data -R /var/www/

    sudo chmod 0755 -R /var/www/

    After adding new files, you'll need to rerun these two commands.

  11. Next create a file index.php in /var/www/:

    touch index.php

  12. Add the following code to it:

    <?php
    phpinfo();
    ?>

  13. In your browser load the page http://127.0.0.1/index.php (again use your specific IP address). The output should look something like this:

    Installation of SilverStripe 2.4

  14. This shows that PHP is working. Also check that you can find mod_rewrite and a full section on APC in the output to be sure they are enabled.
  15. That's it, our live system is now ready for action. We haven't installed PEAR as we'll assume that testing and translating is done in the development environment, not on the live server.

We've also left out how to install and configure an SMTP server. Unfortunately this is pretty complicated and beyond the scope of this article—especially since you don't want to become a spam relay. If your provider or distribution hasn't already set this up for you, take a look at a specific SMTP server how-to and documentation—Postfix (http://www.postfix.org) is widely used for example.

SilverStripe 2.4 Module Extension, Themes, and Widgets: Beginner's Guide Create smashing SilverStripe applications by extending modules, creating themes, and adding widgets
Published: May 2011
eBook Price: €20.99
Book Price: €34.99
See more
Select your format and quantity:
        Read more about this book      

(For more resources on SilverStripe, see here.)

Installing SilverStripe

The following steps are the same on both systems. You can follow these instructions on either one and then copy your site (that is the code, your database dump and any files you've added to the assets/ folder) to the other—but we'll come to that a little later.

Installation

To keep it simple, we'll assume that you know how to get SilverStripe's core files to your development and live system. The options include:

  • Downloading it from SilverStripe's website in your browser to your development machine: http://silverstripe.org/stable-download/
  • Downloading it through the shell with Wget from the above address to your live environment
  • Uploading the files from your development to your live site through FTP or SSH
  • Getting the code from the official repository or your own one—further directions for this can be found at http://silverstripe.org/version-control/

Time for action - installing SilverStripe

We're assuming you've set up your environment. Additionally, you've added a folder silverstripe/ to your web-root containing all of SilverStripe's core files. In our examples this would either be xampp/htdocs/silverstripe/ or /var/www/silverstripe/.

  1. On Linux, make sure you've set the correct file permissions:

    sudo chown ubuntu:www-data -R /var/www/

    sudo chmod 0755 -R /var/www/

  2. Additionally you'll need to allow the web server to write to the following files and folder. This isn't normally necessary on Windows due to its laxer permission settings:

    chmod 0775 -R /var/www/silverstripe/assets/

    chmod 0775 -R /var/www/silverstripe/.htaccess

    chmod 0775 -R /var/www/silverstripe/mysite/_config.php

  3. Open http://127.0.0.1/silverstripe/ in your browser—if you're not installing on localhost, replace the IP address with the one of your server. You should then be redirected to the installation page which looks like this:

  4. If there are any problems with your installation, SilverStripe will tell you about them and your four Requirements points will be yellow or even red instead of green.
  5. Fill out the database credentials and the database name you want to use for your installation.
  6. Fill out your e-mail address, password, and select your default language.
  7. Hit Install SilverStripe.
  8. This might take a little while as SilverStripe is doing a lot of work in the background. After finishing, you should be redirected to the following page:

  9. As advised, remove the installation file install.php in the web-root either manually or by calling http://127.0.0.1/silverstripe/home/deleteinstallfiles in your browser (requires you to login).
  10. Your installation is now ready. You can access the frontend at http://127.0.0.1/silverstripe/ and log into the backend at http://127.0.0.1/silverstripe/admin.

The site's cache folder
Following the above steps, SilverStripe will automatically create the folder /tmp/silverstripe-cache-var-www-silverstripe/ on Linux where it will put all of its cache files. This is the recommended behavior. If this doesn't work on your system (which sometimes happens) or you want to use caching on Windows as well, create a folder silverstripe-cache/ inside your web-root—so it should be located right next to mysite/, sapphire/, and so on. And don't forget to allow the web server to write to the folder on Linux—just like the assets/ folder.

Troubleshooting

In case something doesn't work out as expected despite all our efforts, don't panic! Common problems include getting an error message or the dreaded white page of death with no output at all.

Debugging

There are three things you should do to debug errors:

  1. Enable SilverStripe's development mode, as it will show you what's going wrong. It isn't enabled by default to guarantee maximum security for default installations. Add the following line to mysite/_config.php:

    Director::set_environment_type('dev');

  2. Take a look at the PHP error log file. If it's empty or you can't find it, correct the log level and its location. This is done in PHP's configuration file, located at xampp/php/php.ini or /etc/php5/apache2/php.ini. The following settings are important when debugging:
    • Log all errors with the following setting: error_reporting = E_ALL | E_STRICT
    • Actually write errors to the log file: log_errors = On
    • Define in which file errors should be logged. The example assumes you're using XAMPP on the C:\ drive: error_log = "C:\xampp\apache\logs\php_error.log"

    Don't forget to restart the web server after changing the configuration, otherwise your changes won't be applied.

  3. Carefully read the error message. In most cases it will clearly tell you what's wrong.

PHP requirements

SilverStripe is a modern and powerful system. While its hardware requirements are not very demanding, you may have problems on very cheap hosting platforms. These generally manifest in PHP errors. Ensure that you fulfill the following requirements:

  • You need at the very least 40 MB of memory (memory_limit in the PHP configuration file we used in the previous section). However 64 MB is recommended and you might need even more in some situations: This depends on your site-specific code or in case you want to generate translation files. In case of problems, PHP will choke up an Out of memory error.
  • Another critical value is the maximum execution time of a PHP script (max_execution_time in the configuration). The default of 30 seconds should be enough in most situations, but if you run into Maximum execution time errors, you'll need to increase this value.

For a general purpose website we're done. However, if you expect a lot of traffic you might need to fine-tune and configure your live installation even further—SilverStripe is capable of scaling with your demands.

Copying data between the development and live site

This is actually pretty simple. Let's assume you've created your development site and are ready to put the first version of your page into production.

  • You'll need to copy all of your files to your live environment—including the core files, your custom code, and anything you've added to the assets/ folder. This can either be done through FTP, SSH, or a version control system such as Git or Subversion.
  • Additionally we need to copy the database. You can either rely on a tool such as phpMyAdmin (http://www.phpmyadmin.net) or use MySQL's built-in command line client, at which we'll now take a short look:
    • On the development machine, start the command line and change into the folder xampp/mysql/bin/. Assuming the database is called silverstripe, we could dump the database to the file silverstripe.sql with the following command:

      mysqldump -u root -p silverstripe > silverstripe.sql

    • On the server create the database. First you'll need to change into the MySQL environment (you'll be prompted for the password), then we'll create the database and finally we'll leave the environment again:

      mysql -u root -p

      CREATE database silverstripe;

      \q

    • Upload the dump to the server.
    • Import the dump with this command:

      mysql -u root -p silverstripe < silverstripe.sql

    Now that we've done that, we'll continue to work on the site locally. Once we or our client are satisfied with the result, we'll need to upload it to the server again.

  • As the core files shouldn't be changed during site development, we'll only need to upload our custom code and any changes to the assets/ folder in future.
  • Assuming the live site's database hasn't changed, we can simply overwrite it with a dump from our development machine.
  • If the live site has been changed, which is the more common situation, we cannot simply overwrite the changes. In this situation you'll most likely need to synchronize any code changes with the "old" database. After adding your code changes call http://127.0.0.1/silverstripe/dev/build?flush=all in your browser. You'll obviously need to replace the above address with your own IP address or domain name and the correct folder (if you're using a subfolder). You'll be prompted to log in as an administrator to apply the changes. After that you can add all your other database changes from the development version to the live site—generally by redoing the required steps like adding new pages or other content.

Summary

Getting SilverStripe up and running isn't so hard after all.

In this article we've taken an in-depth look at how to install a development system on Windows, including all the components necessary for creating a successful website. And we've also shown how to set up a live environment on Linux (Ubuntu specifically).

Finally we've also explored how to install SilverStripe itself, how to troubleshoot possible problems and how to upload your development site to your live server.


Further resources on this subject:


SilverStripe 2.4 Module Extension, Themes, and Widgets: Beginner's Guide Create smashing SilverStripe applications by extending modules, creating themes, and adding widgets
Published: May 2011
eBook Price: €20.99
Book Price: €34.99
See more
Select your format and quantity:

About the Author :


Philipp Krenn

Philipp Krenn lives in Vienna, Austria and studies software engineering. Besides being a student, he also works as a freelance IT trainer and web developer (mostly using SilverStripe, but also some Drupal, CakePHP, and Smarty).

Philipp started using SilverStripe in 2007 while he was one of the students at the Google Summer of Code improving the project. While kicking off the effort to support multiple databases (besides MySQL), he got a good insight into the inner workings of the project. Building on top of that, he became an expert in developing web applications with SilverStripe.

Books From Packt


HTML5 Multimedia Development Cookbook: RAW
HTML5 Multimedia Development Cookbook: RAW

Object-Oriented Programming with PHP5
Object-Oriented Programming with PHP5

Object-Oriented JavaScript
Object-Oriented JavaScript

Hacking Vim 7.2
Hacking Vim 7.2

Yahoo! User Interface Library 2.x Cookbook
Yahoo! User Interface Library 2.x Cookbook

PHP 5 CMS Framework Development - 2nd Edition
PHP 5 CMS Framework Development - 2nd Edition

Amazon SimpleDB: LITE
Amazon SimpleDB: LITE

Firebug 1.5: Editing, Debugging, and Monitoring Web Pages
Firebug 1.5: Editing, Debugging, and Monitoring Web Pages


Code Download and Errata
Packt Anytime, Anywhere
Register Books
Print Upgrades
eBook Downloads
Video Support
Contact Us
Awards Voting Nominations Previous Winners
Judges Open Source CMS Hall Of Fame CMS Most Promising Open Source Project Open Source E-Commerce Applications Open Source JavaScript Library Open Source Graphics Software
Resources
Open Source CMS Hall Of Fame CMS Most Promising Open Source Project Open Source E-Commerce Applications Open Source JavaScript Library Open Source Graphics Software