1. cossmic_release Avatar cossmic_release
  2. CoSSMic release
  3. developer-guide

Wiki

Clone wiki

developer-guide / EmonCMS installation

View History

emoncms header

This document describes how to install emoncms (Energy monitoring Content Management System), an open-source web-app for processing, logging and visualising energy, temperature and other environmental data and part of the OpenEnergyMonitor project. The guide should work on most debian systems, but was adjusted to work on wheezy images.

1 Dependencies

First, you may start by updating the system repositories and installing the newest versions of core dependency packages like mercurial, build essentials, containing tools (like the gcc compiler, make tool, etc) for compiling/building software from source and the ntp Network Time Protocol synchronization tool.

sudo apt-get update
sudo apt-get install mercurial build-essential ntp

1.1 MySQL and Redis

The storage of the monitored e.g. energy or temperature data will be handled in a MySQL database, together with redis, an in memory database. Redis is used to store the feed and input last values which do not need to be persistent on disk. Storing these in memory therefore reduces disk writes potentially increasing the life span of the SD card.

The installers can be again downloaded via debian repository. During the MySQL installation you will be promted to enter a root password, which is needed for the further emoncms access. Generate a safe phrase and write it down or remember it well. 

sudo apt-get install mysql-server mysql-client redis-server

To secure the MySQL database, the secure installation script can be used. It is installed as part of the Ubuntu/Debian package and is installed in /usr/bin, so run it with /usr/bin/mysql_secure_installation. Basically answer yes to everything except changing root password (because you’ve already set it).

Next, configure redis /etc/redis/redis.conf to limit its RAM usage below the section LIMITS.

maxmemory 200MB

1.2 HTTP server and PHP

This installation guide contains two separate HTTP servers, of which one has to be chosen from:

  • Apache is probably the most common webserver world wide. It relies on separate processes for each active connection, due to which it can become quite RAM consuming and hence slow. If only few connections are to be expected for the web server to be handled, apache stands out by being in development for a long time with a good library of plugins and modules. In combination with mod-php5 it can even become a very quick solution.

  • Lighttpd is in comparison a very young and RAM efficient webserver, asynchronously handling every connection in one process, even when multithreading for a huge amount of possible connections, which is why it scales very well with the CPU of small servers. Together with fast-cgi, lighttpd can be quite quick as well.

1.2.1 Apache2

To implement the webserver with apache2, install it together with its' script language extension and other web-app dependencies 

sudo apt-get install apache2 libapache2-mod-php5 php5 php5-mysql php5-curl php-pear php5-dev php5-mcrypt php5-json

Emoncms uses a front controller to route requests. Hence Mmdrewrite needs to be configured by 

sudo a2enmod rewrite

and editing the file /etc/apache2/apache2.conf for <Directory /> and <Directory /var/www/> change AllowOverride None to AllowOverride All.

Now that the webserver got prepared, pecl dependencies (serial, redis and swift mailer) must be installed 

sudo pear channel-discover pear.swiftmailer.org
sudo pecl install channel://pecl.php.net/dio-0.0.6 redis swift/swift

and the pecl modules added to the php5 config 

sudo sh -c 'echo "extension=dio.so" > /etc/php5/apache2/conf.d/20-dio.ini'
sudo sh -c 'echo "extension=dio.so" > /etc/php5/cli/conf.d/20-dio.ini'
sudo sh -c 'echo "extension=redis.so" > /etc/php5/apache2/conf.d/20-redis.ini'
sudo sh -c 'echo "extension=redis.so" > /etc/php5/cli/conf.d/20-redis.ini'

1.2.2 Lighttpd

To implement the webserver with lighttpd, install it together with the cgi script language extension and other web-app dependencies 

sudo apt-get install lighttpd php5-cgi php5 php5-mysql php5-curl php-pear php5-dev php5-mcrypt php5-json

Next, configure fast-cgi 

sudo ln -s /etc/lighttpd/conf-available/10-fastcgi.conf /etc/lighttpd/conf-enabled/10-fastcgi.conf
sudo ln -s /etc/lighttpd/conf-available/15-fastcgi-php.conf /etc/lighttpd/conf-enabled/15-fastcgi-php.conf

and modify the configuration /etc/lighttpd/lighttpd.conf:

  • Uncomment mod_rewrite for the front controller to route requests

    server.modules = (
        ...,
        "mod_rewrite",
)

  • Add the lines below

    url.rewrite-if-not-file = (
        "^/emoncms/([^?]*)\?(.*)$" => "/emoncms/index.php?q=$1&$2",
        "^/emoncms/([^?]*)$" => "/emoncms/index.php?q=$1",
)

Now that the webserver got prepared, pecl dependencies (serial, redis and swift mailer) must be installed 

sudo pear channel-discover pear.swiftmailer.org
sudo pecl install channel://pecl.php.net/dio-0.0.6 redis swift/swift

and the pecl modules added to the php5 config 

sudo sh -c 'echo "extension=dio.so" > /etc/php5/cgi/conf.d/20-dio.ini'
sudo sh -c 'echo "extension=dio.so" > /etc/php5/cli/conf.d/20-dio.ini'
sudo sh -c 'echo "extension=redis.so" > /etc/php5/cgi/conf.d/20-redis.ini'
sudo sh -c 'echo "extension=redis.so" > /etc/php5/cli/conf.d/20-redis.ini'

1.3 log4php

For emoncms' logging to work, log4php needs to be enabled 

sudo pear channel-discover pear.apache.org/log4php
sudo pear install log4php/Apache_log4php

Restart the webserver sudo /etc/init.d/apache2 restart or sudo /etc/init.d/lighttpd restart
and redis server sudo /etc/init.d/redis-server restart to prepare future logging.

2 Install emoncms

First, create data repositories for the emoncms feed engines with the right permissions 

sudo mkdir /var/lib/phpfiwa
sudo mkdir /var/lib/phpfina
sudo mkdir /var/lib/phptimeseries

sudo chown www-data:root /var/lib/phpfiwa
sudo chown www-data:root /var/lib/phpfina
sudo chown www-data:root /var/lib/phptimeseries

Now the emoncms application can be installed via mercurial from its repository on bitbucket

Mercurial is a source code management and revision control system but at this stage it is just used to download and update the emoncms application. You may want to install one of the other branches of emoncms or something of you own here. 

sudo hg clone https://bitbucket.org/cossmic/emoncms /usr/share/emoncms
sudo ln -s /var/www/html /usr/share/emoncms

2.1 Create a MySQL database

Start the SQL and enter the root password that you set above. 

mysql -u root -p

Then create the emoncms database, add a user for it (think of a nice long password): 

CREATE DATABASE emoncms;
CREATE USER 'YOUR_USER_NAME'@'localhost' IDENTIFIED BY 'YOUR_SECURE_PASSWORD_HERE';

Give it permissions on the new database and exit MySQL 

GRANT ALL ON emoncms.* TO 'YOUR_USER_NAME'@'localhost';
FLUSH PRIVILEGES;
exit

2.2 Emoncms settings

At last, the database settings need to be updated, to use your new secure password and allow emoncms to access mySQL. To do this, make a copy of the default settings and call it settings.php 

sudo cp /usr/share/emoncms/default.settings.php /usr/share/emoncms/settings.php

Now, open /usr/share/emoncms/settings.php in an editor and update the lines:

$server   = "localhost";
$database = "emoncms";
$username = "YOUR_USER_NAME";
$password = "YOUR_SECURE_PASSWORD_HERE";

Emoncms can now be accessed in the browser. If not over a configured openVPN connection, the page will be viewed on the servers IP address, appended with "/emocnms/", or utilize your hostname with bonjour http://cossmic.local/emoncms/

The first time you run emoncms it will automatically setup the database and you will be taken straight to the register/login screen.

Create an user by entering your desired name and password and clicking register to complete. Now, after running the page the first time, emoncms' database test and initiation can be disabled by modifying /usr/share/emoncms/settings.php again

  • disable user registration

    $allowusersregister = FALSE;

  • stop database setup test

    $dbtest = FALSE;

At last, the owners city location and timezone may be set in the Account section of the emoncms homepage.

3 Updating

Using mercurial, the project can be updated by running a command.
This could be executed by a distributed or cron scheduled script. 

sudo hg pull -u -R /usr/share/emoncms

Updated