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.
Important:
► 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.
Contents
Planning for an On-Premises Server
Inbound Traffic and Open Ports
Outbound Traffic to Map Provider
Supported Subnets Used by the Installation Procedure
Step 1: Connect to Ubuntu Server
Step 3: Verify the Installation
Step 4: Change the Admin User Password
Step 5: Designate the SMTP Server Connection String
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 |
83 84 8079 8123 |
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 |
mapbox.com | 443 |
api.mapbox.com | 443 |
api.tiles.mapbox.com | 443 |
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.
- 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.
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 Note:
|
Manual on the command line |
sudo apt update |
- The on-premises server must have the following minimal hardware provisioned:
Devices | Hardware Resources | Storage |
For 1-50 Wavelets |
|
500 GB SSD |
For 51-500 Wavelets |
|
1 TB SSD |
For 501-4000 Wavelets |
|
1 TB SSD |
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.
- Log in with the operating system administrative user credentials.
- 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
-
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
- 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.
- Run the change admin password shell script, from the Ubuntu console (SSH client), by typing the command:
dchpwd admin update_config2. 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.
- Run the command:
dsmtp_setup2. 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
- In your web browser, type in the new on-premises server's IP address (or domain name if it is registered in your DNS).
-
Log in to the UI with the administrator username (admin) and the password that you changed in Step 4, above.
- Create a new Account.
- 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.
- Log out of the UI as the administrator.
- Log into the UI as your new user with the Account Owner role.
- 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.
If you need to restart 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.