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.

Attention

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

Node.js

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

MongoDB

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

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.

Attention

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

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

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

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

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