Skip to main content

Installation

This documentation will guide you on how to run APEX Message Service on the following platforms:

Hardware requirements​

APEX Message Service is an application that does not need a lot of resources. The minimum hardware requirements are: 1 CPU core and 2 GB of RAM.

It can run on x64 and ARM64 processors. Oracle Cloud provides both x64 and ARM64 processors and a free tier to try it out.

A question we often get is: does AMS have to go on its own server, the database server, or the application (ORDS) server?

Because the AMS Server is running (mostly) in direct connection with your client's browsers, you should choose the server that is closest to your clients. If you have a lot of clients in the same region, you can run AMS on the same server as ORDS. If you have clients worldwide, you should run AMS on its own server in those different regions.

Installation on Linux​

Download and unzip file​

Log in on ams.united-codes.com and download the Linux version of AMS. Copy the zip you downloaded to the server where you want to run the AMS Server. Unzip the file in a directory of choice, e.g.,/opt/ams

Because we have builds for different architectures, you need to download and run the correct version for your architecture.

The commands below have to correspond with the architecture of your server. For example, if you have an ARM64 server, you need to download the ARM64 version of AMS.

create AMS directory​

mkdir /opt/ams

unzip​

unzip ams_linux_ARCH_v23.1.zip -d /opt/ams

give permissions to executable​

chmod 755 /opt/ams/APEXMessageServerLinuxARCH

Installation on Windows​

Download and unzip file​

Log in on ams.united-codes.com and download the Windows version of AMS. Copy the zip you downloaded to the server where you want to run the AMS Server. Unzip the file in a directory of choice, e.g., D:\ams

Running as a Service in Windows​

  • Navigate to WindowsService folder situated in the APEXMessageService folder.

  • Edit 1_SetupAsService.bat to include the full path to the executable APEXMessageServiceWin64.exe

    Note that you can also add additional parameters, for example, for the port it should run on and the starting directory.
    nssm.exe install APEXMessageService %0\..\..\APEXMessageServiceWin64.exe

  • Run 1_SetupAsService.bat.

  • The service should be installed and can be seen in Services (Control Panel > Administrative Tools > Services).

  • To change how the APEXMessageService service starts, you can change it from Services or start it manually via 2_StartService.bat (should be run as Administrator).

  • To check if the service has started, navigate to http://localhost:3000/

  • To stop the service, run 3_StopService.bat as Administrator or stop it from Services.

  • To remove APEXMessageService as a service, run 4_RemoveService.bat.

  • The APEXMessageService service should now be removed from Services. If it says Disabled, it will be removed after the service stops.

Activate and manually start APEX Message Service​

APEX Message Service needs a valid license file. If AMS doesn't find a license, it will run in Trial mode. You have all the features when running in Trial mode, but AMS will print a trial watermark on top of the document.

To activate AMS so there's no trial watermark:

  • Go to the folder containing the executable for APEXMessageService and run: 
    ./APEXMessageServiceLinux64 -a
  • AMS will prompt you for the email.
  • Enter the email you registered with and where a license has been bought.
  • AMS will try to generate the license key. The license key will be generated if there is an open connection to the internet. AMS will generate a license request file if there’s no internet connection or something goes wrong with the activation. After logging in, you can upload this license request file on the dashboard at https://www.united-codes.com/products/apexmessageservice/. Once you receive the license file, it should be placed in the same directory as the AMS executable. If the license file is located somewhere else, please modify the ams_config.jsonc file to point to it.
  • Once the license file is generated, a restart of AMS is necessary. AMS will log the license information in the next run.

To start APEX Message Service:

  • go to the server directory and run 

    ./APEXMessageServiceLinux64 &

On the first run of APEXMessageService, a configuration file, ams_config.jsonc, is created. Customize the ams_config.jsonc file to your needs. For example, to change the port to a different port than the default 8010.

If you encounter this error:

-------------------------------------------------
Error on Thu Feb 04 2016 19:33:35 GMT-0800 (PST)
-------------------------------------------------
listen EADDRINUSE

It means the port is already in use.

Start/Stop APEX Message Service as a service​

You can use systemd (systemctl) on Linux to start and stop services. You can follow the instructions for Red Hat and Oracle Enterprise Linux below.

As user root or sudo privileged user:

  1. create the ams user

    sudo useradd ams
    sudo groupadd ams
    sudo usermod -a -G ams ams

  2. give the ams user the privileges to the /opt/ams directory

    chown ams:ams /opt/ams -R

  3. create ams.service

    cd /etc/systemd/system
    vi ams.service

Paste the following in and adjust for your installation as required. In this script, AMS is installed in /opt/ams, run with the ams user which has as home directory /home/ams.

[Unit]
Description=APEX Message Service
After=network.target

[Service]
Type=simple
User=ams
Group=ams

Environment=AMS_HOME=/opt/ams
Environment=AMS_PROCESS_NAME=APEXMessageService
Environment=AMS_EXECUTABLE_NAME=APEXMessageServiceLinuxARCH # Don't forget to replace ARCH with the correct architecture
Environment=PATH=/usr/local/bin:/usr/bin:/usr/local/sbin:/usr/sbin:/bin/
Environment=HOME=/home/ams

SyslogIdentifier=apexmessageservice
Restart=always
RestartSec=30
TimeoutStartSec=30
TimeoutStopSec=30
WorkingDirectory=/opt/ams
ExecStart=/usr/bin/env ${AMS_HOME}/${AMS_EXECUTABLE_NAME}
ExecStop=/usr/bin/env pkill ${AMS_PROCESS_NAME}

[Install]
WantedBy=multi-user.target

Reload the daemon

systemctl daemon-reload

A simple setup is needed to install the version of ams in /opt/ams. When you install a new version, unzip in this directory. You will end up, for example, with the following directories: v18.2, v19.3, and v21.2. Create a symbolic link in the directory /opt/ams to point to the latest version.

ln -s /opt/ams /opt/ams/latest

Suppose something is not working properly, and you need to revert to your previous version; you only need to change the symbolic link to point to a previous version. For example

unlink latest
ln -s /opt/ams /opt/ams/latest

As root

start ams               : systemctl start ams
stop ams                : systemctl stop ams
status ams              : systemctl status ams
autostart at boot       : systemctl enable ams
remove autostart at boot: systemctl disable ams

To view detailed logs of the service, do the following:

journalctl -u ams.service

FAQ On Installation​

What kind of information is sent during activation?

When you try to activate the product, AMS will ask for the registered email. Afterward, it looks at the UUID/GUID of the machine, which is:

For Windows:

MachineGuid key in registry HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\Cryptography

For Linux:

/var/lib/dbus/machine-id

The machine id is then hashed using sha-256.

The following content after encryption is sent to the AMS license server:

{
"email": "provided-registered-email",
"mid": "sha-256 hashed machine-id",
"version": "AMS version getting activated"
}

Since SHA-256 is a one-way function, deriving the actual machine id from the given hash is impossible. No actual IP address, hostname, serial number, MAC address, or any other hardware information is exposed.

Does the AMS on-prem version require internet access to activate/run?

During the activation, AMS will try to connect to our license server. If this fails, AMS will generate a license request file that can be uploaded to our website to get the license file back. This license file should be placed in the same folder as the AMS executable.

In short, AMS does not require internet access to be activated and to run.