July 10, 2014
By Severalnines

ClusterControl uses the Apache HTTP Server to serve its web interface, but it is also possible to use nginx. nginx + PHP fastcgi is well-known for its capabilities to run on a small memory footprint compared to standard Apache + PHP DSO.

 

In this post, we will show you how to run ClusterControl on nginx web server by swapping out the default Apache web server installed during the initial deployment. This blog post does not mean that we officially support nginx, it just an alternative way that a portion of our users have been interested in. For instance, Phil Bayfield wrote a blog on the same topic a while back.

 

Apache Configuration

 

Before we jump into nginx configurations, let’s look at how the ClusterControl web application is configured with Apache web server. ClusterControl consists of two web components, a web UI and CMONAPI. These components are located in the Apache’s document root which might vary depending on the operating system.

 

1. Make sure ClusterControl UI and CMONAPI exist in the document root. Document root for RedHat/CentOS and Ubuntu 14.04 LTS (Apache 2.4) is located at /var/www/html while Debian and Ubuntu 12.04 and lower is located at /var/www. ClusterControl will be installed under this root directory and you should see something like this:

$ ls -l /var/www/html
drwxr-xr-x. 6 apache apache 4096 Jul  9 16:31 cc-cmonapi-1.2.6
drwxr-xr-x. 5 apache apache 4096 Jul  9 16:31 cc-ui-1.2.6
lrwxrwxrwx. 1 root   root     26 Jul  9 16:31 clustercontrol -> /var/www/html//cc-ui-1.2.6
drwxr-xr-x. 4 apache apache 4096 Jul  8 18:34 cmon
lrwxrwxrwx. 1 root   root     31 Jul  9 16:31 cmonapi -> /var/www/html//cc-cmonapi-1.2.6

 

2. Apache must be able to read custom configuration file (.htaccess) under the document root directory, by setting AllowOverride options to All. Example in /etc/httpd/conf/httpd.conf:

<Directory "/var/www/html">
    Options Indexes FollowSymLinks
    AllowOverride All
    Order allow,deny
    Allow from all
</Directory>

 

3. Require the following PHP modules to be installed and enabled:

  • common
  • mysql
  • ldap
  • gd
  • curl

The standard Apache installation via package manager will install PHP to run as dynamic shared object (DSO). Running on this mode will require you to restart Apache in case of php configuration changes.

 

The following command should install all required packages for ClusterControl:

$ yum install httpd php php-mysql php-ldap php-gd php-curl mod_ssl #RedHat/CentOS
$ apt-get install apache2 php5-common php5-mysql php5-ldap php5-gd libapache2-mod-php5 php5-json php5-curl #Debian/Ubuntu

 

4. The ClusterControl web components must be owned by Apache web server user (apache for RedHat and www-data for Debian).

 

Switching from Apache to nginx

 

We would need to configure nginx to behave similarly to our Apache configuration, as most of the Severalnines tools assume that ClusterControl is running on Apache. 

 

1. Enable nginx repository. Depending on your operating system, please refer to this installation guide for details.

 

2. Install nginx and PHP FPM:

$ yum install nginx php-fpm -y #RedHat
$ sudo apt-get install nginx php5-fpm -y #Debian

 

3. Take note that removing Apache2 directly might cause dependent PHP packages to be uninstalled as well. So we take a safer approach by just turning it off and disabling start after boot:

Redhat/CentOS:

$ chkconfig httpd off
$ service httpd stop

 

Ubuntu/Debian:

$ sudo update-rc.d -f apache2 remove
$ sudo service apache2 stop

 

4. Open the nginx default virtual host configuration file (Redhat: /etc/nginx/conf.d/default.conf, Debian: /etc/nginx/sites-available/default) and make sure it contains following lines:

server {
	listen       0.0.0.0:80;
	server_name  localhost;
 
	access_log /var/log/nginx/localhost-access.log;
	error_log /var/log/nginx/localhost-error.log;
 
	root /var/www/html;
	index index.php;
 
	location ~ \.htaccess {
		deny all;
	}
 
	location ~ \.php$ {
		fastcgi_pass 127.0.0.1:9000;
		fastcgi_index index.php;
		fastcgi_param SCRIPT_FILENAME $document_root$fastcgi_script_name;
		include /etc/nginx/fastcgi_params;
	}
 
	# Handle requests to /clustercontrol
	location /clustercontrol {
		alias /var/www/html/clustercontrol/app/webroot;
		try_files $uri $uri/ /clustercontrol/app/webroot/index.php;
	}
 
	# Equivalent of $is_args but adds an & character
	set $is_args_amp "";
	if ($is_args != "") {
		set $is_args_amp "&";
	}
 
	# Handle requests to /clustercontrol/access
	location ~ "^/clustercontrol/access/(.*)$" {
		try_files $uri $uri/ /clustercontrol/app/webroot/access/index.php?url=$1$is_args_amp$args;
	}
 
	# Handle requests to /cmonapi
	location ~ "^/cmonapi/(.*)$" {
		try_files $uri $uri/ /cmonapi/index.php?url=$1$is_args_amp$args;
	}
 
}

 

*The above configuration example is specifically for running ClusterControl UI and CMONAPI on nginx in RedHat/CentOS. For other OS distributions, replace any occurrences of /var/www/html to its respective document root.

 

5.  Create a new virtual host configuration for SSL:

$ vim /etc/nginx/conf.d/default-ssl.conf #RedHat
$ vim /etc/nginx/sites-available/default-ssl #Debian

 

And make sure it contains following lines:

server {
	listen       443 ssl;
	server_name  localhost;
 
	ssl_certificate      /etc/pki/tls/certs/s9server.crt;
	ssl_certificate_key  /etc/pki/tls/private/s9server.key;
 
	ssl_session_cache shared:SSL:1m;
	ssl_session_timeout  5m;
	ssl_ciphers  HIGH:!aNULL:!MD5;
	ssl_prefer_server_ciphers   on;
 
	access_log /var/log/nginx/localhost-access.log;
	error_log /var/log/nginx/localhost-error.log;
 
	root /var/www/html;
	index index.php;
 
	location ~ \.htaccess {
		deny all;
	}
 
	location ~ \.php$ {
		fastcgi_pass 127.0.0.1:9000;
		fastcgi_index index.php;
		fastcgi_param SCRIPT_FILENAME $document_root$fastcgi_script_name;
		include /etc/nginx/fastcgi_params;
	}
 
	# Handle requests to /clustercontrol
	location /clustercontrol {
		alias /var/www/html/clustercontrol/app/webroot;
		try_files $uri $uri/ /clustercontrol/app/webroot/index.php;
	}
 
	# Equivalent of $is_args but adds an & character
	set $is_args_amp "";
	if ($is_args != "") {
		set $is_args_amp "&";
	}
 
	# Handle requests to /clustercontrol/access
	location ~ "^/clustercontrol/access/(.*)$" {
		try_files $uri $uri/ /clustercontrol/app/webroot/access/index.php?url=$1$is_args_amp$args;
	}
 
	# Handle requests to /cmonapi
	location ~ "^/cmonapi/(.*)$" {
		try_files $uri $uri/ /cmonapi/index.php?url=$1$is_args_amp$args;
	}
 
}

 

*The above configuration example is specifically for running ClusterControl UI and CMONAPI on nginx in RedHat/CentOS. Replace any occurrences of the following:

  • /var/www/html to its respective document root for other OS distribution
  • /etc/pki/tls/certs/s9server.crt to /etc/ssl/certs/s9server.crt for Debian/Ubuntu
  • /etc/pki/tls/private/s9server.key to /etc/ssl/private/s9server.key for Debian/Ubuntu
  • Create a symlink for /etc/nginx/sites-enabled/default-ssl:
    $ sudo ln -sf /etc/nginx/sites-available/default-ssl /etc/nginx/sites-enabled/default-ssl

 

6. Restart nginx and php-fpm:

$ service php-fpm restart
$ service nginx restart

 

Installation is complete. At this point, PHP should run under fastcgi mode and nginx has take over the web server role from Apache to serve ClusterControl UI/CMONAPI. 

 

Caveats

 

  • Severalnines’s s9s_error_reporter might not get a complete error report on ClusterControl UI/CMONAPI since it doesn’t collect any nginx related log files.
  • ClusterControl is built on a common Apache configuration. There might be some features that do not function well (although we have not encountered any malfunctions so far).
  • If you want to install nginx on an independent host and use ClusterControl UI as centralized UI (refer here for details), make sure you install all required PHP packages as described under the Apache Configuration section.