General
      Back to home
      1. Help Center
      2. FAI-Local (On-premises Deployment)
      3. General

      Installing New FAI Local Server

      Ensure your on-premises server meets the system requirements and hardware specifications detailed in this document.

      If you choose to set up an on-premises server instead of using the Ayyeka cloud platform, ensure it meets the system requirements and hardware specifications outlined in this document. 

      Using FAI Local you are also responsible for server operation including administration, backups, and maintenance.


      This document provides a step-by-step guide for deployment. After installing Ubuntu on your server, you will install Ayyeka FAI Local and migrate each device from the cloud instance to your on-premises setup.

      Important:

      ► After you installing FAI Local solution on your server, you will no longer recieve any user interface or Wavelet updates.

      ► Ayyeka does not take responsibility for server 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.

                                                                                                                                                                                                                                                                                                  

      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 admin need the following skill set:

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

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

      • Knowledge on how 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 card for each device that will communicate with the on-premises server, or purchase SIM cards 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 & do port forwarding to your FAI Local Server
      9443 HTTPS  device communication Inbound Must be opened in your external network firewall to allow inbound device traffic & do port forwarding to your FAI Local Server
      99 Firmware-over-the-air  Inbound Must be opened in your external network firewall to allow inbound device traffic & do port forwarding to your FAI Local Server
      443 Web user interface Inbound Allowed for internal users only, closed for external traffic, could be opened for external traffic if FAI is required to be used outside of company's network.

      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
      mapbox.com 443
      api.mapbox.com 443
      api.tiles.mapbox.com 443

       

      If you would like to remove 3rd party maps you can remove it as a super admin user.

      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.

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

      • Server Requirements:

      There are two ways to install the libraries:

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

      Note:

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

      		 1 TB SSD 

      For 501-4000  Wavelets
      • 32x Intel/AMD CPU cores

      • 64 GB RAM

      		 1 TB SSD 
       
      Notes:

      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.

       

       

      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. 

      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:

        sudo 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

        Important:
        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

           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 redo the installation, do the following steps:

        1. Go to the installation directory, and then run the uninstall.sh script located there ( ./uninstall.sh). 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 support@ayyeka.com. 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.

         

        To change the SSL/TLS certificate on the on-premises server (optional)

        1. Go to the nginx config directory: /etc/ayyeka/nginx
        2. Once you are there, you'll see three files that are related to the process:
             nginx.conf
             nginx.crt
             nginx.key
        3. First of all, better to create a backup of these files.
        4. Now, add to this directory your TLS certificate (your .crt and .key files).
        For example: my.crt, my.key (other names are allowed as well, as long as they end with .crt and .key)

         

        5. Now the /etc/ayyeka/nginx contains at least these files:
             nginx.conf
             nginx.crt
             nginx.key
             nginx.conf_orig
             nginx.crt_orig
             nginx.key_orig
             my.crt
             my.key
         
        6. The next step is to edit the nginx.conf file:
        In the file, go to the sections that starts with "server" following "listen 443 ssl;":
        This section contains two relevant parameters, that should be changed:
        ssl_certificate
        ssl_certificate_key

         

        7. Change the first one (ssl_certificate) to be /etc/ayyeka/nginx/my.crt instead of /etc/ayyeka/nginx/nginx.crt
        8. Change the second one (ssl_certificate_key) to be /etc/ayyeka/nginx/my.key instead of /etc/ayyeka/nginx/nginx.key

         

        Note: nginx.crt and nginx.key should remain in the directory. They are used for ports 9443 and 8883, that receive device traffic. Do not change these configurations (ports 9443 and 8883). Changing these ports will block any device communication. The only port that should be modified is 443.