Installation Guide

This guide is for installing GenieACS on a single server on any Linux distro that uses systemd as its init system.

The various 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/failover setup.

For production deployments make sure to configure TLS and change UI_JWT_SECRET to a unique and secure string. Refer to HTTPS section for how to enable TLS to encrypt traffic.

Prerequisites

GenieACS requires Node.js 12.13 and up. Refer to https://nodejs.org/ for instructions.

GenieACS requires MongoDB 3.6 and up. Refer to https://www.mongodb.com/ for instructions.

Install GenieACS

Installing from NPM:

sudo npm install -g genieacs@1.2.13

Installing from source

If you prefer installing from source, such as when running a GenieACS copy with custom patches, refer to README.md file in the source package. Adjust the next steps below accordingly.

Configure systemd

Create a system user to run GenieACS daemons

sudo useradd --system --no-create-home --user-group genieacs

Create directory to save extensions and environment file

We’ll use /opt/genieacs/ext/ directory to store extension scripts (if any).

mkdir /opt/genieacs mkdir /opt/genieacs/ext chown genieacs:genieacs /opt/genieacs/ext

Create the file /opt/genieacs/genieacs.env to hold our configuration options which we pass to GenieACS as environment variables. See Environment Variables section for a list of all available configuration options.

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

Generate a secure JWT secret and append to /opt/genieacs/genieacs.env :

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

Set file ownership and permissions:

sudo chown genieacs:genieacs /opt/genieacs/genieacs.env sudo chmod 600 /opt/genieacs/genieacs.env

Create logs directory

mkdir /var/log/genieacs chown genieacs:genieacs /var/log/genieacs

Create systemd unit files

Create a systemd unit file for each of the four GenieACS services. Note that we’re using EnvironmentFile directive to read the environment variables from the file we created earlier.

Each service has two streams of logs: access log and process log. Access logs are configured here to be dumped in a log file under /var/log/genieacs/ while process logs go to journald. Use journalctl command to view process logs.

If the command systemctl edit --force --full fails, you can create the unit file manually.

Run the following command to create genieacs-cwmp service:

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

Then paste the following in the editor and save:

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

Run the following command to create genieacs-nbi service:

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

Then paste the following in the editor and save:

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

Run the following command to create genieacs-fs service:

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

Then paste the following in the editor and save:

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

Run the following command to create genieacs-ui service:

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

Then paste the following in the editor and save:

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

Configure log file rotation using logrotate

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

/var/log/genieacs/*.log /var/log/genieacs/*.yaml daily rotate 30 compress delaycompress dateext >

Enable and start services

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 message for each to verify that the services are running successfully.