emurestapi

Setup

The emurestapi shim is a multi-threaded, multi-tenanted HTTP based server implementing the EMu REST API on top of Texpress. Its most common use is to provide EMu based services for EMu implementations. The server is designed to be plug compatible with Axiell Flow. The server may also be used for other projects requiring a REST based API to EMu.

Installation

The emurestapi shim including the server and configuration files can be downloaded from the Axiell Nexus Repository. The download is available in both zip and tgz formats. The following instructions describe the installation process where emurestapi is to be used in a production environment.

  1. Check either OpenJDK 8 or OpenJDK 11 is installed on the server.
  2. Add user emu to the password file with a home directory of /home/emu. A password should be set and a login shell of bash used.
  3. Add group emuadmin to the group file.
  4. Create the home directory /home/emu and set the directory ownership to user emu and group emuadmin.
  5. Login (or su) as user emu.
  6. Download the latest version (3.1.1) of the emurestapi installation archive using wget in either zip or tgz format.
  7. Unarchive the installation file using unzip or tar based on the file type downloaded. The emurestapi-3.1.1 directory will be created.
  8. Create a symbolic link from emurestapi-3.1.1 to restapi with the command ln -s emurestapi-3.1.1 restapi.
  9. See the configuration section for the registering of tenants and server options.

The system is now installed and can be run by executing restapi/bin/emurestapi. The server will run in the foreground if started this way. It is recommended the server starts when the operating system is booted. Consult the relevant section below for the operating system on which emurestapi is installed.

FreeBSD

A FreeBSD startup file can be found in the restapi/rc directory. The file is called emurestapi.freebsd. To install the startup file:

  1. Login as user root
  2. Enter cp ~emu/restapi/rc/emurestapi.freebsd /usr/local/etc/rc/emurestapi
  3. Enter chmod 755 /usr/local/etc/rc/emurestapi
  4. Enter vi /usr/local/etc/rc/emurestapi
  5. Change all instances of EMUPATH to ~emu (expanded).
  6. Save the file.
  7. Edit /etc/rc.conf and add emurestapi_enable="YES"
  8. Start the service by executing service emurestapi start

The shim should now be running and will be started whenever the system is rebooted. The shim can be stopped by entering service emurestapi stop.

Linux (systemd)

If the version of Linux on which emurestapi is installed uses systemd then the following instructions should be followed:

  1. Login as user root
  2. Enter cp ~emu/restapi/rc/emurestapi.systemd /etc/systemd/system/emurestapi.service
  3. Enter vi /etc/systemd/system/emurestapi.service
  4. Change all instances of EMUPATH to ~emu (expanded).
  5. Save the file.
  6. Enter systemctl daemon reload
  7. Enter systemctl enable emurestapi
  8. Enter systemctl start emurestapi

The shim should now be running and will be started whenever the system is rebooted. The shim can be stopped by entering systemctl stop emurestapi.

Solaris

A Solaris startup script can be found in the restapi/rc directory. The file is called emurestapi.solaris. To install the startup file:

  1. Login as user root
  2. Enter cp ~emu/restapi/rc/emurestapi.solaris /etc/rc3.d/S97emurestapi
  3. Enter vi /etc/rc3.d/S97emurestapi
  4. Change all instances of EMUPATH to ~emu (expanded).
  5. Save the file.
  6. Enter chmod 755 /etc/rc3.d/S97emurestapi
  7. Start the serive by executing /etc/rc3.d/S97emurestapi start

Upgrade

If emurestapi has already been installed then the following instructions should be used to update to the latest version:

  1. Stop the running version of emurestapi.
  2. Login (or su) as user emu.
  3. Download the latest version (3.1.1) of the emurestapi installation archive using wget in either zip or tgz
  4. Unarchive the installation file using unzip or tar based on the file type downloaded. The emurestapi-3.1.1 directory will be created.
  5. Enter rm -f restapi
  6. Enter ln -s emurestapi-3.1.1 restapi
  7. Enter cp emurestapi-oldversion/conf/tenants.conf restapi/conf/tenants.conf
  8. Enter cp emurestapi-oldversion/conf/restapi.conf restapi/conf/restapi.conf (if changes made to server configuration)
  9. Login (or su) as user root
  10. Start up emurestapi (using service for FreeBSD, systemctl for Linux or /etc/rc3.d/S97emurestapi start for Solaris).

Development

If development work is to be undertaken then a local copy of the emurestapi source is required. The following commands will download the source, build the shim and documentation and run the server.

git clone git@gitto.axiell.com:alm/alm-r-d/emu/emurestapi.git
cd emurestapi
sbt compile makeSite run

The documentation can be found under emurestapi/target/site.

Dependencies

Next: Configuration