Installation & configuration

Introduction

Although Amforeas, as any Java application, can run in any operating system, this guide focuses on Linux as Amforeas only provides a startup script for Linux. If anyone wants to contribute with an executable for Windows or MacOS, you're welcome.

Dependencies

You'll need the latest Java 11 JRE or install the one with your distribution.

Installation from Distribution

Installation is pretty simple. Just download the latest distribution ZIP file and unzip it wherever you want.

Configuration

Amforeas is configured by setting properties this way:

• Default properties file: amforeas.properties file in ${AMFOREAS_HOME}/etc/amforeas.properties
• Custom properties file: -Damforeas.properties.file=myproperties.properties
• Java options: -Damforeas.server.http.port=8080
• Environment variables: AMFOREAS_SERVER_HTTP_PORT=8080

This means an environment variable will override all of the others.

For all configuration options, check the reference file

Configure a single MySQL database:

amforeas.database.list=my_sql_alias
amforeas.my_sql_alias.jdbc.driver=MySQL
amforeas.my_sql_alias.jdbc.username=foo
amforeas.my_sql_alias.jdbc.password=pass4foo
amforeas.my_sql_alias.jdbc.database=foo_schema
amforeas.my_sql_alias.jdbc.host=mysql-server-01
amforeas.my_sql_alias.jdbc.port=3306

# You can use a custom JDBC URL for advanced connection options
amforeas.my_sql_alias.jdbc.url=jdbc:mysql://mysql-server-01:3306/foo_schema&ssl=true

This will publish this alias and now you can:

$curl "http://localhost:8080/amforeas/my_sql_alias"

Make sure the user has the right permissions.

Multiple databases/schemas

You can register different databases/schemas and amforeas will publish them. In this case, two different databases and schemas:

amforeas.database.list=foo, bar

amforeas.foo.jdbc.driver=MySQL
amforeas.foo.jdbc.username=foo
amforeas.foo.jdbc.password=pass4foo
amforeas.foo.jdbc.url=jdbc:mysql://mysql-server-01:3306/foo_schema

amforeas.bar.jdbc.driver=PostgreSQL
amforeas.bar.jdbc.username=bar
amforeas.bar.jdbc.password=pass4bar
amforeas.bar.jdbc.url=jdbc:postgresql://pgsql-server-01:5432/my_database?currentSchema=my_schema&ssl=true

$curl "http://localhost:8080/amforeas/foo"
$curl "http://localhost:8080/amforeas/bar"

JDBC Drivers

We can't distribute every JDBC Driver out there, so you'll need to download the latest for your RDBMS.

Once you've downloaded the driver copy the .jar file to ${AMFOREAS_HOME}/lib/

Start it up

Go to ${AMFOREAS_HOME} and execute the script

$./amforeas.sh start
or
$ export AMFOREAS_SERVER_HTTP_PORT=8080 ; ./amforeas.sh start
or
$./amforeas.sh start [myproperties.properties]

Docker/Podman

To run Amforeas in a docker/podman container we provide a Dockerfile and instructions in it.