path: root/_site_build/_posts/2012-06-03-how-to-install-magento-on-ubuntu.markdown

---
layout: post
title: How to install Magento on Ubuntu
author: David T. Sadler
description: By the end of this guide you will have installed Magento locally on Ubuntu.
categories: ["Magento","Ubuntu"]
robots: follow, noodp, noydir, noarchive
comments: true
google_plus: true
twitter_share: true
facebook_like: true
published: true
licensed: true
---
By the end of this guide you will have installed Magento, and some sample data, locally on Ubuntu. This will allow you to get to grips with the software before installing it onto a production server. In addition to Magento I will take you through installing Apache, PHP and MySQL. I'm going to assume that you are using Ubuntu 12.04 (Precise Pangolin) and that you wish to install version 1.7.0.0 of Magento. You're results may vary if you are using different versions.

As this is quite a long post I have broken it down into various sections. Feel free to ignore those parts that are not relevent for you.

* [Getting started.](#start)
* [Installing and configuring the Apache HTTP server.](#apache)
* [Installing PHP.](#php)
* [Installing the MySQL database server.](#mysql)
* [Creating the directory from which Magento will be served from.](#directory)
* [Configuring the Apache Virtual Host.](#vhost)
* [Installing Magento.](#magento)
* [Running the Magento setup wizard](#wizard.)

<h2 id="start">Getting started.</h2>

If you have never heard of Magento the following from the <a href="http://www.magentocommerce.com/" rel="external nofollow" target="_blank" title="Go to the Magento website">website</a> will explain.

<blockquote cite="http://www.magentocommerce.com/product/faq#What%20is%20Magento?">
  <p>Magento is a feature-rich eCommerce platform built on open-source technology that provides online merchants with unprecedented flexibility and control over the look, content and functionality of their eCommerce store. Magento’s intuitive administration interface features powerful marketing, search engine optimization and catalog-management tools to give merchants the power to create sites that are tailored to their unique business needs. Designed to be completely scalable and backed by Varien's support network, Magento offers companies the ultimate eCommerce solution.</p>
  <footer>&mdash; <cite><a href="http://www.magentocommerce.com/product/faq#What%20is%20Magento?" rel="external nofollow" target="_blank" title="Go to the Magento FAQ">Magento Frequently Asked Questions</a></cite></footer>
</blockquote>

Magento is available in two editions, Community and Enterprise. The Enterprise edition is the company's commercial version of the software and is meant for large-scale eCommerce users. The Community edition on the other hand is available as a free download under the open source OSL 3.0 license and is the version that you will be installing.

This post will walk you through every thing you need to get a local copy of Magento running on Ubuntu. It is not meant as a guide to installing a fully working eCommerce store located on a production server.

To begin, open up a terminal and enter the command below.

{% highlight bash %}
sudo apt-get update
{% endhighlight %}

This will ensure that the computer's database of software packages is updated to contain the latest versions. While this command is not strictly necessary, I tend to issue it before installing any software so that the most up to date versions of the packages are used.

<h2 id="apache">Installing and configuring the Apache HTTP server.</h2>
Apache is easily installed by entering the following command.
{% highlight bash %}
sudo apt-get install apache2 -y
{% endhighlight %}

During the install you may notice the following warning:
{% highlight console %}
apache2: Could not reliably determine the server's fully qualified domain name, using 127.0.1.1 for ServerName
{% endhighlight %}

This comes from Apache itself and means that it was unable to determine its own name. The Apache server needs to know its own name under certain situations. For example, when creating redirection URLs.

To stop this warning we can create an Apache config file to store the name. On a production server you would set this as either a hostname or a <abbr title="Fully Qualified Domain Name">FQDN</abbr>, but for local development we can get away with using 'localhost'.

{% highlight bash %}
sudo bash -c "cat >> /etc/apache2/conf.d/servername.conf <<EOF
ServerName localhost
EOF"
{% endhighlight %}

In order for this change to take effect restart Apache. The warning should no longer appear.

{% highlight bash %}
sudo service apache2 restart
{% endhighlight %}

One of the features of Magento is its URL rewriting. By default Magento will use category and product IDs when generating URLs. With the rewrite tool you can create more SEO friendly URLs for your store. So rather than the URL below,

{% highlight console %}
/catalog/product/view/id/16
{% endhighlight %}

you can instead use,

{% highlight console %}
/size-6-red-shoes.html
{% endhighlight %}

In order to take advantage of this feature we need to enable Apache's rewrite module with the `a2enmod` command.

{% highlight bash %}
sudo a2enmod rewrite
sudo service apache2 restart
{% endhighlight %}

<h2 id="php">Installing PHP.</h2>
As can be seen from the list of system <a href="http://www.magentocommerce.com/system-requirements" rel="external nofollow" target="_blank" title="Go to the list of Magento requirements">requirements</a>, Magento needs PHP version 5.2.13 or later with the following extensions.

* PDO_MySQL
* simplexml
* mcrypt
* hash
* GD
* DOM
* iconv
* curl
* SOAP

We will therefore install PHP with the following command.

{% highlight bash %}
sudo apt-get install php5 php5-curl php5-gd php5-mcrypt php5-mysql -y
{% endhighlight %}

<h2 id="mysql">Installing the MySQL database server.</h2>
The command below will install MySQL. Note that the install process will ask you to create and confirm a password for the root user. Remember the password that you enter as it will be needed later.

{% highlight bash %}
sudo apt-get install mysql-server -y
{% endhighlight %}

<h2 id="directory">Creating the directory from which Magento will be served from.</h2>
Before we get into the business of creating the directory I need to point out a few things. The process below is heavly infulenced by how I setup websites when developing locally. The actual whys and wherefores of how I do this is are too long to go into detail in this post but can be summarised as such.

* Each site is served from its own directory named after the site's domain name. E.g, `my-example-site.com`
* Group ownership of these directories, and their contents, is set as `www-data`. The same group that the Apache process runs under.
* The directories are located in a `public_html` directory that has been created in my home directory.

Many of the commands that follow use absoulte paths when refering to directories located in my home directory. Since the username on my computer is `dev` you will need to replace any occurrences of this with your own username. Feel free to also change the location of any of the directories. Just remember that you must use the correct location when configuring the virtual host later on.

The first thing we need to do is ensure that you belong to the same group as the Apache process. Note that after entering the command you must log out and then log back in before the system will recognise that you belong to a new group.

{% highlight bash %}
sudo usermod -a -G www-data dev
{% endhighlight %}

You can use the `groups` command to check that you belong to the `www-data` group. As long as it appears in the list of groups you can move on to creating the required directories.

{% highlight bash %}
mkdir /home/dev/public_html
chgrp www-data /home/dev/public_html
{% endhighlight %}

As both you and Apache need read and write access to the directory we have used the `chgrp` command to change its group to be `www-data`. However, any new files or directories that you create within `public_html` will not inherit the same group. We therefore need to change the permissions to include the &quot;setgid&quot; bit.

{% highlight bash %}
sudo chmod 2750 /home/dev/public_html
{% endhighlight %}

We can now create the directory that Magento will be served from and it will be given the `www-data` group automatically.

{% highlight bash %}
mkdir -p /home/dev/public_html/magento-store.com/{public,log}
{% endhighlight %}

<h2 id="vhost">Configuring the Apache Virtual Host.</h2>

We will create a simple virtual host configuration file that will instruct Apache to serve the contents of the directory `/home/dev/public_html/magento-store.com/public` for any requests to `localhost.magento-store.com`

{% highlight bash %}
sudo bash -c "cat >> /etc/apache2/sites-available/magento-store.com <<EOF
<VirtualHost *:80>

  ServerName  localhost.magento-store.com
  ServerAlias www.localhost.magento-store.com

  DocumentRoot /home/dev/public_html/magento-store.com/public

  LogLevel warn
  ErrorLog  /home/dev/public_html/magento-store.com/log/error.log
  CustomLog /home/dev/public_html/magento-store.com/log/access.log combined

</VirtualHost>
EOF"
{% endhighlight %}

Using the `a2ensite` command and restarting Apache will load the new configuration file.

{% highlight bash %}
sudo a2ensite magento-store.com
sudo service apache2 restart
{% endhighlight %}

To ensure that the domain `localhost.magento-store.com` resolves locally to the computer we need to add some entries to the system's `hosts` file.

{% highlight bash %}
sudo bash -c "cat >> /etc/hosts <<EOF

# DNS for localhost magento store development.
127.0.0.1 localhost.magento-store.com
127.0.0.1 www.localhost.magento-store.com
EOF"
{% endhighlight %}

If everything has gone according to plan you should be able to open a browser and navigate to `localhost.magento-store.com` where you will see a directory listing as shown below.

<figure>
![Browser showing the directory listing when going to localhost.magento-store.com](/img/localhost.magento-store.com.png "Visiting localhost.magento-store.com for the first time.")
</figure>

<h2 id="magento">Installing Magento.</h2>

Log into MySQL with the following command. Note that it will prompt you to enter the root user password that you specified as part of the MySQL install.

{% highlight bash %}
mysql -u root -p
{% endhighlight %}

We need to create a database for Magento and a MySQL user that it can use to access it. For local development it is fine to use the value &quot;magento&quot; for not only the database name but for the user's name and password. On a production server you would use something a lot more secure.

{% highlight mysql %}
CREATE DATABASE magento;
INSERT INTO mysql.user (User,Host,Password) VALUES('magento','localhost',PASSWORD('magento'));
FLUSH PRIVILEGES;
GRANT ALL PRIVILEGES ON magento.* TO magento@localhost;
FLUSH PRIVILEGES;
exit
{% endhighlight %}

Change into the directory where we wish to perform the install. 

{% highlight bash %}
cd /home/dev/public_html/magento-store.com/public
{% endhighlight %}

You now need to download the tar archive of the source code and unpack it.

{% highlight bash %}
wget http://www.magentocommerce.com/downloads/assets/1.7.0.0/magento-1.7.0.0.tar.gz
tar -xzvf magento-1.7.0.0.tar.gz
{% endhighlight %}

The source code is located in a directory called `magento`. Since we don't want Apache to serve Magento from this sub-directory we need to move the source code out of it.

{% highlight bash %}
mv magento/* magento/.htaccess .
{% endhighlight %}

We should now tidy up after ourselves by removing any unnecessary files.

{% highlight bash %}
rm magento-1.7.0.0.tar.gz
rm -r magento
{% endhighlight %}

Since testing an eCommerce store without any products is not much fun we will install some sample data. First download and extract the tar archive that Magento provides for us.

{% highlight bash %}
wget http://www.magentocommerce.com/downloads/assets/1.6.1.0/magento-sample-data-1.6.1.0.tar.gz
tar -xzvf magento-sample-data-1.6.1.0.tar.gz
{% endhighlight %}

The archive provides a sql file and various assets such as images. The assets need to be moved from the sample sub-directory and put into the `media` directory of the Magento source. The sql file is also moved to make it easier for loading into MySQL. 

{% highlight bash %}
mv magento-sample-data-1.6.1.0/media/* media/
mv magento-sample-data-1.6.1.0/magento_sample_data_for_1.6.1.0.sql data.sql
{% endhighlight %}

We need to log into MySQL again but this time we will use the MySQL user `magento` that we set up earlier. 

{% highlight bash %}
mysql -u magento -p
{% endhighlight %}

When prompted enter `magento` as the password and then enter the following sql statements to load in the sample data.

{% highlight mysql %}
USE magento;
SOURCE data.sql;
exit
{% endhighlight %}

Again we can now remove any unnecessary files.

{% highlight bash %}
rm magento-sample-data-1.6.1.0.tar.gz
rm -r magento-sample-data-1.6.1.0
rm data.sql
{% endhighlight %}

When you run Magento for the first time you will be taken through the setup wizard. This needs to have permission to create files and directories where necessary. We therefore need to ensure that the correct write permission is set on the following.
 
* The directory `var`
* The file `var/.htaccess`
* The directory `app/etc`
* All directories under `var/package`
* All directories under `media`

Since the Apache process runs under the `www-data` group we can use the `chmod` command to give write permission to the this group.

{% highlight bash %}
chmod g+w var var/.htaccess app/etc
chmod -R g+w var/package/ media
{% endhighlight %}

<h2 id="wizard">Running the Magento setup wizard.</h2>

Now that everything is setup, open your browser and navigate to `localhost.magento-store.com` where you will start the setup wizard as show below. 

<figure>
![Browser showing the Magento setup wizard](/img/magento-setup-wizard-step-1.png "Starting the Magento setup wizard.")
</figure>

You need to accept the terms and conditions before you can continue. Once that's done fill in the localization settings with the values that are relevant to you.

Next up is the database connection settings which should be filled in with the following information.

* Database Type: *MySQL*
* Host: *localhost*
* Database Name: *magento*
* User Name: *magento*
* Password: *magento*
* Tables Prefix: *Leave blank*

On the same page you will also need to specify the web access options.

* Base URL: *http://localhost.magento-store.com/*
* Admin Path: *admin*
* Select the *Use Web Server (Apache) Rewrites* option.

The next step is where you create the Admin user. Fill in the required details and choose to let the software generate an encryption key for you. Proceed to the next step and you will have finished installing Magento. 

At this point you can view your store at `http://localhost.magento-store.com`

<figure>
![Browser showing a new Magento store](/img/magento-store.png "Magento store.")
</figure>

To access the admin section of the store navigate to `http://localhost.magento-store.com/admin/` where you can login using the details set up during the installation.

<figure>
![Browser showing the Admin login page for a Magento store](/img/magento-store-admin.png "Magento store Admin login page.")
</figure>

##Conclusion.

Hopefully you had no trouble in following this very lengthy post. I welcome any thoughts or opinions via the comments below.