How to Install and run OpenCart on NGINX server
Nginx has recently become a very popular web server due to its extremely fast response and ability to handle thousands of simultaneous requests, while using minimal system resources. According to W3Tech, which is one of the most reliable and extensive information source on web technology usage, Nginx is used by 34% of the sites with heaviest traffic in the world.
In this blogpost we will try to give you a heads up on how to configure Nginx for OpenCart.
Prerequisites
Server platform:
The operating system that we are going to use for the server, in this example, is FreeBSD 9.1 (free Unix-like operating system). You can also use any of the other supported operating systems (GNU/Linux, Unix, BSD, Mac OS X, Solaris and Windows, etc.) . We will manage our server remotely over SSH (secure shell).
FastCGI Process Manager:
For the installation of OpenCart we would need an Nginx server with PHP and MySQL installed on it. What is different here is that we need to have the PHP-FPM (FastCGI Process Manager) built, which is an alternative of the PHP FastCGI version, typically used on Apache server.
PHP extensions:
Once we have built the PHP-FPM, we need to add several php-extensions which are of great importance so that our OpenCart installation will proceed flawlessly. The extensions that we need are:
- php*-mysql
- php*-gd
- php*-curl
- php*-mcrypt
- php*-zlib
* where the asterisk(*) should be changed with the version of PHP you have installed
You can add these extensions using the package manager of your server operating system. In our case we use the following commands:
root@nginx:/ #pkg_add -r php55-mysql root@nginx:/ #pkg_add -r php55-gd root@nginx:/ #pkg_add -r php55-curl root@nginx:/ #pkg_add -r php55-mcrypt root@nginx:/ #pkg_add -r php55-zlib
OpenCart Installation
We will start with downloading the OpenCart platform from the OpenCart website. In our case we will download it through the secure shell.
The latest available for download version of OpenCart is 1.5.6.1. The download link, which we take from the OpenCart website is: http://www.opencart.com/index.php?route=download/download/download&download_id=33
In the secure shell we should type the following command to download OpenCart:
root@nginx:/#fetch “http://www.opencart.com/index.php?route=download/download/download&download_id=33”
After that we need to extract the downloaded archive:
root@nginx:/# tar -zxf “./download&download_id=33”
Now, we will create a new directory on the server, where we are going to install our OpenCart.
root@nginx:/ # mkdir /usr/local/www/nginx/opencart
After we have created the directory for our installation, we have to copy all files and folders from the extracted OpenCart upload directory to the Nginx web directory:
root@nginx:/ # cp -r ./opencart-1.5.6.1/upload/* /usr/local/www/nginx/opencart
Following, we should rename the OpenCart config-dist.php and admin/config-dist.php files to config.php otherwise the installation will not run properly.
root@nginx:/ # mv /usr/local/www/nginx/opencart/config-dist.php /usr/local/www/nginx/opencart/config.php root@nginx:/ # mv /usr/local/www/nginx/opencart/admin/config-dist.php /usr/local/www/nginx/opencart/admin/config.php
Please mind that in order for the installation to proceed successfully you should configure the file permissions according to the OpenCart installation requirements.
Next stop, we should configure Nginx to have access to our installation directory. For that purpose we will create a new configuration file, separated from the default nginx.conf file.
The new file is opencart.conf and it should be located in /usr/local/etc/nginx/sites/.
root@nginx:/ # mkdir /usr/local/etc/nginx/sites/ root@nginx:/ # touch /usr/local/etc/nginx/sites/opencart.conf
After we have created the opencart.conf file we should add the necessary OpenCart server settings.
First, we open the file for edit:
root@nginx:/ # edit /usr/local/etc/nginx/sites/opencart.conf
Then add the necessary settings:
# /usr/local/etc/nginx/sites/opencart.conf
server {
listen 80;
#here we set the domain name that we use for this installation
server_name opencart.yourdomain.com;
access_log /var/log/www/opencart.access-log;
root /usr/local/www/nginx/opencart/;
index index.php index.html index.htm;
location ~ \.php$ {
fastcgi_pass 127.0.0.1:9000;
fastcgi_index index.php;
fastcgi_param SCRIPT_FILENAME /usr/local/www/nginx/opencart$fastcgi_script_name;
include fastcgi_params;
}
}
Note: The server_name value (opencart.yourdomain.com) should be changed to your IP address or domain name of your OpenCart installation.
Now we will configure our main .conf file which is nginx.conf. This file contains the main server settings and we will include in it all other .conf files from /usr/local/etc/nginx/sites/.
We need to open the file for edit:
root@nginx:/ # edit /usr/local/etc/nginx/nginx.conf
Next, we add the server_name value and the function which will include all .conf files into the nginx.conf file. This is how our nginx.conf file looks like after the changes:
# /usr/local/etc/nginx/nginx.conf
user www;
worker_processes 1;
error_log /var/log/nginx-error.log;
events {
worker_connections 1024;
}
http {
include mime.types;
default_type application/octet-stream;
access_log /var/log/nginx-http.log;
sendfile on;
keepalive_timeout 65;
server {
listen 80;
#here we set the domain name for the server web root directory
server_name yourdomain.com;
access_log /var/log/nginx-access.log;
location / {
root /usr/local/www/nginx;
index index.html index.htm index.php;
}
error_page 404 /404.html;
error_page 500 502 503 504 /50x.html;
location = /50x.html {
root /usr/local/www/nginx-dist;
}
location ~ \.php$ {
root html;
fastcgi_pass 127.0.0.1:9000;
fastcgi_index index.php;
fastcgi_param SCRIPT_FILENAME /scripts$fastcgi_script_name;
include fastcgi_params;
}
location ~ /\.ht {
deny all;
}
}
# virtual hosting
#here we include the rules from all .conf files located in /usr/local/etc/nginx/sites/
include /usr/local/etc/nginx/sites/*.conf;
}
Please have in mind that it is a good practice to first backup the files that you change in case something go wrong.
So far we are ready with the basic configuration. From here on the installation process continues with typical OpenCart installation through the web browser. In our example the store should be available on
http://opencart.yourdomain.com
Common problems
-
MySQL server strict mode
In our example the installation of MySQL server comes with enabled strict mode which controls the way MySQL handles invalid or missing values in data-change statements such as INSERT or UPDATE. This setting of MySQL server causes an error during the installation:
Fatal error: Uncaught exception 'ErrorException' with message 'Error: Field 'image' doesn't have a default value<br />Error No: 1364………………………
The problem comes from the fact that some of the INSERT queries in the opencart.sql don’t have default values.
If this error occurs during the installation, you have to go back and make some changes.
1. First, you should drop the created tables in the OpenCart database.
2. After that, you have two ways to resolve the problem
- The first one is to edit the opencart.sql file, located in the /install directory, and manually add default values for the empty fields.
- The second solution, which we are going to use in our example, is to disable the MySQL strict mode. Here is how to do this:
First we have to access the MySQL command line
root@nginx:/ # mysql -u root -p
Then we disable the strict mode with the following query:
mysql> set global sql_mode = 'NO_ENGINE_SUBSTITUTION';
This should do the job. Once you fix this problem you can run the installation again.
-
SEO URLs
If you intend to use SEO URLs you will have to make some modifications in the opencart.conf file. These modifications are needed because Nginx does not support .htaccess files and it is not able to run the default rewrite rules of OpenCart.
In order to resolve this problem we will add the rewrite rules in the /usr/local/etc/nginx/sites/opencart.conf file.
First we open the file for edit:
root@nginx:/ # edit /usr/local/etc/nginx/sites/opencart.conf
Then we add the rewrite rules. After the changes our opencart.conf file should look like this:
# /usr/local/etc/nginx/sites/opencart.conf
server {
listen 80;
#here we set the domain name that we use for this installation
server_name opencart.yourdomain.com;
access_log /var/log/www/opencart.access-log;
root /usr/local/www/nginx/opencart/;
index index.php index.html index.htm;
# START Rewrite rules
rewrite ^/sitemap.xml$ /index.php?route=feed/google_sitemap last;
rewrite ^/googlebase.xml$ /index.php?route=feed/google_base last;
rewrite ^/download/(.*) /index.php?route=error/not_found last;
if (!-f $request_filename) {
set $rule_3 1$rule_3;
}
if (!-d $request_filename) {
set $rule_3 2$rule_3;
}
if ($uri !~ ".*.(ico|gif|jpg|jpeg|png|js|css)") {
set $rule_3 3$rule_3;
}
if ($rule_3 = "321") {
rewrite ^/([^?]*) /index.php?_route_=$1 last;
}
# END Rewrite rules
location ~ \.php$ {
fastcgi_pass 127.0.0.1:9000;
fastcgi_index index.php;
fastcgi_param SCRIPT_FILENAME /usr/local/www/nginx/opencart$fastcgi_script_name;
Include fastcgi_params;
}
}
This is one of the ways to make the OpenCart rewrite rules working on Nginx. There are also others, alternative ways to make the rewrite rules working on Nginx - like for example, you can convert the OpenCart .htaccess rewrite rules to Nginx format with some of the online guides or converters.
In conclusion
I believe this blogpost will be in help to those decided to try the relatively new Nginx, for their OpenCart stores, as I have elaborated on the essentials and cover common pitfalls people face. Since we really love tinkering with Nginx, you can watch out for the upcoming data-rich blogpost OpenCart with Nginx vs. OpenCart with Apache comparison.
