Install Domogik

If you are already a Domogik 0.3 user

You must first install Domogik 0.4.2 release. Then, you will be able to upgrade to Domogik 0.5.

Important notice about the 0.5.x release

In the 0.5.x releases, the Rest component has been merged in the Admin component. If you were using some user interfaces that uses Rest or any script. Please upgrade them :

  • use the admin port (40406) instead of the previous rest port (40405)
  • add /rest/ in front of all old Rest url. Example : http://192.168.1.10:40405/device/ become http://192.168.1.10:40406/rest/device/.

Some core butler functions interfaces have changed. All brain packages must be upgraded to Domogik 0.5.2 compliant releases.

Note

If you are already a Domogik 0.5.0 or Domogik 0.5.1 user, please upgrade the following packages to the last releases for compatibility :

  • Plugin weather
  • Plugin caller id
  • Brain base
  • Brain shopping

If you plan to install Domogik on a Raspberry pi

If you want to use a Raspberry pi A/B/B+, you should forget to install Domogik on it. Currently Domogik uses too much memory for these models.

Domogik can work fine on a Raspberry pi 2 but some users encountered some performances issues. Please avoid using this platform for now (except for test purpose).

Installation

Note

  • Domogik includes its own xPL hub. If you are running another xPL hub on your target machine (xpl-perl, etc), you will have to deactivate it before the installation.
  • In this example, we use a MySQL or MariaDB database. If you want to use a Postgresql database, please refer to the specific installations steps for Postgresql.

The sudo command

Some distributions may not include the sudo command as a default one. For Debian-based distribution, you can install it by doing as root :

# apt-get install sudo

You can also simply logon as the root user and ignore the sudo part of the command for the commands that include a sudo.

The lsb_release command

Domogik installation script uses the lsb_release -si command to check which Linux distribution you are using. Some Linux distribution has not this package instlled by default. This is the case for Raspbian for example.

On all Debian-based distributions (Raspbian for example), please install the lsb-release package like this:

$ sudo apt-get install lsb-release

On other distributions, please refer to your distribution documentation.

Dependencies

Check your Python version with the below command:

python -V

Note

Right now Domogik requires Python 2.7. Python 3 is not (yet) fully supported.

If you don’t already have Python 2.7 or above (you have it if you are running a recent Linux system), please install the following package :

  • python2.7

Note

Example on a Debian based distribution:

$ sudo apt-get install python2.7
$ sudo ln -sf /usr/bin/python2.7 /usr/bin/python

Here are the needed dependencies. depanding on your Linux distribution, they will be installed automatically Debian, Ubuntu) or not.

  • the development packages, pip and setuptools : python2.7-dev, python-pip, python-setuptools
  • SSL libraries : libssl-dev
  • Zero MQ library : libzmq-dev >= 14.4. With the 14.3 release of this library, the publish/subscribe feature will not work!
  • postgresql libraries : libpq-dev, python-psycopg2
  • various needed libraries : python-mako, libffi-dev, python-netifaces
  • git : git
  • MariaDB server (or MySQL server) : mariadb-server (or mysql-server)
  • Sphinx and Sphinx theme : python-sphinx, sphinx-better-theme

Note

  • Even if you plan to use MariaDB (or MySQL) database instead of postgresql, the python-psycopg2 package is needed by the alembic library.

The install.py script will install these dependencies for the following distributions:

  • Debian based distributions

For all the other distributions, please install them manually.

Dependencies to install manually

The netifaces python library can’t be installed automatically. For now you will have to install it manually. Example for debian based distributions:

$ sudo apt-get install python2.7-dev python-pip
$ sudo pip install netifaces

In minimum debian repo the package sphinx-better-theme does not exist:

$ sudo pip install sphinx-better-theme

About Debian stable (8.6)

If you are using a Debian stable, you will need to install a more recent release of alembic related package. You will have to follow these steps.

Create the file /etc/apt/apt.conf.d/99defaultrelease. It must contain :

APT::Default-Release "stable";

Create the file /etc/apt/sources.list.d/stable.list :

deb     http://ftp.fr.debian.org/debian/    stable main contrib non-free
deb-src http://ftp.fr.debian.org/debian/    stable main contrib non-free
deb     http://security.debian.org/         stable/updates  main contrib non-free

Create the file /etc/apt/sources.list.d/testing.list :

deb     http://ftp.fr.debian.org/debian/    testing main contrib non-free
deb-src http://ftp.fr.debian.org/debian/    testing main contrib non-free
deb     http://security.debian.org/         testing/updates  main contrib non-free

Then run :

$ sudo apt-get update
$ sudo apt-get -t testing install python-sqlalchemy python-editor python-sqlalchemy python-alembic

It will install the needed packages from the testing repository.

MariaDB (or MySQL server)

Note

Notice that MariaDB and MySQL are two compliant database engines. We recommend to use MariaDB instead of MySQL. All the instructions will be about MariaDB. Please notice that the MariaDB tools and services are named as mysql.

Note

  • If you have already a MariaDB or MySQL server installed, you will only have to create the Domogik database.
  • Please note that Domogik does not automatically install the MariaDB (or MySQL) server.
  • If you choose to manually create the database, it is highly recommended to use the innodb engine (which can be enabled in /etc/mysql/my.cnf)

Install the packages for MariaDB server:

$ sudo apt-get install mariadb-server

During the installation, Domogik will automatically create the database, but if you want to create the database yourself, log on the mysql database as root user:

$ mysql -u root -p
Enter password:

Create a database called domogik and add grants on it to the user domogik:

CREATE DATABASE domogik;
GRANT ALL PRIVILEGES ON domogik.* to domogik@localhost IDENTIFIED BY 'domopass';

Download Domogik components

Note

The following commands assume that you are using the /opt/dmg/ folder as the root folder for Domogik. And so Domogik will be installed in the /opt/dmg/domogik/ folder. If you choose another folder, please keep in mind the below points:

  • You must put Domogik sources in a folder which can be read by all the system users and the domogik user. For example, be careful if you extract domogik sources in /home/john/domogik and you choose the domogik user during installation : the domogik user must have write access to /home/john/domogik.
  • Don’t download Domogik sources directly in /root or /
  • The folder path must also not contains any spaces in its name!

Two components are needed to install domogik :

  • domogik-mq : the message queue component used by all components which want/need to use the message queue (Domogik, Domoweb, ...)
  • domogik

Git is used to get the sources (be sure that your user is able to create some directories where you will clone the sources).

Create the folder /opt/dmg/ :

$ sudo mkdir -p /opt/dmg
$ sudo useradd -M domogik
$ sudo chown domogik /opt/dmg  # assuming the user domogik already exists!
$ sudo chmod 777 /opt/dmg

Download the packages

Download Domogik-mq :

$ cd /opt/dmg/
$ wget --content-disposition https://github.com/domogik/domogik-mq/archive/1.4.tar.gz
$ tar xvzf domogik-mq-1.4.tar.gz
$ ln -sf domogik-mq-1.4 domogik-mq
$ cd domogik-mq

Download Domogik :

$ cd /opt/dmg/
$ wget --content-disposition https://github.com/domogik/domogik/archive/0.5.2.tar.gz
$ tar xvzf domogik-0.5.2.tar.gz
$ ln -sf domogik-0.5.2 domogik
$ cd domogik

Install Domogik-mq

Run the install.py script :

$ cd /opt/dmg/domogik-mq
$ sudo ./install.py --dist-packages

You will be requested to give some informations.

[ Create domogik-mq user ]
As what user should domogik-mq run? [domogik]:

Give the system user you will use to install Domogik. You can use a dedicated user named domogik if you want. I would suggest you to use your personal user if you are not familiar with users and related permissions on Linux.

Install MQ as master (lib+daemon) or client (lib only) ? [M/s]:

On on single server installation, choose the default option (library and daemon). On a multi server installation (not yet ready in 0.5), on the main server, choose the default option and on the other servers, choose the client option.

Install Domogik

Run the install.py script :

$ cd /opt/dmg/domogik/
$ sudo ./install.py --dist-packages

You will be requested to give some informations.

[ Create domogik user ]
As what user should domogik run? [domogik]:

Give the system user you will use to install Domogik. You can use a dedicated user named domogik if you want. I would suggest you to use your personal user if you are not familiar with users and related permissions on Linux.

[ Update /etc/default/domogik ]
Configuration files
Do you want to keep your current config files ? [Y/n]:

If you already have a configuration file, you could keep it. But the rest section will not be used anymore (as Rest and Admin have been merged in the Admin component).

[ Starting on section database ] Key type [mysql]: Key user [domogik]: Key password [domopass]: Key port [3306]: Key name [domogik]: Key host [127.0.0.1]:

Set up the database credentials. I you created the database as defined in this page, you can keep the default values. Even for a MariaDB database engine, keep the mysql value.

You should keep the default values.

[ Starting on section butler ]
Key name [Aria]:
Key lang [fr_FR]:
Key sex [female]:

These are the information about the butler. If you are not a french user, set the lang to the appropriate choice, for example en_US.

[ Starting on section backup ]
Key folder [/var/lib/domogik/backup/]: /tmp/

Set the folder you want to use to save Domogik backups.

During the database installation or update, if needed the MariaDB administrator password will be asked.

[ Installing or upgrading the db ]
==> Creating backup
Do you want to backup your database? [Y/n]

If you are upgrading your Domogik, you should let the installer do a backup of your database!

Backup file? [/tmp/domogik-1442999380.sql]

Set the backup file

Note

About Domogik 0.5 database upgrade.

  • the following action may take some time : INFO [alembic.runtime.migration] Running upgrade 2e6c120aa69a -> a2a3015badf, Upgrade float precission: it will affect all the history table, so it may take a while to run! Don’t worry if this is very long, just wait for the end ;)

Note

  • Domogik uses a configuration file which is created and configured by the install.py script. This file is /etc/domogik/domogik.cfg. For more informations, please read the page related to the configuration file.
  • If you want to use the C xPL hub instead of the python xPL hub, you need to update manually the configuration after Domogik installation. You can check the technical documentation for more informations about configuring the xPL Hub.

In case you keep your old Domogik 0.4.0 configuration file /etc/domogik/domogik.cfg, you will have to complete it with these lines for Domogik 0.4.2 :

[butler]
name = Aria
lang = fr_FR
sex = female

[backup]
folder = /opt/dmg/backup

[metrics]
id = some_random_id_of_your_choice
url = http://metrics.domogik.org/

And you will also have to replace the below line value (use a network interface name instead of an ip address). Example:

bind_interface = eth0,lo

Butler section :

  • The name is your butler name, use the name you want.
  • The lang is your language : fr_FR, en_US, ...
  • The sex is related to the name you choosed : male, female

Backup section :

  • The folder location is the place in which all domogik data will be backuped (database, configuration files, etc).

Metrics section :

  • The id should be some anonymous id.
  • The url must not be changed.

If you are wondering what metrics are, please check the note about metrics in the 0.5.0 release note.

Make Domogik start with your computer

For Debian or Ubuntu systems:

$ sudo update-rc.d domogik defaults

Start domogik

$ sudo /etc/init.d/domogik start
* Starting 0MQ broker ... Done.
* Starting 0MQ forwarder ... Done.
* Starting xPL (python version)... Done.
* Starting Manager (with -d -r -x -s)... Done.
* Starting the admin interface ... Done.

It will start :

  • The 0MQ broker and forwarder
  • The xpl hub
  • The Domogik manager on this host
  • The database manager and the REST interface module (which will take in account the parameters you defined in your configuration file : host, IP...)
  • The administration web interface

Note

Domogik administration is available on http://<ip>:40406/ if you didn’t change the port number.

Default login and password are :

  • login : admin
  • password : 123

Set up the automatic backup and packages documentation automatic upgrade

If you want (and you should), you could configure a daily (or weekly) backup. Domogik provides a python backup script : backup.py.

To use it, edit your crontab file:

crontab -e

And add at the end the below lines:

# Domogik backup each night at 1:00
0 1 * * * /opt/dmg/domogik/backup.py > /var/log/domogik/backup-$(date "+\%Y\%m\%d_\%H\%M").log 2>&1
# Domogik : regenerate packages documentation each hour
0 * * * * /opt/dmg/domogik/src/domogik/bin/package.py -d >> /var/log/domogik/refresh_docs_pkg-$(date "+\%Y\%m\%d").log 2>&1

The default backup folder is /var/lib/domogik/backup/. You can change it in the file /etc/domogik/domogik.cfg in the section [backup]. Example:

###
# Backup configuration
###
[backup]
folder=/var/lib/domogik/backup/

Next step : install and use a user interface

You can use either Domoweb or Domodroid to control your home.

It doesn’t work?