Appery.io

The Appery.io Developer Hub

Welcome to the Apperyio developer hub. You'll find comprehensive guides and documentation to help you start working with apperyio as quickly as possible, as well as support if you get stuck. Let's jump right in!

Documentation    Latest Updates

Standalone Version

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

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/
Don't forget to look 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 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 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 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 standalone Docker container
docker stop standalone
  1. Remove standalone Docker container
docker rm standalone
  1. Pull the latest API Express standalone docker image
docker pull apperyio/api-express-standalone 

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 Windows machine it is possible to use following workaround

  1. Run docker without providing 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 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
test02@mail.com = test02
[roles]
admin = *
test02@mail.com = *

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 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 free ssl certificate which is valid 3 months

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

  2. Generate .p12 or .pkf certificate

For example, you can do it by using 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 witch 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>

Pay attention than alias name will be shown in console.

For getting alias name from keystore 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 windows machine you can have issues with mapping folder and in this case you can copy files from defaults folder of container modified them and copy back

Copying file from container

docker cp standalone:/defaults/file_name file_name

Copying file to 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 Admin server as usual

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

Standalone Version