1.0.0-beta.5 • Public • Published


Domapic Controller

Controller for Domapic systems

Build status Coverage Status Quality Gate js-standard-style

NPM dependencies Last commit

NPM downloads Website License

Table of Contents


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.

Domapic system example

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)


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:

Quick start


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 IP. If not, use the "admin" user with "admin" password. Remember to add your own administrator user and delete the default one.

Swagger example

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



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 ['', '::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= --logLevel=debug --color=false


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 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.


npm i domapic-controller


DownloadsWeekly Downloads






Unpacked Size

139 kB

Total Files


Last publish


  • javierbrea