GuidesAPI ReferenceLatest UpdatesBlogVideosStart Building Apps
Guides

Standalone Version

Suggest Edits

API Express allows enterprises to quickly mobilize existing systems with RESTful APIs so that they can be accessed from other applications including mobile or desktop apps by allowing modernization of legacy systems without re-writing them and making them accessible through mobile apps. This is highly beneficial as many enterprises are still constrained by legacy applications that are not mobile friendly. With API Express Standalone, enterprises are free to deploy it behind their firewall, while still leveraging the rest of the Appery.io Platform from the cloud.

Appery.io provides the opportunity to install API Express on demand using Docker container.

Why Docker

Docker is a software technology providing containers and promoted by the company Docker, Inc. Docker provides an additional layer of abstraction and automation of operating-system-level virtualization on Windows, Linux and macOS. Docker uses the resource isolation features of the Linux kernel such as cgroups and kernel namespaces, and a union-capable file system such as OverlayFS and others to allow independent "containers" to run within a single Linux instance avoiding the overhead of starting and maintaining virtual machines (VMs). (https://en.wikipedia.org/wiki/Docker_(software) )

Docker advantages

  • Speed
  • Lightweight
  • Isolation
  • Automation
  • Portability
  • Migration

Installation Procedure

API Express Architecture

1216

Docker Setup

You can download docker from official website https://www.docker.com/. Community Edition is totally free.

Installation instructions for Ubuntu:

https://docs.docker.com/engine/installation/linux/docker-ce/ubuntu/

Check here for Linux:
https://docs.docker.com/engine/installation/linux/linux-postinstall/

Installation instructions for Windows:

https://docs.docker.com/docker-for-windows/install/

Run Docker Container

Run docker using the following command:

docker run -it -p 11443:11443 -p 12443:12443 -v pgdata:/var/lib/postgresql/data --name standalone apperyio/api-express-standalone

apperyio/api-express-standalone is the name of docker image from Appery.io public docker repository https://hub.docker.com/r/apperyio/api-express-standalone/

standalone is the name of Docker container which will be created from the Docker image apperyio/api-express-standalone

API Express stores all data into the PostgreSQL database. In order to save all assets created into API Express after restarting Docker container, adding mapping -v pgdata:/var/lib/postgresql/data is required

It is possible to specify the folder where data of the PostgreSQL database will be stored.

Example for Linux and macOS:

docker run -it -p 11443:11443 -p 12443:12443 -v /home/{username}/apiexpress/docker/data:/var/lib/postgresql/data --name standalone apperyio/api-express-standalone

Example for Windows:

docker run -it -p 11443:11443 -p 12443:12443 -v c:\Users\{username}\apiexpress\docker\data:/var/lib/postgresql/data --name standalone apperyio/api-express-standalone

API Express has two servers admin working on the internal port 11443 and aex runtime server working on the internal port 12443. To make these servers available outside of container mapping internal ports to external ones is required
-p 11443:11443 -p 12443:12443

Start Admin node

To start the API Express admin node, run the following command:

docker exec -it standalone bash "./admin_start.sh"

standalone is the name of container created in the previous step

Start AEX node

To start the API Express aex node, run the following command:

docker exec -it standalone bash "./aex_start.sh"

After that, you can test API Express in your browser.

Open the page https://localhost:11443/apiexpress and log in using the default credentials: admin/admin.

Stop Standalone Docker Container

Docker container can be stopped using the following command:

docker stop standalone

Start Already Existing Standalone Docker Container

Docker container can be restarted (if it was stopped before) using the following command:

docker start standalone

Update API Express

Appery.io is constantly improving API Express and users can update the already installed version of API Express without losing their data.

To update API Express, just perform the following steps:

  1. Stop the standalone Docker container:
docker stop standalone
  1. Remove the standalone Docker container:
docker rm standalone
  1. Pull the latest API Express standalone docker image:
docker pull apperyio/api-express-standalone
  1. Run docker container (https://docs.appery.io/v2.4.0/docs/standalone-version#run-docker-container).

Customization

If necessary, Appery.io users can customize working with API Express.

To do it, docker has to be started with some additional parameter:

-v {path on user's machine}:/defaults

Example for Linux and macOS:

docker run -it -p 11443:11443 -p 12443:12443 -v pgdata:/var/lib/postgresql/data -v /home/{username}/apiexpress/docker/config:/defaults --name standalone apperyio/api-express-standalone

Example for Windows:

docker run -it -p 11443:11443 -p 12443:12443 -v pgdata:/var/lib/postgresql/data -v c:\Users\{username}\apiexpress\docker\config:/defaults --name standalone apperyio/api-express-standalone

All API Express properties are located in the apiexpress.properties file:

aex.domain=localhost:12443
runtime.poolsize=32
aex.request.maxsize=5242880
aex.component.rest.request.maxsize=10241000
aex.component.sql.request.maxsize=10241000
aex.component.sql.response.maxrows=1000
admin.session=1440
aex.project.session=1440
aex.flow.runtime=30000

wildfly.keystore.password=change_it
wildfly.key.password=change_it
wildfly.key.alias=localhost

Properties io.appery.apiexpress.standalone.aex.domain, wildfly.keystore.password, wildfly.key.password, wildfly.key.alias=localhost will be explained in the Security section below

aex.domain - host name with port of aex node (should be changed in case of using custom domain name)
runtime.poolsize - Number of threads on aex nodes which can process user requests
aex.request.maxsize - Maximum request size (bytes) of REST services created in API Express
aex.component.rest.request.maxsize - Maximum request size (bytes) of REST component in API Express custom service
aex.component.sql.request.maxsize - Maximum request size (bytes) of SQL component in API Express custom service
aex.component.sql.response.maxrows - Maximum rows number of SQL component in API Express custom service
aex.flow.runtime - Maximum running time (milliseconds) of API Express service in milliseconds
admin.session - Lifetime (minutes) of jwt token of admin node
aex.project.session - Lifetime (minutes) of jwt token of aex node

Note Customization on Windows

In case of facing issues with mapping configuration folder on a Windows machine, it is possible to use following workaround.

  1. Run docker without providing an absolute path:
docker run -it -p 11443:11443 -p 12443:12443 -v pgdata:/var/lib/postgresql/data -v config:/defaults --name standalone apperyio/api-express-standalone
  1. Run admin node:
docker exec -it standalone bash "./admin_start.sh"
  1. Review current configs: 
docker exec -it standalone bash
cd ..
cd defaults
cat apiexpress.properties
  1. Update configs:

If it is needed to update only apiexpress.properties file vim editor can be used.

apt-get update
apt-get install vim
vim apiexpress.properties

Property and other configuration files can be modified in any editor and then copied into docker container using this command:

docker cp apiexpress.properties standalone:/defaults/apiexpress.properties

In the same way, files can be copied from docker container:

docker cp standalone:/defaults/apiexpress.properties apiexpress.properties

Security

API Express uses Apache SHIRO (https://shiro.apache.org/) library for security purposes.

By default, API Express uses simple properties shiro.ini file with predefined users for authentication:

[users]
admin = admin,admin
[email protected] = test02
[roles]
admin = *
[email protected] = *

To override default users, update the shiro.ini file and restart admin server.

Example of configuring shiro.ini using LDAP:

ldapRealm = org.apache.shiro.realm.ldap.DefaultLdapRealm
ldapRealm.userDnTemplate = uid={0},dc=example,dc=com
ldapRealm.contextFactory.url = ldap://ldap.forumsys.com:389
securityManager.realms = $ldapRealm

Example of configuring shiro.ini using MySQL:

jdbcRealm = org.apache.shiro.realm.jdbc.JdbcRealm
jdbcRealm.permissionsLookupEnabled = false
jdbcRealm.authenticationQuery = SELECT password FROM users WHERE username = ?
jdbcRealm.userRolesQuery = SELECT role_name FROM user_roles WHERE username = ?

ds = com.mysql.jdbc.jdbc2.optional.MysqlDataSource
ds.serverName = change_it
ds.user = change_it
ds.password = change_it
ds.databaseName = change_it
 

jdbcRealm.dataSource = $ds

securityManager.realms = $jdbcRealm

Check the official Apache SHIRO site (https://shiro.apache.org/) about the other options of security configurations.

SSL configuration

By default, API Express is shipped with self-signed SSL certificate which is suited for development stage but cannot be used for production purposes.

Providing custom SSL certificate

How to install openssl on windows

  1. Get a domain and point it on your machine IP address.
  2. Generate CSR.

For example, you can do it by using Openssl tool on Unix:

openssl req -new -newkey rsa:2048 -nodes -keyout <your_domain>.key -out <your_domain>.csr

on Windows (Since windows is supplied without OpenSSL tool you can download it for example from here https://slproweb.com/products/Win32OpenSSL.html):

openssl genrsa -out <your_domain>.key 2048
openssl req -new -key <your_domain>.key -out <your_domain>.csr

Common name is your domain name

  1. Get SSL certificate.

For testing purposes, it is possible to get a free SSL certificate which is valid 3 months

(Example of resource for generating free certificate https://www.ssl.com/certificates/free/ )

  1. Generate .p12 or .pkf certificate.

For example, you can do it by using the OpenSSL tool:

openssl pkcs12 -export -in <your_domain>.crt -inkey <your_domain>.key -out <your_domain>.p12 -name default -CAfile <your_provider_bundle>.crt -caname root

<your_provider_bundle>.crt is certificate from your provider

  1. Generate keystore.

API Express is running on JBOSS application server and to work with your SSL certificate it is required to generate keystore, you can do it using Keytool which is supplied with JDK.

for Unix:

keytool -importkeystore -deststorepass <your_storepass> -destkeypass <your_keypass> -destkeystore <your_domain>.jks -srckeystore <your_domain>.p12 -srcstoretype PKCS12 -srcstorepass <your_password_used_in_csr> -alias localhost

For Windows:

keytool -importkeystore -deststorepass <your_storepass> -destkeypass <your_keypass> -destkeystore <your_domain>.jks -srckeystore <your_domain>.p12 -srcstoretype PKCS12 -srcstorepass <your_password_used_in_csr>

Note that the alias name will be shown in the console.

For getting alias name from keystore, the following command can be used: 

keytool -list -keystore server.keystore
  1. Run container Docker with an additional attribute:
-v <folder_on_your_computer>:/defaults

On a Windows machine, you can have issues with the mapping folder and in this case, you can copy files from defaults folder of container modified them and copy back.

Copying file from the container:

docker cp standalone:/defaults/file_name file_name

Copying file to the container:

docker cp file_name standalone:/defaults/file_name
  1. Init default files with the command:
docker exec -it standalone bash "./init_properties.sh"

  1. Put server.keystore into <folder_on_your_computer>.

  2. Open apiexpress.properties and make changes to properties:

io.appery.apiexpress.standalone.aex.domain=<your_domain>:12443
wildfly.keystore.password=<your_storepass>
wildfly.key.password=<your_keypass>
wildfly.key.alias=localhost

  1. Run the Admin server as usual.

  2. Don't forget to set up port routing on your router.

Updated almost 2 years ago