Server Configuration

Server Configuration

In order to get everything up and running, you need to:

1. Set up Runtime environment
2. Set up the Web Server and the MONO Runtime
3. Create a VirtualHost in Apache for HTTP, HTTPS or both
4. Configure MySQL Connection String in app configuration (see Server Appliation Configuration section)
5. Set up regular schedules processes

The app has been tested on standard Debian Debian Jessie (8) Linux distribution. It's required to have Apache2 and Mono installed. Apache2 is a standard web server which is used to handle all request for the server application. MONO is a runtime which is able to run .NET assemblies on Linux. MOD_MONO is an interconnection point between Apache and MONO which is capable of running ASP.NET websites (such as this server application) on Linux machines.

sudo apt-get install apache2
sudo apt-get install mono-complete
sudo apt-get install mono-apache-server

Create a file /etc/apt/preferences.d/stretch with the following contents (note that should be no extra empty lines between the records in the file):

Package: *
Pin: release n=jessie
Pin-Priority: 900
Package: libapache2-mod-mono
Pin: release n=stretch
Pin-Priority: 800
Package: ca-certificates-mono
Pin: release n=stretch
Pin-Priority: 800

and execute ...

echo "deb http://ftp.cz.debian.org/debian/ stretch main" | sudo tee -a /etc/apt/sources.list
sudo apt-get update

sudo apt-get install ca-certificates-mono
sudo apt-get install libapache2-mod-mono

In order to prevent following error:

Access to the path “/etc/mono/registry” is denied

you need to :

sudo mkdir /etc/mono/registry
sudo chmod uog+rw /etc/mono/registry

The interconnection between Apache web server and MONO runtime is provided by MOD_MONO project (http://www.mono-project.com/docs/web/mod...). The MOD_MONO is enabled using the following command. Technically it creates a link in /etc/apache2/mods-enabled to a configuration file in /etc/apache2/mods-available, therefore if there's anything wrong with this command, check the existence of particular configuration file. If there's nothing like that, you probably don't have MOD_MONO installed at all. Following command usually says that it's enabled by default.

sudo a2enmod mod_mono

Because of the performance reasons, you may also want to enable the HTTP compression using (usually enabled by default):

sudo a2enmod deflate

You may want to disable default Apache site (located in /var/www/html and bound to port 80) using:

sudo a2dissite 000-default

To enable the application for the web server you need to add following VirtualHost element into the Apache configuration. In the first version this was done in the default configuration file (usually /etc/apache2/apache2.conf), recently it's preferable to create a separate host file (eg. /etc/apache2/sites-available/002-poweranalyzer-http.conf). It includes also HTTP compression (lines containing DEFLATE string). Note the INSERT_YOUR_SERVER_NAME line.

As of version 2.0.3 (=43) it is recommended to add the line AddType text/vtt .vtt in order to supply subtitles for video tutorials correctly.

MonoServerPath "/usr/bin/mod-mono-server4" 

<VirtualHost *:80>
  MonoAutoApplication disabled

  ServerName INSERT_YOUR_SERVER_NAME
  DocumentRoot /var/www/poweranalyzer
  ErrorLog ${APACHE_LOG_DIR}/errorMono.log
  CustomLog ${APACHE_LOG_DIR}/accessMono.log combined
  MonoServerPath "/usr/bin/mod-mono-server4" 
  Alias /webapp "/var/www/poweranalyzer" 
  MonoApplications "/:/var/www/poweranalyzer" 
  MonoDebug true
  <Directory /var/www/poweranalyzer>
    SetHandler mono
    SetOutputFilter DEFLATE
    AddType text/vtt .vtt
  </Directory>
  <IfModule mod_deflate.c>
       AddOutputFilterByType DEFLATE text/html text/plain text/xml text/javascript application/javascript application/json
  </IfModule>
</VirtualHost>

In the end you may enable the host site using:

sudo a2ensite 002-poweranalyzer-http

Now you can place the application in the desired folder (/var/www/poweranalyzer in this case) and set the access rights so it's readable by all.

mkdir /var/www/poweranalyzer
... unpack app

NOTE: If you want to use different ports than the default one (80 for HTTP), you need to change this at the start of the VirtualHost section (see above) and then double check this in the Apache ports configuration (/etc/apache2/ports.conf) - if there's a Listen command for all the ports you need (usually Listen 80 for HTTP and Listen 443 for HTTPS communication. Following example holds for using the port 8081.

Listen 8081

After changes in web server configuration you need to restart the service using

sudo service apache2 restart

If you're in shared or production environment you may want to check the configuration before the restart using

apachectl configtest

At this point you may get warning about domain/server name. This should be fixed by using proper SSL certificate (or generating properly named self-signed certificate as can be seen in the following step).

This guide comes from this guide. You need to active the SSL module in Apache2 using

sudo a2enmod ssl

You may generate a self-signed certificate using:

sudo mkdir /etc/apache2/ssl 
sudo openssl req -x509 -nodes -days 365 -newkey rsa:2048 -keyout /etc/apache2/ssl/apache.key -out /etc/apache2/ssl/apache.crt

You may need to create a new VirtualHost in Apache2 configuration (as HTTP host cannot be shared with HTTPS). A crucial point is to enter ServerName that matches the server certificate and double check the paths to the certificates. Following configuration contains also the HTTP compression (lines containing DEFLATE string).

NOTE: First deployments contained this configuration inside Apache's main configuration file (/etc/apache2/apache2.conf), while recently it's preferable to create a separate host file (eg. /etc/apache2/sites-available/003-poweranalyzer-https.conf).

<VirtualHost *:443>
  MonoAutoApplication disabled

  ServerName INSERT_YOUR_SERVER_NAME
  SSLEngine on
  SSLCertificateFile /etc/apache2/ssl/apache.crt
  SSLCertificateKeyFile /etc/apache2/ssl/apache.key

  DocumentRoot /var/www/poweranalyzer
  ErrorLog ${APACHE_LOG_DIR}/errorMono.log
  CustomLog ${APACHE_LOG_DIR}/accessMono.log combined
  MonoServerPath "/usr/bin/mod-mono-server4" 
  Alias /webapp "/var/www/poweranalyzer" 
  MonoApplications "/:/var/www/poweranalyzer" 
  MonoDebug true
  <Directory /var/www/poweranalyzer>
    SetHandler mono
    SetOutputFilter DEFLATE
  </Directory>
  <IfModule mod_deflate.c>
       AddOutputFilterByType DEFLATE text/html text/plain text/xml text/javascript application/javascript application/json
  </IfModule>
</VirtualHost>

In the end you may enable the host site using:

sudo a2ensite 003-poweranalyzer-https

The HTTPS port should be included in the Apache2 configuration (usually /etc/apache2/ports.conf - should contain a line Listen 443) or any other port you need. Following example holds for using alternative HTTPS port - 8043.

Listen 8043

To simply set proper file access rights (assuming the web server is running under default user www-data) you may use:

sudo chown -R www-data:www-data /var/www/poweranalyzer
sudo chmod -R u+rwx /var/www/poweranalyzer

In order to set up multiple applications on one server, one may simple create multiple application folders (eg. /var/www/poweranalyzer_d1, /var/www/poweranalyzer_d2), then create multiple corresponding Apache web-sites (eg. /etc/apache2/sites-available/004-poweranalyzer-d1http.conf, /etc/apache2/sites-available/005-poweranalyzer-d2http.conf) with appropriate Listen configuration. There are two important things that need to be checked:

All application should have its own alias - in the file /etc/apache2/sites-available/004-poweranalyzer-d1http.conf you should have something like:

ServerName C014H010_d1
Alias /webapp_d1 "/var/www/poweranalyzer_d1"

Following paragraph is obsolete since v1.9.8 (Historian do not uses sessionState anymore due to bugs in MONO implementation).

In order to have separated session identifiers (allows the user to be logged separately to all instances of the server) - the /var/www/poweranalyzer_d1/web.config file should contain (inside the system.web tag) something like (notice the attribute cookieName):

<sessionState timeout="60" cookieName="pad1"  />

In order to run the app properly, the configuration of MySQL should be also adjusted. Required configurations are documented at MySQL Configuration Options.

Scheduled processes are activated by requesting the url /apiv1/scheduler of the application with the appropriate adminKey parameter. It's recommended to schedule a repeated action for this task using

crontab -e

where in edit mode you can enter a scheduled task (eg. using Midnight Commander editor)

*/60 * * * * /var/www/poweranalyzer_cron/scheduler.sh

This line will make cron daemon to execute the specified script every 60 minutes. The script has following content (you need to enter specific URL on particular server):

wget http://SERVER_IP:SERVER_PORT/apiv1/scheduler?adminKey=ADMIN_KEY -O /var/www/poweranalyzer_cron/scheduler.out

There's usually a predefined cron.daily job which restarts the Apache server every day. As reloading the application usually takes a couple of minutes, this is not a desired behavior. It can be disabled by removed the /etc/cron.daily/apache2 file or by removing its execute privileges.

Note: Previously the CRON job executed the CRON action on Historian which was used to periodically check for new data in database. In recent versions this call has been moved to data conversion batch and is no-longer needed. Previously shown SCHEDULER action has different purpose - it server for automated report generation.

If you need to get to MySQL which is not properly configured for login, but you have local access? Edit the file /etc/mysql/my.cnf and after [mysqld] insert

skip-grant-tables

Then restart the service using

sudo service mysql restart

Now you may sign into using

mysql -u root

However in this mode if you need to work with access rights, you need to execute

FLUSH PRIVILEGES;

and now you may grant access to anyone using:

GRANT ALL ON *.* TO inflex@'historianServer' IDENTIFIED BY 'HESLO';

We have several times experienced a situation where the application is running and while there are no requests being served, the CPU is being used in 100% by the mono process. The problem seems to be when updating/or restarting the application, Apache may be unable to kill all dedicated MONO worker processes. These processes (and their PIDs) may be observed using the command

top

and then manually killed using

sudo kill -9 PARTICULAR_PID