Skip to content
Architecture

Advanced Setup

Advanced Java Configurations

Running AMI on Java 18

If you were to run AMI on Java 18 and ever come across any Java exceptions, please add something like this to your start.sh:

1
2
3
4
      -XX:+PrintGCDetails \
      -Xloggc:log/gc.log --add-opens java.base/java.lang=ALL-UNNAMED --add-opens java.base/java.util=ALL-UNNAMED --add-opens java.base/java.text=ALL-UNNAMED --add-opens java.base/sun.net=ALL-UNNAMED --add-opens java.management/sun.management=ALL-UNNAMED --add-opens java.base/sun.security.action=ALL-UNNAMED --add-opens java.desktop/com.sun.imageio.plugins.png=ALL-UNNAMED\
       ${JAVA_OPTIONS}\ 
       $* -classpath $CP $APPCLASS >> log/stdout.log 2> log/stderr.log &

Using Java G1GC garbage collector

Java G1GC is a garbage collector that is designed to improve the performance and scalability of Java applications by reducing pause times and improving throughput. Here is a detailed instruction on how you can set this up on ami:

  1. From the root directory where you installed AMI_One, Open /amione/scripts/start.sh

  2. Remove the following properties:

1
2
    -XX:+UseConcMarkSweepGC
    -XX:+PrintGCTimeStamps
  1. And add this property.
1
    -XX:+UseG1GC

Manual Upgrade of AMI using .tar.gz file

1. unzip and extract the files.

  1. Move the extracted files to the project directory where the old ami folder resides and overwrite it.

For linux machines, you can use the following command to do so:

1
**tar -xf ami_unix_version<file_name>.tar.gz -c <your target directory>
Note: This command is NOT REVERSIBLE and will overwrite your existing ami folder with the new one. You may want to backup your 3forge AMI project before proceeding to make rollback easier especially for a prod environment. This overwriting process includes the overwrite of the following files (subject to change):
(1). amione/lib
(2). amione/data
(3). amione/scripts

Note 1 : For the scripts directory, make sure to rename your start script if it gets modified
Note 2: These following properties files will be updated: build.properties, defaults.properties, root.properties, speedlogger.propertie, (Windows) AMI_One.vmoptions
Note 3: You can use tar -tvf to preview the contents of a zip.

Manual Upgrade of AMI using .sh file

Simply run the installer and select the option to update the existing installation.

Instructions for Secure Socket

  • You'll need to start by creating the certificates. To do this, keytool must be in your PATH.

  • First we create a server.jks file and a server.cer file which we will keep with the server. Note, replace serverpass with a password

1
2
3
keytool -genkeypair -deststoretype pkcs12 -keyalg RSA -alias 3forge_server -keystore server.jks -validity 1000 -keysize 2048 -keypass serverpass -storepass serverpass -dname "cn=3Forge Client"

keytool -export -alias 3forge_server -storepass serverpass -file server.cer -storetype pkcs12 -keystore server.jks
  • Now lets create a client.jks file using the server's certificate, if you have multiple clients you should run this for each client (such that each time the client.jks file is unique for that client). Note, replace clientpass with a password
1
2
3
keytool -genkey -deststoretype pkcs12  -alias 3forge_client -keyalg RSA -keypass clientpass -storepass clientpass -keystore client.jks  -dname "cn=3Forge Client"

keytool -import -v -trustcacerts -alias 3forge_server -file server.cer -keystore client.jks -keypass clientpass -storepass clientpass -noprompt
  • To configure the server, copy the server.jks file to the server, and add the following properties to your local.properties of AMI:
1
2
ami.port.keystore.file=/path/to/server.jks
ami.port.keystore.password=serverpass
  • To configure the client, copy the client.jks file to the client and instead of calling the function AmiClient::start(host, port, loginId, options) call:
1
2
3
AmiClient client = new AmiClient();
...
client.start(host, port, loginId, options, new File("/path/to/client.jks"), "clientpass");

Configuring Multiple Instances on a Single Machine

Multiple instances of AMI can be run on the same machine. First, each entry should have it's own root directory. Next each additional instance must be configured to use different server ports. (Two processes can not have conflicting server ports). Below is a list of the server ports that need to be configured:

  • You must always replace the following default port with a new, unique port (or use -1 to disable the console): 
    1
    f1.console.port=3285
  • If running the center, you must replace the following default ports with new, unique ports: 
    1
2
3
    ami.center.port=3270
ami.db.jdbc.port=3280
ami.db.console.port=3290
  • If running the relay, you must replace the following default port with a new, unique port: 
    1
    ami.port=3289
  • If running the web with secure https socket, you must replace the following default port with new, unique ports: 
    1
    https.port=33332
  • If running the web with non-secure http socket, you must replace the following default port with new, unique ports: 
    1
    http.port=33332

Running Components Independently

The same AMI binary is configured to run as a center, relay, web or a combination of the three. Add one of the following configuration blocks to your amione/config/local.properties to control what is run. If the local.properties file does not exist, please create it. Note, that port 3270 is the default port that the center listens on and that the web/relay connect to, but can be changed. Also, the web server never connects to the relay directly (they both connect to the center).

Finally, keep in mind that the center starts up the server port and multiple clients (relays/web) can connect to a single center.

Default: Run the center,relay,web 

1
2
3
ami.components=relay,center,web
ami.center.port=3270
ami.center.host=localhost

Run the center 

1
2
ami.components=center
ami.center.port=3270

Run the relay 

1
2
3
ami.components=relay
ami.center.port=3270
ami.center.host=hostname.running.center

Run the web 

1
2
3
ami.components=web
ami.center.port=3270
ami.center.host=hostname.running.center

Run the center,web 

1
2
3
ami.components=center,web
ami.center.port=3270
ami.center.host=localhost

Run the center,relay 

1
2
3
ami.components=center,relay
ami.center.port=3270
ami.center.host=localhost

Run the web,relay 

1
2
3
ami.components=web,relay
ami.center.port=3270
ami.center.host=hostname.running.center

Run the relay connected to multiple centers 

1
2
3
4
ami.components=relay
ami.centers=center1=hostname.running.center1:3270,center2=hostname.running.center2:3270,center3=hostname.running.center3:3270
ami.center.port=
ami.center.host=

Run the web connected to multiple centers 

1
2
3
4
ami.components=web
ami.centers=center1=hostname.running.center1:3270,center2=hostname.running.center2:3270,center3=hostname.running.center3:3270
ami.center.port=
ami.center.host=

Configuring Web, Relay and Center Ports

This guide describes what ports each AMI component listens or connects to.

Console Port

f1.console.port : default 3285 (Listens)

Admin console port all components listens on, to prevent port conflict you may need to change this.

AMI Center

ami.center.port : default 3270 (Listens)

Sets the port of the primary instance of ami center, for more connections from other AMI Web and Relay instances.

Also sets the connecting port of relay & web components to this center if configured and launched together.

ami.db.console.port : default 3290 (Listens)

The port for connecting via telnet command line interface

ami.db.jdbc.port : default 3280 (Listens)

The port for connecting to AMI via the AMI JDBC driver

AMI Relay

ami.port : default 3289 (Listens)

Sets the port that applications connect to on the Relay's host machine. See AMI Realtime Messages for the messages format AMI expects

ami.center.port : default 3270 (Connects)

ami.center.host (e.g. localhost)

For relay components running separately from the center, to be configured with ami.center.host

Note: the relay can connect to multiple centers, with a comma-delimited list entry e.g.: ami.centers=center1=host.running.center1:3270,center2=host.running.center2:3270,center3=host.running.center3:3270

AMI Web

http.port : default 33332 (Listens)

Sets the port that web browsers use to connect to AMI Web (Default 33332)

https.port : default 33333, disabled (Listens)

Sets the port that web browsers use to connect securely to AMI Web.

https.keystore.file : the path to the key store file generated using java's keytool that will be used for secure web connections.

ami.center.port : default 3270 (Connects)

ami.center.host (e.g. localhost)

For web components running separately from the center, to be configured with ami.center.host

Web Manager

ami.webmanager.port : default 3271, disabled (Listens)

Optional location for where to access webmanager, used for remotely loading files.

Web Balancer

ami.webbalancer.http.port : default 33330 (Listens)

Optional, the http port to listen for insecure connections on. If not specified, http is not available.

Configure AMI properties from environment variables

Another alternative solution to configuring AMI properties is to use system variables.
For example, instead of in "local.properties", where you set:

1
ami.db.console.port=3291
You can set this up via environment variables by adding property_<AMI Property Name>=<value> (case-sensitive)

This will overwrite the existing property defined in local.properties and apply globally on all AMI instances running on the current machine.

Running AMI with Docker

AMI can be easily configured for use with docker using the following recommended folder configuration:

Folder Contents
./ami Unix installation of ami (ami/amione/...)
./docker Dockerfile provided below
./scripts start.sh script provided below

Sample Dockerfile

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
FROM ubuntu:20.04

RUN apt-get update
RUN apt-get install -y default-jre

COPY ami ami
COPY scripts scripts

EXPOSE 3289
EXPOSE 3290
EXPOSE 33332

CMD ["bash", "./scripts/start.sh"]

Sample start.sh

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
#!/bin/bash

SCRIPTDIR=$(dirname "$0")

mkdir -p $SCRIPTDIR/../ami/amione/resources/

echo 'Starting AMI...'
AMI_EXECUTABLE=$SCRIPTDIR/../ami/amione/scripts/start.sh
sed -i -e 's/\r$//' $AMI_EXECUTABLE
sed -i -e 's/-XX:+PrintGCTimeStamps//g' $AMI_EXECUTABLE
chmod +x $AMI_EXECUTABLE
$AMI_EXECUTABLE > exec.out

echo 'Checking for errors during launch...'
if grep -q error exec.out; then
    echo 'An Error Has Occured While Starting AMI, Dumping Error...'
    error_log=$(grep -o "[^ ]*/log/" exec.out)
    echo ''
    more $error_log/stderr.log
    echo ''
    rm exec.out
    echo 'Terminating Docker Start Script'
    exit 1
else
    rm exec.out
    echo 'AMI Successfully launched'
fi

echo 'Completed Start Script'

tail -f /dev/null

To build the image:

1
docker build -t ami -f ./docker/Dockerfile .

To run the image (the use of detached mode is optional):

1
docker run -d -p 33332:33332 ami