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.


► After you install the Ayyeka server software onto an on-premises server, your on-premises server is no longer synchronized with the Ayyeka cloud server for any user interface or Wavelet updates.  

► Ayyeka does not take responsibility for security, backing up or otherwise maintaining your on-premises server and data.

►It is the responsibility of the customer to provide redundancy, cyber security, and full disk encryption for any on-premises deployment.



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



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.

TCP Port Description Direction Recommend Firewall Configuration
8883 MQTT device communication Inbound Must be opened in your external network firewall to allow inbound device traffic 
9443 HTTPS  device communication Inbound Must be opened in your external network firewall to allow inbound device traffic
99 Firmware-over-the-air  Inbound Must be opened in your external network firewall to allow inbound device traffic
80 Not in use, automatic redirect to 443 Inbound Allowed for internal users only, closed for external traffic
443 Web user interface Inbound Allowed for internal users only, closed for external traffic
85 REST API for agent integration Inbound Allowed for internal users only, closed for external traffic





Internal microservice communication Inbound Must be closed to all inbound internal and external communication

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:

Target IP/Host Port 443 443 443

Subnets Used by the Installation Procedure

The installation procedure uses the following subnets:


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



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

Note: It is recommended that you change the sudo password timeout to at least 60 minutes.

There are two ways to install the libraries:

Installation Method Commands
Automatic by the Installer
OFFLINE_PACKAGES=Yes INSTALL_PATH=/opt/onprem ./onprem_offline_install_*.run


  • INSTALL_PATH must not be any of the following directories: /tmp, /etc, /var, /bin, or /dev.
  • The installer will try to install the packages from the internet if they are not found.
  • Install with sudo privileges.
Manual on the command line
sudo apt update
sudo apt install moreutils jq unzip ansible mysql-client -y
wget -qO- | tar xvz && sudo ln -s `pwd`/flyway-7.11.0/flyway /usr/bin
curl -fsSL | sudo apt-key add -
sudo add-apt-repository "deb [arch=amd64] $(lsb_release -cs) stable"
sudo apt-get update -y
sudo apt-get install docker-ce docker-ce-cli 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:
Devices Hardware Resources Storage
For 1-50 Wavelets
  • 4x Intel/AMD CPU cores

  • 8 GB RAM

500 GB SSD
For 51-500 Wavelets
  • 10x Intel/AMD CPU cores

  • 16 GB RAM


For 501-4000  Wavelets

  • 32x Intel/AMD CPU cores
  • 64 GB RAM


1. Depending on your traffic and data volume, you might need to add more storage over time.

2. Running the Ayyeka software on an on-premises server is CPU-intensive. Therefore, this configuration is the minimum that you must have on your server.



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. 

Note: You might need to add the "execution attribute" to the command:   chmod +x onprem_offline_install_*.run


    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. 

       2.    Log out, and then log in to apply the new security privileges to the administrative user.

    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.

    Note: A minimum of 12 characters is required for the new password.
    The password must contain a combination of uppercase and lowercase letters and numbers.

    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:  
       2.   Fill in the following information when prompted:
      • 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.


    For an on-premises system, you must not generate the REST API keys when logged in as the (super)Admin user. The keys generated by the Admin user will not work.


     For general information about the REST API, see Getting Started with REST API.

    If you need to restart the installation, do the following steps:

    1. Go to the installation directory, and then run the script located there ( ./ Note: Any data in your database will be deleted.

    2. Rerun Step 2 above.


    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 You may wish to provide Ayyeka Support with direct access to your on-premises server.

    For this reason, it is recommended that you set up a VPN so that if there are problems, Ayyeka Support can directly access your on-premises server. Otherwise, Support cannot access your system without your direct involvement.