Production Installation

Install and configure GenieACS for production deployments on Linux with systemd.

This guide walks through installing GenieACS on a single Linux server that uses systemd as its init system.

The four GenieACS services are independent of each other and may be installed on different servers. You may also run multiple instances of each in a load-balancing or failover setup.

For production deployments, configure TLS and change UI_JWT_SECRET to a unique and secure string. See the TLS/HTTPS guide for details.

Prerequisites

Node.js 12.13 or later

GenieACS requires Node.js 12.13 and up. Refer to nodejs.org for installation instructions.

MongoDB 3.6 or later

GenieACS requires MongoDB 3.6 and up. Refer to mongodb.com for installation instructions.

Install GenieACS

Install GenieACS globally from npm:

sudo npm install -g genieacs

Configure systemd

1. Create a system user

   Create a dedicated system user to run the GenieACS daemons:

   sudo useradd --system --no-create-home --user-group genieacs
   
2. Create the extensions directory

   Create /opt/genieacs/ext/ to store extension scripts:

   mkdir /opt/genieacs
   mkdir /opt/genieacs/ext
   chown genieacs:genieacs /opt/genieacs/ext
   
3. Create the environment file

   Create /opt/genieacs/genieacs.env to hold configuration options passed to GenieACS as environment variables.

   Save the following as /opt/genieacs/genieacs.env:

   GENIEACS_CWMP_ACCESS_LOG_FILE=/var/log/genieacs/genieacs-cwmp-access.log
   GENIEACS_NBI_ACCESS_LOG_FILE=/var/log/genieacs/genieacs-nbi-access.log
   GENIEACS_FS_ACCESS_LOG_FILE=/var/log/genieacs/genieacs-fs-access.log
   GENIEACS_UI_ACCESS_LOG_FILE=/var/log/genieacs/genieacs-ui-access.log
   GENIEACS_DEBUG_FILE=/var/log/genieacs/genieacs-debug.yaml
   NODE_OPTIONS=--enable-source-maps
   GENIEACS_EXT_DIR=/opt/genieacs/ext
   

   See Environment variables for a full list of available configuration options.

4. Generate a secure JWT secret

   Generate a cryptographically secure random value and append it to the environment file:

   node -e "console.log(\"GENIEACS_UI_JWT_SECRET=\" + require('crypto').randomBytes(128).toString('hex'))" >> /opt/genieacs/genieacs.env
   

   The GENIEACS_UI_JWT_SECRET value signs browser cookies. Never use a weak or guessable value in production. The command above generates a 256-character hex string using Node.js’s built-in crypto module.

5. Set file permissions

   Restrict access to the environment file since it contains the JWT secret:

   sudo chown genieacs:genieacs /opt/genieacs/genieacs.env
   sudo chmod 600 /opt/genieacs/genieacs.env
   
6. Create the logs directory

   mkdir /var/log/genieacs
   chown genieacs:genieacs /var/log/genieacs
   
7. Create systemd unit files

   Create a unit file for each of the four GenieACS services. Each file uses the EnvironmentFile directive to load configuration from /opt/genieacs/genieacs.env.

   If systemctl edit --force --full fails, create the unit files manually at /etc/systemd/system/<service-name>.service.

   genieacs-cwmp

   Run the following command, then paste the unit file content into the editor and save:

   sudo systemctl edit --force --full genieacs-cwmp
   

   [Unit]
   Description=GenieACS CWMP
   After=network.target
   
   [Service]
   User=genieacs
   EnvironmentFile=/opt/genieacs/genieacs.env
   ExecStart=/usr/bin/genieacs-cwmp
   
   [Install]
   WantedBy=default.target
   

   genieacs-nbi

   sudo systemctl edit --force --full genieacs-nbi
   

   [Unit]
   Description=GenieACS NBI
   After=network.target
   
   [Service]
   User=genieacs
   EnvironmentFile=/opt/genieacs/genieacs.env
   ExecStart=/usr/bin/genieacs-nbi
   
   [Install]
   WantedBy=default.target
   

   genieacs-fs

   sudo systemctl edit --force --full genieacs-fs
   

   [Unit]
   Description=GenieACS FS
   After=network.target
   
   [Service]
   User=genieacs
   EnvironmentFile=/opt/genieacs/genieacs.env
   ExecStart=/usr/bin/genieacs-fs
   
   [Install]
   WantedBy=default.target
   

   genieacs-ui

   sudo systemctl edit --force --full genieacs-ui
   

   [Unit]
   Description=GenieACS UI
   After=network.target
   
   [Service]
   User=genieacs
   EnvironmentFile=/opt/genieacs/genieacs.env
   ExecStart=/usr/bin/genieacs-ui
   
   [Install]
   WantedBy=default.target
   
8. Configure log rotation

   Save the following as /etc/logrotate.d/genieacs:

   /var/log/genieacs/*.log /var/log/genieacs/*.yaml {
       daily
       rotate 30
       compress
       delaycompress
       dateext
   }
   
9. Enable and start services

   Enable each service to start on boot, then start it and verify its status:

   sudo systemctl enable genieacs-cwmp
   sudo systemctl start genieacs-cwmp
   sudo systemctl status genieacs-cwmp
   
   sudo systemctl enable genieacs-nbi
   sudo systemctl start genieacs-nbi
   sudo systemctl status genieacs-nbi
   
   sudo systemctl enable genieacs-fs
   sudo systemctl start genieacs-fs
   sudo systemctl status genieacs-fs
   
   sudo systemctl enable genieacs-ui
   sudo systemctl start genieacs-ui
   sudo systemctl status genieacs-ui
   

   Review the status output for each service to confirm it is running successfully. Use journalctl -u genieacs-cwmp (or the relevant service name) to view process logs.

Next steps

TLS/HTTPS

Encrypt traffic between CPE devices and the CWMP service, and secure the UI with TLS.

Environment variables

Full reference for all configuration options available to each service.