joanhe/product-community-edition

eCommerce Platform for Growth (Community Edition)

dev-master 2015-04-06 17:20 UTC

This package is not auto-updated.

Last update: 2024-12-17 09:20:16 UTC


README

Build Status

Welcome to Magento 2 installation! We're glad you chose to install Magento 2, a cutting edge, feature-rich eCommerce solution that gets results.

Contents

Magento 2 system requirements

Before you install Magento 2, make sure your system meets or exceeds the following requirements:

  • Operating systems

    Linux distributions such as RedHat Enterprise Linux (RHEL), CentOS, Ubuntu, Debian, and so on

  • Composer (latest stable version)

  • Apache 2.2 or later

  • PHP 5.4.11 or 5.5.x

  • Required PHP extensions:

    • PDO/MySQL
    • mbstring
    • mcrypt
    • mhash
    • simplexml
    • curl
    • gd2, ImageMagick 6.3.7 (or later) or both
    • soap
  • MySQL 5.6.x

  • Mail Transfer Agent (MTA) or an SMTP server

  • Optional but recommended:

    • php_xdebug2.2.0 or later (development environments only; can have an adverse effect on performance)
    • PHPUnit (as a command-line tool) 4.1 or later

Composer and Magento

We now use Composer to install the Magento 2 software. Composer enables us to manage Magento 2, extensions, and their dependencies.

Composer provides you with the following advantages:

  • Enables you to reuse third-party libraries without bundling them with source code
  • Component-based architecture with robust dependency management
  • Manages dependencies to reduce extension conflicts and compatibility issues
  • Versioned dependencies
  • Semantic versioning
  • Supports PHP Framework Interoperability standards

We'll have more information soon on how developers can use Composer to package extensions to distribute to Magento merchants and to other developers.

High-level installation roadmap

Following is a brief overview of how to install the Magento 2 software.

Step 1: Verify your prerequisites

Use the following table to verify you have the correct prerequisites to install the Magento 2 software.

Step 2: Prepare to install

After verifying your prerequisites, perform the following tasks in order to prepare to install the Magento 2 software.

  1. Installing Composer
  2. Cloning the Magento 2 GitHub repository

Step 3: Install and verify

  1. Installing or reinstalling the Magento software
  2. Verifying the installation

Required server permissions

Unless otherwise noted, all commands in this Readme must be entered as a user with root privileges and permission to write to the web server docroot. Depending on your system, that might mean you must use different user accounts or add users to the web server user group—provided that group has sufficient privileges.

Installing software on Linux typically requires root privileges. You should generally not install the Magento 2 software in the web server docroot using root privileges; however, that is up to you.

Prerequisites

This section discusses how to install software required to install Magento 2.

See one of the following sections:

Before you begin

Before you install Magento, you must do all of the following:

  • Set up one or more hosts that meet the Magento 2 system requirements.
  • Make sure you can back up your entire system at various points during the installation so you can roll back in the event of issues.

Apache

Installing Apache on Ubuntu

  1. Install Apache using the guidelines on the Ubuntu site.
  2. Enable server rewrites:
    • Apache 2.2: Use the guidelines on askubuntu.
    • Apache 2.4: Enter the following command: a2enmod rewrite
  3. Specify the type of directives that can be used in .htaccess. Magento uses .htaccess for redirects. For guidelines, see:
    • Apache 2.2: The Apache 2.2 documentation.
    • Apache 2.4: The Apache 2.4 documentation.
      Note that in Apache 2.4, the server's default site configuration file is /etc/apache2/sites-available/000-default.conf
      For example, you can add the following to the bottom of 000-default.conf:
      <Directory "/var/www">
      AllowOverride [value from Apache site]
      </Directory>
      Note: You must change the value of AllowOverride in the directive for the directory to which you expect to install the Magento software. For example, to install in the web server docroot, edit the directive in <Directory /var/www>.
  4. Restart Apache: service apache2 restart

Installing Apache on CentOS

  1. Install Apache:

    yum -y install httpd

    For additional information, see the Apache site.

  2. Enable server rewrites.

    Note: You must change the value of Allow Override in the directive for the directory to which you expect to install the Magento software. For example, to install in the web server docroot, edit the directive in <Directory "/var/www/html">.

  3. Set the type of directives that can be used in .htaccess. Magento uses .htaccess for redirects. Apache documentation.

  4. Restart Apache: service httpd restart

MySQL

Installing MySQL on Ubuntu

  1. Install MySQL on Ubuntu 12 or Ubuntu 14.
  2. Configure the database instance.

Installing and configuring MySQL on CentOS

The following procedure is based on Install MySQL Server 5.6 in CentOS 6.x and Red Hat 6.x Linux.

  1. Install the MySQL database:

    cd /tmp
    

wget http://repo.mysql.com/mysql-community-release-el6-5.noarch.rpm rpm -ivh mysql-community-release-el6-5.noarch.rpm yum -y install mysql-server

  1. Start MySQL.

    service mysqld start

  2. Set a password for the user and set other security-related options. Enter the following command and follow the prompts on your screen to complete the configuration.

    mysql_secure_installation

Configuring the Magento database instance

This section discusses how to create a new database instance for Magento. Although a new database instance is recommended, you can optionally install Magento into an existing database instance.

To configure a MySQL database instance:

  1. Log in to your database server as any user.

  2. Enter the following command to get to a MySQL command prompt:

    mysql -u root -p

  3. Enter the MySQL root user's password when prompted.

  4. Enter the following commands in the order shown to create a database instance named magento with user name magento:

    create database magento;
    

GRANT ALL ON magento.* TO magento@localhost IDENTIFIED BY 'magento';

  1. Enter exit to quit the command prompt.

PHP

Magento 2 requires PHP 5.4.11 or later or PHP 5.5.x.

Note: Magento 2 does not support PHP 5.6.

PHP 5.5 or 5.4 on Ubuntu

Install PHP 5.5 on Ubuntu 14

To install PHP 5.5 on Ubuntu 14:

  1. Enter the following command:

    apt-get -y install php5

  2. Verify the PHP version by entering php -v. Messages similar to the following should display:

    PHP 5.5.9-1ubuntu4.4 (cli) (built: Sep  4 2014 06:56:34)
    Copyright (c) 1997-2014 The PHP Group
    Zend Engine v2.5.0, Copyright (c) 1998-2014 Zend Technologies
    with Zend OPcache v7.0.3, Copyright (c) 1999-2014, by Zend Technologies
Install PHP 5.5 on Ubuntu 12
  1. Use the following commands from dev-metal:

    add-apt-repository ppa:ondrej/php5
    apt-get update
    sudo apt-get install php5
  2. Verify the PHP version by entering php -v. Messages similar to the following should display:

    PHP 5.5.18-1+deb.sury.org~precise+1 (cli) (built: Oct 17 2014 15:11:34)
    Copyright (c) 1997-2014 The PHP Group
    Zend Engine v2.5.0, Copyright (c) 1998-2014 Zend Technologies
    with Zend OPcache v7.0.4-dev, Copyright (c) 1999-2014, by Zend Technologies
Install PHP 5.4 on Ubuntu 12

To install PHP 5.4 on Ubuntu 12:

  1. Use the following instructions from askubuntu:

    add-apt-repository ppa:ondrej/php5-oldstable
    apt-get update
    apt-get upgrade
    apt-get install php5
  2. Verify the PHP version by entering php -v. Messages similar to the following should display:

    PHP 5.4.33-2+deb.sury.org~precise+1 (cli) (built: Sep 25 2014 09:06:25)
    Copyright (c) 1997-2014 The PHP Group
    Zend Engine v2.4.0, Copyright (c) 1998-2014 Zend Technologies
  3. Restart Apache: service apache2 restart

Upgrade to PHP 5.4 on Ubuntu

To upgrade to PHP 5.4 on Ubuntu:

  1. Use the instructions on phpave.

  2. After upgrading, verify the PHP version by entering php -v. Messages similar to the following should display:

    PHP 5.4.33-2+deb.sury.org~precise+1 (cli) (built: Sep 25 2014 09:06:25)
    Copyright (c) 1997-2014 The PHP Group
    Zend Engine v2.4.0, Copyright (c) 1998-2014 Zend Technologies
  3. Restart Apache: service apache2 restart

Install required PHP extensions on Ubuntu

Enter the following command to install required PHP extensions:

apt-get -y install php5 php5-mhash php5-mcrypt php5-curl php5-cli php5-mysql php5-gd

Ubuntu 14 only: workaround for mcrypt issue

There is a known issue in Ubuntu 14 with the mcrypt PHP extension. To work around the issue, see askubuntu.

PHP 5.5 or 5.4 on CentOS

PHP 5.3 is the default PHP version on CentOS distributions. Upgrade to PHP 5.4 using a repository like remi.

The following resources are also available:

To verify if PHP is installed already, enter php -v. If PHP is not installed, install it by entering the following command:

yum -y install php php-xml
PHP 5.5 on CentOS

To upgrade to PHP 5.5:

There is more than one way to upgrade CentOS 6.5 to PHP 5.5; the following is a suggestion only. Consult a reference for additional options.

Enter the following commands in the order shown.

cd /tmp
rpm -Uvh https://mirror.webtatic.com/yum/el6/latest.rpm
yum -y remove php-common-5.3.3-40.el6_6.x86_64
yum -y install php55w php55w-opcache

Restart Apache: service httpd restart

PHP 5.4 on CentOS

To upgrade to PHP 5.4:

  1. Enter the following commands:

    cd /tmp
    rpm -Uvh http://download.fedoraproject.org/pub/epel/6/i386/epel-release-6-8.noarch.rpm
    rpm -Uvh http://rpms.famillecollet.com/enterprise/remi-release-6.rpm
    yum -y --enablerepo=remi install httpd php php-common
  2. To verify PHP 5.4 is installed, enter php -v. The command displays results similar to the following:

    PHP 5.4.33 (cli) (built: Sep 20 2014 16:20:03)
    Copyright (c) 1997-2014 The PHP Group
    Zend Engine v2.4.0, Copyright (c) 1998-2014 Zend Technologies
  3. Restart Apache: service httpd restart

Install required PHP extensions on CentOS

Enter the following command to install required PHP extensions:

yum -y --enablerepo=remi install php-xml php-mcrypt.x86_64 gd gd-devel php-gd php-mysql

Setting the PHP timezone (all operating systems)

Before you install Magento, you might need to set the system time zone for PHP; otherwise, errors like the following display during the installation and time-related operations like cron might not work:

PHP Warning: date(): It is not safe to rely on the system's timezone settings. [more messages follow]

To set your time zone:

  1. Locate your server's time zone in the available time zone settings.

  2. Locate php.ini by entering the following command:

    php -i | grep "Loaded Configuration File"

    Typical locations follow:

    Ubuntu: /etc/php5/cli/php.ini

    CentOS: /etc/php.ini

  3. Open php.ini in a text editor.

  4. Locate the following setting and uncomment it if necessary:

    date.timezone =

  5. Add the time zone setting you found in step 1.

  6. Save your changes to php.ini and exit the text editor.

Setting the PHP memory limit (all operating systems)

Increase memory_limit in php.ini to at least 512MB for normal operation or 2GB for testing:

  1. Open one of the following in a text editor:

    • Ubuntu: /etc/php5/apache2/php.ini
    • CentOS: /etc/php.ini
  2. Change memory_limit to:

    memory_limit = 512M or more for normal operation

    memory_limit = 2G or more for testing

  3. Save your changes and exit the text editor.

  4. Restart Apache:

    Ubuntu: service apache2 restart

    CentOS: service httpd restart

Installing Composer

To install Composer:

  1. Change to or create an empty directory on your Magento server.

  2. Enter the following commands:

    curl -sS https://getcomposer.org/installer | php
    mv composer.phar /usr/local/bin/composer

    For additional installation options, see the Composer installation documentation.

Cloning the Magento 2 GitHub repository

To clone the Magento 2 GitHub repository:

  1. Change to your web server's docroot directory.

    Typically, for Ubuntu, it's /var/www and for CentOS it's /var/www/html.

  2. Enter any of the following commands as a user with privileges to write to the web server docroot:

    To clone using HTTPS, use either of the following:

    git clone https://github.com/magento/magento2.git

    git clone https://[your github.com user name]:[password]@github.com/magento/magento2.git

    To clone using SSH: git clone git@github.com:magento/magento2.git

  3. Wait for the repository to clone on your server.

Note: If you get an error that includes Permission denied (publickey), see Troubleshooting.

Installing or reinstalling the Magento 2 software

Before you begin, make sure that:

  1. Your system meets the requirements discussed in Magento 2 system requirements.
  2. You completed all prerequisite tasks discussed in Prerequisites.
  3. You installed Composer.
  4. You cloned the Magento 2 GitHub repository.

Setting file system permissions and ownership before you install

To make sure the installation completes successfully, we suggest the following file system permissions and ownership:

  • All files and directories owned by the web server user
  • Certain directories must be writable

Finding the web server user

To find the web server user, enter one of the following commands:

  • Ubuntu: ps -ef | grep apache2
  • CentOS: grep User /etc/httpd/conf/httpd.conf

Pre-installation permissions and ownership

Before the installation, set the following permissions:

  • All directories have 700 permissions (drwx------).

    700 permissions give full control (that is, read/write/execute) to the owner and no permissions to anyone else.

  • All files have 600 permissions (-rw-------).

    600 permissions mean the owner can read and write but other users have no permissions.

Setting permissions and ownership

  1. To set ownership, enter the following commands as a user with root privileges:

    cd [your Magento installation directory]
    chown -R [web server user name] .

    CentOS example:

    cd /var/www/html/magento2
    chown -R apache .

    Ubuntu example:

    cd /var/www/magento2
    chown -R www-data .
  2. Set file and directory permissions:

    find . -type d -exec chmod 700 {} \;
    find . -type f -exec chmod 600 {} \;

Getting started with your installation

After you complete the tasks discussed in the preceding section, update Composer and run the installer:

  1. Log in to your Magento server as a user with root privileges.

  2. Change to the Magento 2 installation directory. For example,

    cd /var/www/html/magento2

    Note: On Ubuntu, you might have to use the sudo -s or equivalent command to access this directory.

  3. As user with privileges to write to the web server docroot, enter composer install

    This command updates package dependencies and can take a few minutes to complete.

  4. Change to the Magento 2 setup subdirectory and enter composer install.

Note: You must run composer install from both directories.

Running the Magento 2 installer

This section discusses how to run the command-line installer for Magento 2.

Note: You must install Magento from its setup subdirectory.

The installer is designed to be run multiple times if necessary so you can:

  • Provide different values

    For example, after you configure your web server for Secure Sockets Layer (SSL), you can run the installer to set SSL options.

  • Correct mistakes in previous installations

  • Install Magento in a different database instance

Note: By default, the installer doesn't overwrite the Magento database if you install the Magento software in the same database instance. You can use the optional parameter to change this behavior.

Note: If you get errors during the installation, see Troubleshooting.

Before you begin, you can run the following commands to find values for some required options:

<p>The format of the command follows:</p>

<code>php -f index.php install [--[installation option name]=[installation option value] ...</code>

<p>The following table discusses the meanings of installation option names and values. An example is provided in <a href="#sample-localhost-installation">Sample localhost installation</a>.</p>
	<td>admin_firstname</td>
	<td>Magento administrator user's first name.</td>
	<td>Yes</td>
</tr>
<tr>
	<td>admin_lastname</td>
	<td>Magento administrator user's last name.</td>
	<td>Yes</td>
</tr>
<tr>
	<td>admin_email</td>
	<td>Magento administrator user's e-mail address.</td>
	<td>Yes</td>
</tr>
<tr>
	<td>admin_username</td>
	<td>Magento administrator user name.</td>
	<td>Yes</td>
</tr>
<tr>
	<td>admin_password</td>
	<td>Magento administrator user password.</td>
	<td>Yes</td>
</tr>
<tr>
	<td>language</td>
	<td>Language code to use in the Admin and storefront. (If you have not done so already, you can view the list of language codes by entering <code>php -f index.php help languages</code> from the <code>setup</code> directory.)</td>
	<td>Yes</td>
</tr>
<tr>
	<td>currency</td>
	<td>Default currency to use in the storefront. (If you have not done so already, you can view the list of currencies by entering <code>php -f index.php help currencies</code> from the <code>setup</code> directory.)</td>
	<td>Yes</td>
</tr>
<tr>
	<td>timezone</td>
	<td>Default time zone to use in the Admin and storefront. (If you have not done so already, you can view the list of time zones by entering <code>php -f index.php help timezones</code> from the <code>setup</code> directory.)</td>
	<td>Yes</td>
</tr>
<tr>
	<td>use_secure</td>
	<td><p><code>1</code> enables the use of Secure Sockets Layer (SSL) in all URLs (both Admin and storefront). Make sure your web server supports SSL before you select this option.</p>
	<p><code>0</code> disables the use of SSL with Magento. In this case, all other secure URL options are assumed to also be <code>0</code>.</p></td>
	<td>No</td>
</tr>
<tr>
	<td>base_secure_url</td>
	<td><p><code>1</code> means SSL is preferred in Magento URLs designed to use it (for example, the checkout page). Make sure your web server supports SSL before you select this option.</p>
	<p><code>0</code> means SSL is not used.</p></td>
	<td>No</td>
</tr>

<tr>
	<td>use_secure_admin</td>
	<td><p><code>1</code> means you use SSL to access the Magento Admin. Make sure your web server supports SSL before you select this option.</p>
	<p><code>0</code> means you do not use SSL with the Admin.</p></td>
	<td>No</td>
</tr>
<tr>
	<td>admin_use_security_key</td>
	<td><p><code>1</code> causes the Magento software to use a randomly generated key value to access pages in the Magento Admin and in forms. These key values help prevent <a href="https://www.owasp.org/index.php/Cross-Site_Request_Forgery_%28CSRF%29" target="_blank">cross-site script forgery attacks</a>.</p>
	<p><code>0</code> disables the use of the key.</p></td>
	<td>No</td>
</tr>
<tr>
	<td>session_save</td>
	<td><p>Use any of the following:</p>
	<ul><li><code>files</code> to store session data in the file system. File-based session storage is appropriate unless the Magento file system access is slow or you have a clustered database.</li>
	<li><code>db.files</code> to store session data in the database. Choose database storage if you have a clustered database; otherwise, there might not be much benefit over file-based storage.</li></ul></td>
	<td>No</td>
</tr>
<tr>
	<td>key</td>
	<td>If you have one, specify a key to encrypt sensitive data in the Magento database. (This includes passwords and personally identifiable customer information.) If you don't have one, Magento generates one for you.</td>
	<td>No</td>
</tr>
<tr>
	<td>cleanup_database</td>
	<td>To drop database tables before installing the Magento 2 software, specify this parameter without a value. Otherwise, the Magento database is left intact.</td>
	<td>No</td>
</tr>
<tr>
	<td>db_init_statements</td>
	<td>Advanced MySQL configuration parameter. Uses database initialization statements to run when connecting to the MySQL database. Consult a reference similar to <a href="http://dev.mysql.com/doc/refman/5.6/en/server-options.html" target="_blank">this one</a> before you set any values.</td>
	<td>No</td>
</tr>
<tr>
	<td>sales_order_increment_prefix</td>
	<td>Specify a string value to use as a prefix for sales orders. Typically, this is used to guarantee unique order numbers for payment processors.</td>
	<td>No</td>
</tr>

</tbody>

Sample localhost installation

The following example installs Magento with the following options:

  • The Magento software is installed in the magento2 directory relative to the web server docroot on localhost and the path to the Magento Admin is admin; therefore:

    Your storefront URL is http://localhost and you can access the Magento Admin at http://localhost/admin

  • The database server is on the same host as the web server.

    The database name is magento, and the user name and password are both magento

  • The Magento administrator has the following properties:

    • First and last name are is Magento User
    • User name is admin and the password is iamtheadmin
    • E-mail address is user@example.com
  • Default language is en_US (U.S. English)

  • Default currency is U.S. dollars

  • Default time zone is U.S. Central (America/Chicago)

php -f index.php install --base_url=http://localhost/magento2/
	--backend_frontname=admin 
	--db_host=localhost --db_name=magento 
	--db_user=magento --db_pass=magento 
	--admin_firstname=Magento --admin_lastname=User 
	--admin_email=user@example.com 	--admin_username=admin 
	--admin_password=iamtheadmin --language=en_US
	--currency=USD --timezone=America/Chicago

Reinstalling the Magento 2 software

This section discusses how to install the Magento 2 software after you installed it previously. You might do this in an development environment especially to get all the latest code changes.

To reinstall the Magento 2 software:

  1. Optionally delete and re-create the database instance.

  2. Log in to your Magento server as a user with permissions to modify files in the Magento file system.

  3. Enter the following commands in the order shown:

    cd [your Magento install dir]
    

git pull composer install cd setup composer install

  1. Repeat the tasks discussed in Installing or reinstalling the Magento 2 software.

Verifying the installation

Verifying the storefront

Go to the storefront in a web browser. For example, if your Magento 2 installation base URL is http://www.example.com, enter it in your browser's address or location bar.

The following figure shows a sample storefront page. If it displays as follows, your installation was a success!

Magento storefront which verifies a successful installation

If the page appears unconfigured (no styles, only text), see Troubleshooting.

Verifying the Magento Admin

Go to the Magento Admin in a web browser. For example, if your Magento 2 installation base URL is http://www.example.com, and the Admin URL is admin, enter http://www.example.com/admin in your browser's address or location bar.

(The Admin URL is specified by the value of the backend_frontname installation parameter.)

When prompted, log in as a Magento Administrator.

The following figure shows a sample Magento Admin page. If it displays as follows, your installation was a success!

Magento Admin which verifies a successful installation

If the page appears unconfigured (no styles, only text), see Troubleshooting.

If you get a 404 (Not Found) error similar to the following, see Troubleshooting:

The requested URL /magento2index.php/admin/admin/dashboard/index/key/0c81957145a968b697c32a846598dc2e/ was not found on this server.

Troubleshooting

Problem: Cannot clone the Magento 2 GitHub repository

Detail: Error is similar to the following:

Cloning into 'magento2'...
Permission denied (publickey).
fatal: The remote end hung up unexpectedly

Solution: Upload your SSH key to GitHub as discussed in the GitHub help page.

Problem: Cannot run 'composer install'

Suggestion: Change to the directory in which you installed Composer and enter the following command:

mv composer.phar /usr/local/bin/composer

Problem: During installation, PHP date warning

Details: During the installation, the following message displays:

PHP Warning: date(): It is not safe to rely on the system's timezone settings. [more]

Solution: Set the PHP timezone properly.

Problem: During installation, the following fatal error displays:

PHP Fatal error: Class 'PDO' not found in /var/www/html/magento2/setup/module/Magento/Setup/src/Module/Setup/ConnectionFactory.php on line 44

Solution: Make sure you installed all required PHP extensions.

Problem: You cannot access Magento in a web browser

Details: The following message displays when you try to access the Magento storefront or Admin:

Whoops, it looks like you have an invalid PHP version.
Magento supports PHP 5.4.11 or newer. 

Solution: Either upgrade PHP or restart Apache (Apache might not be using the same PHP version as is on the file system).

To restart Apache:

  • Ubuntu: service apache2 restart
  • CentOS: service httpd restart

Problem: Error after logging in to the Magento Admin:

The requested URL /magento2index.php/admin/admin/dashboard/index/key/0c81957145a968b697c32a846598dc2e/ was not found on this server.

Note the lack of a slash character between and in the URL.

Solution: The base URL is not correct. The base URL must start with or and it must end with a slash (/). Run the installation again with a valid value.

Problem: After installing, images and stylesheets do not load; only text displays, no graphics.

Details: The path to images and stylesheets is not correct, either because of an incorrect base URL or because server rewrites are not set up properly. To confirm this is the case, use a web browser inspector to check the paths to static assets and verify those assets are located on the Magento file system.

Magento 2 static assets should be located under [your Magento install dir]/pub/static/ (there should be frontend and adminhtml directories).

Verify your server rewrites setting and your base URL and try again.