Domapic Controller

Controller for Domapic systems

---

Table of Contents

• Introduction
• Prerequisites
• Quick Start
  • Installation
  • Start the server
  • Display logs
  • Get API Key to connect Domapic Services
  • Stop and restart
• Options
• Security

---

Introduction

Controller server for Domapic domotic systems.

Connect all your Domapic Modules and control them with a single application.

NOTE: The next schema includes some Domapic pieces that are still not released. The Domapic Cloud plugin, mobile apps and Alexa plugin will be available soon.

Above, an example of two modules in a Domapic System. Now, the relay can be controlled using the web or mobile applications, or interacting with ["Alexa"][alexa-url] or ["HomeKit"][homekit-url]. Automatisms can be configured in the [Domapic Controller Web UI][domapic-controller-url] to make the [Phillips Hue][hue-url] bulb be switched off automatically when the relay bulb is switched on, for example. (Automatisms feature is still in development)

Prerequisites

Domapic controller is built with Node.js, and uses MongoDB as database, so, first of all, you need to have installed them in your system:

• Installing Node.js and npm
• Installing MongoDB

Quick start

Installation

Install Domapic-controller globally using npm:

npm i domapic-controller -g --production

Start the server

domapic-controller start

The controller process will be started at background (using PM2 as manager). Now you can browse to http://localhost:3000 to check that the server has started successfully.

The Domapic Controller Web User interface will be available at that url. If you are loading the web interface from localhost, login is not necessary because authentication is disabled by default for the 172.0.0.1 IP. If not, use the "admin" user with "admin" password. Remember to add your own administrator user and delete the default one.

Note that, with basic options, server will be started over http protocol, and security will be disabled for localhost requests. Read about all options and security to start the controller with stricter security options.

Display logs

domapic-controller logs

This command will display last logs of server, and will continue displaying logs until CTRL-C is pressed.

Server logs are saved too into a daily file. These files are rotated automatically and only last ten days files are kept. You´ll find these files in the ~/.domapic/domapic-controller/logs folder.

Server logs are managed by PM2 too, so, it is recommended to install PM2 log rotate to avoid pm2 logs file growing too much.

Get API Key to connect Domapic Services

Checking the server log you´ll find something like:

2018-09-29 19:35:55.042: [controller] [info] Connected to database "mongodb://localhost:27017/domapic"
2018-09-29 19:35:56.855: [controller] [info] 
-----------------------------------------------------------------
Use the next api key to register services: 6hka5b0jnT9HOMJjUNquqOLneFGxYYtfOygguKoACUIviRvTJLV4IzglcybePQLB
-----------------------------------------------------------------
2018-09-29 19:35:56.885: [controller] [info] Server started and listening at port 3000

Copy the provided api key and place it in a safe place, and use it later when starting your Domapic Services (plugins or modules), in order to allow them to automatically register themself into the controller and connect with it.

Stop and restart

domapic-controller stop

This command will stop the server, and, if you used the --save option when you started it for first time, you´ll be able to start it again with same settings simply executing:

domapic-controller start

If you want your server to be started automatically on system reload, use the pm2 startup and pm2 save commands:

pm2 startup
pm2 save

Options

Help

Use the next command to display help with detailed information about all available commands and options:

# Display all available commands:
domapic-controller --help

# Display all options for an specific command (domapic-controller [command] --help):
domapic-controller start --help

Start command options:

option	description	default
--name	Custom service instance name. Name can be defined too as first argument. Default is "domapic-controller"	-
--db	MongoDB connection uri	mongodb://localhost:27017/domapic
--port	Http port used	3000
--hostName	Hostname for the server	-
--sslCert	Path to an ssl certificate	-
--sslKey	Path to an ssl key	-
--authDisabled	Array of IPs or CIDR IP ranges with authentication disabled	['127.0.0.1', '::1/128']
--auth	If false, authentication will be disabled for all origins	true
--secret	Secret to be used in authentication encoding	-
--color	Use ANSI colors in traces	true
--logLevel	Tracing level. Choices are 'log', 'trace', 'debug', 'info', 'warn' and 'error'	info
--path	Path to be used as home path, instead of user´s default (.domapic folder will be created inside)	~
--saveConfig	Save current options for next execution (except name and path)	false
--rejectUntrusted	Reject untrusted ssl certificates when making requests to modules or plugins	false

Example of setting options from command line:

domapic-controller start --name=fooName --authDisabled=192.168.1.128/25 --logLevel=debug --color=false

Security

The Domapic Controller can be securized in order to expose it from local network to internet, and act as a remote controller for all your local network Domapic Services.

Follow the next steps to securize your Controller before exposing it to the internet:

• Setup an administrator user:

  The Controller is distributed with a default administrator user, which name is "admin", and password is "admin". Delete it and setup your own administrator user.

  You can use both the web user interface or the command line interface in order to remove the user:

   domapic-controller user remove admin
  

   domapic-controller user add
  

  You will be prompted for user name, role, email and password. Using your real email will allow you to use OAuth to login at Domapic Cloud and access to your controller through it.

• Enable ssl:

  Enable ssl for your Controller Server generating an SSL certificate. Use options --sslCert and --sslKey to define the paths to each file, and remember to use the --save option to store that settings for next server restarts. From now, your server will start using https instead of http.

• Provide a custom secret for JWT authentication:

  Domapic controller provides two methods of authentication, jwt and api keys. The first one will be used by allowed human users to access to the provided web user interface (still in development). Provide a custom secret using the --secret option to make this method securer. Remember to use the --save option to store the secret for next restarts.

• Disable the authentication whitelist:

  Authentication can be disabled for desired IPs or IP ranges using the --authDisabled option, or for all origins using the --auth=false option. By default, authentication is disabled only for the 172.0.0.1 IP in order to make easier the first configuration, but you can disable it for your whole your local network, etc. Because of security reasons, this is not recommended, take into account that users accessing to the controller with authentication disabled will have equivalent permissions to an user with "admin" role. Use always the built-in api keys method to identify your Domapic Services. If you want to force the authentication requirement even for localhost, use the --authDisabled as a flag, without specifying any IP.