Chapter 2: Getting Started with Magento

Last modified by SisterTwisted on Thu, December 25, 2008 12:41
Source|Old Revisions  
The Magento Wiki is managed by a community of contributors, not by the Magento team. The community, which includes some Magento employees, does frequently add new content to the Wiki. While most content is current and accurate, Magento cannot guarantee the accuracy of every article.

This is an old revision of the document!


Magento is developed to take full advantage of the newest technologies available, allowing your site the maximum flexibility without sacrificing speed. In this chapter we will look at the system requirements of Magento, how to download and install Magento on your server, and go through an introduction to the administration panel and key concepts when using the administration panel.

System Requirements

At the base level, Magento will require the following software.

  • Linux, Windows, or another UNIX-compatible operating system
  • Apache Web Server (1.x or 2.x)
  • PHP 5.2.0 or newer, with the following extensions/addons:
    • PDO/MySQL
    • MySQLi
    • mcrypt
    • mhash
    • simplexml
    • DOM
    • curl
    • gd
    • soap
  • MySQL 4.1.20 or newer
  • A Sendmail-compatible Mail Transfer Agent (MTA)
    • Magento will connect directly to an SMTP server if you don’t have an MTA

We also recommend the use of APC as a bytecode cache for performance improvements. You can find it in the PECL archives here: http://pecl.php.net/package/APC. Other bytecode cache systems are not supported at this time.

If you are unsure if your hosting company supports these specifications, please check with them. You can also view these specifications at: magentocommerce.com/system-requirements. Once you have a hosting environment set up with support for these requirements you are able to download and install Magento to your server.

Downloading Magento

Magento is free to download. Simply go to magentocommerce.com/download and you will be able to download the software. Magento is available for download in two different versions. The installer version includes only the necessary files needed to begin the installation process and will be all that is necessary for most cases. If you are planning on installing multiple versions of Magento the full version will be more useful, as you will then only need to download the full version once, and will then be able to download the installer version for each new version. To keep it simple, if you are confused about which version to download, use the installer version.

Both versions are available in multiple formats to suit different needs. If you are unsure of which version to download use the .zip format.

Note: If you are a developer and are familiar with SVN you can also checkout the newest version of Magento using SVN. To view the most up to date command please visit magentocommerce.com/svn.

If you have successfully downloaded Magento you are now ready to install the software on your web server.

Installing and Configuring Magento

Downloader Install

This section covers the installer installation process for Magento. If you have downloaded the installer package from magentocommerce.com, then follow this guide to complete the installation.

Installation

1. Download the .zip or .tar.gz installer package from the Magento website and decompress it.

2. Upload all the decompressed files to your web server via FTP

3. Create a MySQL database and user/password for Magento

  • This step varies by hosting provider and is out of the scope of this document. Consult your provider’s support/documentation for instructions on how to do this.

4. The top-level Magento directory (the one you uploaded the decompressed files to) must have the correct permissions in order for the installer to proceed. To do so, navigate to the directory with your FTP client. Then locate the function “Change Permissions” or “Change Mode” in your FTP client and select it. Once you find the function, you must set the permissions so the web server can write to this file. There are two typical ways of representing file permissions in Linux:

  • As a number (eg, 755)
  • As a series of permissions categorized into user, group, and other

If your FTP client uses the first representation, set the permissions on the directory to be 777, or 0777. If your FTP client uses the second representation, set the permissions as shown in the image below.

777_file_permissions.jpg

5. If your server primarily runs PHP4 then you will require the PHP5 CGI Binary in order to continue. Please read the PHP5 CGI Setup appendix below and complete it before continuing to Step 6.

6. Now use your web browser to surf to the Magento installation wizard. If you’ve uploaded the Magento files to http://www.example.com/magento/, then the wizard will be located here: http://www.example.com/magento/.

7. Since you are using the installer version, the downloader will be the first installation process to run. It will attempt to download all the necessary components for a complete Magento install. If you notice a few “Warning” messages zip by on the green-on-black screen, don’t worry too much about it. The installer will detect an overall success or failure, and if you see the “Continue Magento Installation” button at the end (usually takes about 5 minutes) then the process has succeeded. Click the “Continue Magento Installation” button to continue on to the regular installer wizard.

8. Once in the wizard, you can configure various system-level settings that are required for Magento to function. Most options will be intelligently guessed for you, but you’re free to override any settings that don’t look right. At the very least, change the database parameters in the first box, “Database connection”, to match those of the database you set up in Step 3.

9. Success! You’ve completed a Magento installation. You can now visit the administration backend and begin configuring your new online store.

Default Install

This section covers the default installation process for Magento. If you have downloaded one of the standard release distributions from magentocommerce.com, follow this guide to complete the installation.

Installation

1. Download the .zip or .tar.gz file from the Magento website and decompress it.

2. Upload the Magento web files to your web server via FTP

3. Create a MySQL database and user/password for Magento

  • This step varies by hosting provider and is out of the scope of this document. Consult your provider’s support/documentation for instructions on how to do this.

4. Ensure that the directories app/etc , var , and media are writable by the web server. To do so, navigate to the directory with your FTP client. Then locate the function “Change Permissions” or “Change Mode” in your FTP client and select it. Once you find the function, you must set the permissions so the web server can write to this file. There are two typical ways of representing file permissions in Linux:

  • As a number (eg, 755)
  • As a series of permissions categorized into user, group, and other

If your FTP client uses the first representation, set the permissions on each directory to be 777, or 0777. If your FTP client uses the second representation, set the permissions as shown in the image below.

777_file_permissions.jpg

5. If your server primarily runs PHP4 then you will require the PHP5 CGI Binary in order to continue. Please read the PHP5 CGI Setup appendix below and complete it before continuing to Step 6.

6. Now use your web browser to surf to the Magento installation wizard. If you’ve uploaded the Magento files to http://www.example.com/magento/, then the wizard will be located here: http://www.example.com/magento/.

7. Once in the wizard, you can configure various system-level settings that are required for Magento to function. Most options will be intelligently guessed for you, but you’re free to override any settings that don’t look right. At the very least, change the database parameters in the first box, “Database connection”, to match those of the database you set up in Step 3.

8. Success! You’ve completed a Magento installation. You can now visit the administration backend and begin configuring your new online store.

Appendix: PHP5 CGI Setup

Introduction

Some hosting providers do not yet provide PHP5 on their servers, opting instead to stay with PHP4 for the time being. As Magento is a PHP5-only application, this can be a barrier for some users. This document outlines a possible workaround for such a scenario. The goal is to install PHP5 as a CGI binary and configure the web server (Apache) to use it instead of the default PHP4.

Requirements

Every hosting provider has a slightly different way of doing things, so it’s important to know if this method will work with your provider before continuing. Below is a list of the basic requirements that this document requires. If you’re unsure as to whether your provider supports these requirements, pass the list along to them and find out.

  • Operating System: Linux
  • Web Server: Apache with CGI support
  • FileInfo override control via .htaccess files
  • A user-writable cgi-bin directory
  • FTP access to your web root and cgi-bin directories

Step 1: Upload the PHP5 CGI binary

It is possible to compile a PHP5 binary yourself, but for the purposes of this solution, we’ve provided one for you. You can download it here: http://www.magentocommerce.com/support/php5cgi/php5-cgi

Once downloaded, use your FTP client to upload the file to your cgi-bin directory. If you don’t know where your cgi-bin directory is, ask your hosting provider.

After uploading, use your FTP client to set the proper mode on the php5-cgi file. This function varies for each FTP client, but it usually called “Change Permissions” or “Change Mode” or “Chmod”. Once you find the function, you must set the permissions so the web server can run this file. There are two typical ways of representing file permissions in Linux:

  1. As a number (eg, 755)
  2. As a series of permissions categorized into user, group, and other

If your FTP client uses the first representation, set the permission on the php5-cgi binary to be 755, or 0755. If your FTP client uses the second representation, set the permissions as shown in the image below.

755_file_permissions.jpg

Step 2: Modify the Magento .htaccess file

By default, the web server will want to run the Magento application using PHP4, which will not work. In order to point it to the new PHP5 CGI binary, you must modify the .htaccess file in the Magento top-level directory.

Using your FTP client, edit the file .htaccess in your top-level Magento directory.

The file is somewhat long so we won’t list it all here. But the first few lines at the top should look like this:

cgi_htaccess_file.jpg

First, remove the # symbol from the beginning of the last three lines listed in the excerpt above. This will enable the special CGI handler for your Magento site. Next, you’ll want to modify the path in the Action line to point to the location of the php5-cgi binary you uploaded in Step 1. This path should be relative to the web root of your site.

That’s it! You can now proceed with the rest of the Magento installation.

Troubleshooting

I still see “Invalid PHP version” when visiting my Magento page.

This probably means that your hosting provider does not allow the FileInfo overrides via .htaccess files. This is a necessary requirement for this solution, so you’ll have to ask your hosting provider for it.

I see “Internal Server Error” when visiting my Magento page.

This is a typical error message when a CGI binary quits unexpectedly, and could be caused by a number of things. If you have access to your server’s Apache error log, you can look there for some clues. We’ll cover a few more common issues here.

  1. Bad location to the PHP5 binary. Make sure the AddHandler directive in your .htaccess file is pointing to the correct location for the PHP5 binary. You can often test it by trying to surf to the location with your web browser. For example, if your site is www.example.com and your PHP5 location is /cgi-bin/php5-cgi , try visiting http://www.example.com/cgi-bin/php5-cgi with your web browser. If you see an “Internal Server Error” message, then that means your PHP5 binary is in the correct location. If you get a “File not found” message, then this is not the correct location.
  2. Bad permissions on the PHP5 binary. Double check the permissions on the PHP5 CGI binary you uploaded in Step 1. They should be 755 or “rwxr-xr-x”, depending on your FTP client’s representation.

Configuration during Installation

Once you select your option you will see the files downloaded. The time required to download the files will depend on your connection speed. Once the files have downloaded a success message will be displayed. Select OK and you will be taken to the next step of the installation where you will set the default configuration settings for your store.

The first settings you will need to enter will be your Database Connection settings. Your host will likely be your domain name, the database name, user name and user password will be the values you created when creating the database.

Troubleshooting Installation

If you have difficulty with installation you can receive help at the www.magentocommerce.com site in the forums.

Introduction to the Administrative Panel

Once you have completed the installation you will be taken to the frontend of your site. To access the administration panel you will add /admin to the end of the base URL you specified during the installation. E.G. if you specified example.com as the base URL, just go to http://www.example.com/admin. Once you are at the login section you will need to sign in using the user name and password you created during the installation process. Select the Login button and you are now in the administration panel.

The following sections detail some of the most important features which you will want to address in the initial configuration of your admin. Other features, such as adding products, payment methods, and shipping settings, will be addressed in following chapters.

Creating Multiple Websites and Stores

If you are interested in creating a multiple Website, Store, and/or Store View setup you can do so by navigating to System > Manage Stores.

Website

To create a new Website, click Create Website in the upper right corner.

Websites will each need to have a unique Code. This code can be a text name, but cannot have spaces or special characters within it.

If your Website name is New Website, a good rule of thumb would be to use “new” or “newwebsite” as your website code.

You can designate the Sort order of the Website as it will appear relative to your other Website(s) throughout the admin.

If you have not indicated which Website will be displayed when the index.php path is requested by the browser, your customers will automatically be directed to the default Website, which you select by checking the Set as default checkbox.

Store

To create a new Store, click Create Store in the upper right corner.

Select the Website to which this Store will be associated.

Select the Root Category which will be associated to this store. In your categories setup, you can create multiple Root Categories, each associated to different Stores. The sub-categories and products associated to those categories will only display in the Store to which the Root Category is associated. If you do not want to create different Root Categories to display in different Stores, you can select the same Root Category for all Stores. Categories are discussed in more detail in the next chapter.

Store View

As explained in Chapter 1, Store Views are best used to display a Store in multiple languages.

To create a new Store View, click Create Store View in the upper right corner.

Select the Store to which this Store View will be associated. The Code and Sort order fields work like those for Websites.

For a Store View to be visible on the front-end, it must be Enabled. You can remove it from the front-end without deleting it by selecting Disabled.

You can set unique Locales for each Store View. Simply navigate to System > Configuration, and select the General tab from the left column. In the Current Configuration Scope drop-down above, select the desired Store View. Uncheck the Use website checkbox next the Locale settings, and select the Locale you prefer. This Locale will only apply to this Store View.

Permissions

Magento’s Permissions module is both flexible and intuitive. You can create predefined Roles, which have specific access to various parts of the admin. Then, you can create users and select which Role each user will possess. You can associate Users to Roles in both the Users page and the Roles page.

Creating Roles

To create a Role, navigate to System > Permissions > Roles and click Add New Role.

Role Info

Enter the Role Name.

Role Resources

Choose the Resources, or admin features, to which Users associated to this Role will have access. If you select all from the Resource Access drop-down, this Role will have access to all resources. If you select Custom, a resource tree will populate, and you will have to select the checkbox for each resource to which this Role will have access.

Click Save Role.

Role Users

Once a Role has been saved, this tab will appear. It will display all Users that are associated to this Role. To see a list of all Users, click Reset Filter. Click the checkbox of all Users you want to associate to this Role, and click Save Role again.

Assigning Users

To create a User, navigate to System > Permissions > Users and click Add New User.

User Info

Enter all the information for this User. The User Name and Password will be used by this User to log into the Magento admin panel. For a User to be able to access the admin panel, the User must be Active. You can prevent a User from accessing the admin panel without deleting their User account by changing this to Inactive.

User Role

Select the Role to which this User will be associated. This page will produce a list of all existing Roles, and you will only be allowed to choose one.

Click Save User.

Cache Management

Cache management can be accessed by navigating to System > Cache management. It can be enabled to improve the performance of Magento. When developing on Magento it is best to disable the cache management. You can enable caching on the entire site, or enable cache management on certain elements of the site by using the various checkboxes in this page.




 

Magento 2 GitHub Repository

Magento Job Board - Some sort of tag line goes here

Latest Posts| View all Jobs