Installing New FAI Local Server

When you decide to establish your own on-premises server rather than take advantage of the Ayyeka cloud platform, you must make your platform conform to the system requirements and hardware sizing specified in this document.

When you decide to establish your own on-premises server rather than take advantage of the Ayyeka cloud platform, you must make your platform conform to the system requirements and hardware sizing specified in this document.  Furthermore, you are responsible for all of the standard operations, including administration, backups, and general server maintenance.

In this document, we will guide you through a step-by-step deployment. After you install the Ubuntu server operating system on your on-premises server, you will install the Ayyeka FAI Local. Subsequently, you will need to migrate each device from the cloud instance to your on-premises instance.

Contents

Planning for an On-Premises Server

Network and Security

Inbound Traffic and Open Ports

Outbound Traffic to Map Provider

Supported Subnets Used by the Installation Procedure

Prerequisites

Installation

Step 1: Connect to Ubuntu Server

Step 2: Do the Installation

Step 3: Verify the Installation 

Step 4:  Change the Admin User Password

Step 5: Designate the SMTP Server Connection String

Step 6: Do Sanity Check

Step 7: Final Steps

Planning for an On-Premises Server

The server Operations personnel need the following skill set:

• Linux server maintenance (familiarity with Ubuntu distribution version 20.04)

• Administrative responsibility for server, network, security, backups, etc.

• The customer needs to supply the security appliances to secure device communication. See the section Network and Security.

An enterprise email server, or a dedicated email server must be available that will perform the following tasks:

• Email notification

• User invitations 

The user workstation that will act as a client to connect to the on-premises server during the installation, needs the following software tools:

• SSH client connects to the on-premises server

• FTP/SCP tool for uploading resource files to the on-premises server

You must provide your own SIM for each device that will communicate with the on-premises server, or purchase SIMs and SIM service from  Ayyeka. Information about the SIM card that you provide is not available in the Cellular Sessions tab for the device.         

Network and Security

Inbound Traffic and Open Ports

The following table lists the open ports on the on-premise server that must be secured with your firewall and network security tools.

Outbound Traffic to Map Provider

The web user interface uses a 3rd party mapping provider. In order to allow the web browser to load maps, allow the following outbound traffic through your firewall:

Subnets Used by the Installation Procedure

The installation procedure uses the following subnets:

• 172.25.0.0/24
• 172.25.1.0/24
• 172.25.2.0/24
• 172.25.3.0/24

TLS Certificate

By default, a self-signed certified is provided as part of the installation package. If you want to use a different TLS certificate, contact support@ayyeka.com.

Prerequisites

• Fixed IP address or DNS for inbound HTTPS/MQTT traffic from the devices. See the required list of inbound device ports above.
• You must know the internal IP address or DNS host name of your on-premises server. 
• You must know the SMTP server host, the SMTP port, the SMTP username, and the SMTP password for the email server.
• Contact support@ayyeka.com to get the installation deliverables (onprem_offline_install_*.run).

The on-premises server must fulfill the following requirements:

• The server must be a dedicated server for on-premises use only.
• You must be an Administrative user with sudo privileges. If you need to add or edit a user, see Adding a New User and Editing a User.

• The on-premises server must have the following operating system setup:
  • Ubuntu Server, version 20.04 Server Edition must be installed.  
  • The timezone must be set to UTC. See How To Set or Change Timezone on Ubuntu 20.04. 
  • The following libraries are required and must be installed: moreutils, jq, unzip, mysql-client v8+, ansible, flyway, docker, docker-compose.
  • The server's time must be synced via Network Time Protocol (NTP).

There are two ways to install the libraries:

OFFLINE_PACKAGES=Yes INSTALL_PATH=/opt/onprem ./onprem_offline_install_*.run

sudo apt update
sudo apt install moreutils jq unzip ansible mysql-client -y
wget -qO- https://repo1.maven.org/maven2/org/flywaydb/flyway-commandline/7.11.0/flyway-commandline-7.11.0-linux-x64.tar.gz | tar xvz && sudo ln -s `pwd`/flyway-7.11.0/flyway /usr/bin
curl -fsSL https://download.docker.com/linux/ubuntu/gpg | sudo apt-key add -
sudo add-apt-repository "deb [arch=amd64] https://download.docker.com/linux/ubuntu $(lsb_release -cs) stable"
sudo apt-get update -y
sudo apt-get install docker-ce docker-ce-cli containerd.io docker-compose -y
sudo usermod -aG docker $USER
sudo systemctl enable docker
sudo ln -sf `which docker-compose` /usr/local/bin/docker-compose

• The on-premises server must have the following minimal hardware provisioned:

Installation

In this section, you will connect to the Ubuntu server, and then install the Ayyeka on-premises software on the server. You will verify the installation and do a brief sanity check. Finally, you will configure an SMTP email server.

Step 1: Connect to Ubuntu Server  

Use the SSH client to connect to the Ubuntu server. All of the following commands are executed from this SSH client.

1. Log in with the operating system administrative user credentials.
2. Copy onprem_offline_install_*.run to the installation directory. 

Step 2: Perform the Installation 

1. Run the following shell script to begin the installation:

 OFFLINE_PACKAGES=Yes   INSTALL_PATH=/opt/onprem ./onprem_offline_install_<version>.run

Step 3: Verify the Installation 

1. Check the lines on the console following the “PLAY RECAP” line:

As part of the installation, the administrative user is added to the docker security group. This allows the administrative user to execute the post-installation scripts in subsequent steps. 

Step 4: Change the Admin User Password

It is highly recommended that you change the default password for the user interface "admin" user.  However, even if you wish to retain the default password (temporarily), you need to run this command in order to set up internal configuration files.

1. Run the change admin password shell script, from the Ubuntu console (SSH client), by typing the command: 

 dchpwd admin update_config

  2.   When prompted, enter the new password, and then press the Enter key.  Repeat when requested to confirm the new password.

Step 5: Designate the SMTP Server Connection String

On the on-premises server, do the following steps in the SSH console (if you are unable to provide these connection properties, you may skip this step for now). However, without configuring the SMTP server, you will be unable to add users to the application and send email notifications when required.

1. Run the command:  

dsmtp_setup

• • SMTP Server Host
  • SMTP Server Port
  • SMTP Username
  • SMTP Password
  • Support TLS 1.2 - If the on-premises server uses TLS 1.2, then type in "Yes" (type out the entire word without the quotation marks, and capitalize the "Y")
  • FromAddress (email address of sender)

   3.   Restart the SMTP service: drestart backend

   4.   Verify the successful SMTP configuration by performing Step 4 in the Sanity Check below.

Step 6: Do Sanity Check

1. In your web browser, type in the new on-premises server's IP address (or domain name if it is registered in your DNS). 

2. Log in to the UI with the administrator username (admin) and the password that you changed in Step 4, above.

3. Create a new Account.
4. From the new Account, click on the Invite User link to send yourself a User Invitation.
   • Enter your email address, specify the Account Owner role, then click Submit. 
   • When you receive the Invitation email, open the email, and then click the Accept Invitation link.
   • Complete your user profile: password, mobile number, time zone, and so forth.
5. Log out of the UI as the administrator.
6. Log into the UI as your new user with the Account Owner role.
7. In the left pane of the UI, click API, and then click the Agents tab. Download the CSV Agent.

Step 7: Final Steps

Encrypt the Server
As a security precaution, it is recommended that you encrypt the entire on-premises disk.

Migrate All Devices from the Cloud to the On-Premises Server

Now that you've installed  Ayyeka On-Premises, devices will need to be migrated from the default on-cloud server to the on-premises server. Follow the steps in Device Migration from FAI Pro to FAI Local.

Set up a VPN (optional)

You are responsible for all maintenance, management, administration, and operations of your on-premises server.  If you require assistance, contact support@ayyeka.com. You may wish to provide Ayyeka Support with direct access to your on-premises server.