Standalone Installation

The Standalone distribution packages AS2 Gateway (web interface, AS2 processing engine and, optionally, an embedded database) as a single self-contained unit, that can be run on any Java-compatible environment - a bare-metal desktop, a server, or a VM.

1 System Requirements

Compute: 2-4 GB of RAM and 2-4 CPU cores, at minimum
Network: a stable network link, to communicate with partner AS2 systems
Database: a relational database, to store AS2 file/message content and metadata AS2 Gateway supports several common DBMS vendors, and has been tested extensively against MySQL, PostgreSQL and SQL Server; you may either provision a new database instance, or reuse an already available one
Disk space: the VM (or the database server, if hosted separately) needs disk capacity to hold retained message content, roughly estimated as:
3 * {size of outgoing files, retained long-term} + 2 * {size of incoming files, retained long-term}
Java: install OpenJDK (version 8 or above; 17 or 11 is recommended; the latest available patch version is fine)

Note: The default on-premise installation does not include message statistics (the home ‘dashboard’ shown when logging into the SaaS platform). Contact us if this is a requirement for your deployment.

2 Default Installation

By default, the Standalone distribution runs against a bundled, embedded database, requiring no external dependencies to get started.

Extract the distributed .zip archive to a suitable directory on the target machine. Let’s call this directory $AS2_HOME.
Run $AS2_HOME/bin/as2gx.sh (or as2gx.bat on Windows).
When prompted on the terminal, enter these details:
- Your admin email address - used as the log-in username (a password will be auto-generated)
- Your organization domain name - used as your account name
- The public IP and hostname of your AS2 receiving endpoint
- Your client key - provided to you at the time of purchase/registration
The application will initialize its database and bootstrap itself, then display a URL to access the web dashboard.
Log in to the dashboard using the user email and password displayed alongside the URL.

Below is a sample installation output:

Starting AS2 Gateway...
Using X_HOME:  installation-path\

Let us set up your new AS2 Gateway account.

Please answer these few questions:

Please enter your email address (for your new account): your.email@acme.com

Using super.user.email: your.email@acme.com

We will auto-generate a password for you.

Please enter your organization domain/host name: acme.com

Using super.user.org.domain: acme.com

Please enter host name for your AS2 receiving endpoint (press Enter for default: acme.com): as2.acme.com

Using host.name: as2.acme.com

Please enter static IP address of your AS2 receiving endpoint: 20.10.30.40

Using host.ip: 20.10.30.40

Thank you! Set-up is starting now...

Client Key file conf\license\client.key.properties not found!

Please enter the Client Key provided by the vendor: xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx

Using Client Key: xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx

************************************************************************************************

Welcome!

You are running AS2 Gateway v2.3.14-standalone from Aayu Technologies.

Java: 12

If this is your first run, we may need a few extra minutes to prepare the environment for you.
When we are done, we will show you how you can log in and start using the platform.

While you wait, check out our product documentation:
https://aayutechnologies.com/docs/product/as2-gateway/

************************************************************************************************

Starting up, please wait...

************************************************************************************************

Success!

Your AS2 Gateway installation is now ready to use.

Please open the following URL in your browser:

http://as2.acme.com:8080

Your initial log-in credentials are as follows:

Username:
your.email@acme.com

Password:
xxxxxxxxxxxx

To learn how to use the platform, please check our product documentation:
https://aayutechnologies.com/docs/product/as2-gateway/

You can also reach us anytime, via email:
support@as2gateway.com

************************************************************************************************

Log in with your browser to get started.

If you encounter any errors, copy the relevant description text (usually between the ***...*** lines) and contact support by attaching it.

3 Common Customization Scenarios

AS2 Gateway Standalone is based on Java SE, the Spring Framework, and Spring Boot; standard Spring configuration-override mechanisms (environment variables, Java system properties, .properties files, etc.) are supported for any of the customizations below.

3.1 Configuring Email Notification Delivery

By default, the application does not ship with email delivery (SMTP configurations).

To enable emailing:

Obtain SMTP credentials for an email server/service (e.g. AWS SES, Gmail, Sendgrid, etc.).

Enter them in conf/default.properties, in the following format:

# SMTP email server hostname
spring.mail.host=email-smtp.us-east-1.amazonaws.com
# port number to connect on the email server
spring.mail.port=587
# 'From' address (MAILFROM) to use for sending emails out; may need to be authorized before use, e.g. in case of SES
spring.mail.from=noreply@as2gateway.com
# name to use (along with the 'From' address) for sending emails out
spring.mail.fromName=AS2 Gateway
# SMTP server log-in username
spring.mail.username=
# SMTP server log-in password
spring.mail.password=

Restart the application.
Trigger a test email (e.g. via the Share Partner Configuration action).
After delivery is confirmed, you can enable email notifications more broadly.

3.2 Using an External Database

The Standalone distribution runs on an embedded database by default; to use an external database instead, you need to point the application at it via a standard JDBC URL, as described below for some supported DBMSs.

3.2.1 PostgreSQL

Create the database, application user, and grant the necessary privileges (e.g. via psql):

-- create database
CREATE DATABASE as2gx;

-- create user
CREATE USER as2gx WITH PASSWORD 'mysecretpassword';

-- grant privileges
GRANT ALL PRIVILEGES ON DATABASE as2gx TO as2gx;

-- make as2gx the database owner
ALTER DATABASE as2gx OWNER TO as2gx;

Log in to psql again as the as2gx user, and verify access by creating a test table:
```
CREATE TABLE dummy (id INT);

-- verify:
\dt
```
Take a backup copy of the existing conf/default.properties file.
Download the PostgreSQL JDBC driver (postgresql-42.x.x.jar), and copy it into $AS2_HOME/lib/custom/.

Update conf/default.properties with the following values:

database.url=jdbc:postgresql://{DB host}:{DB port, default 5432}/{new DB name}
database.username=as2gx
database.password=mysecretpassword

database.driverClass=org.postgresql.Driver
database.validationQuery=SELECT 1
database.dialect=org.hibernate.dialect.PostgreSQLDialect

Restart the application.

3.2.2 MySQL

Prepare an empty MySQL database, along with a password-based user that has full access to that database.
Download the MySQL Connector/J JDBC driver, and place it into $AS2_HOME/lib/custom/.

Update $AS2_HOME/conf/default.properties, replacing the {placeholder} values below with the relevant details from your MySQL setup:

database.url=jdbc:mysql://{MySQL server host}:{MySQL server port, default 3306}/{new DB name}?useSSL=false
database.username={MySQL DB user name}
database.password={MySQL DB user password}

database.driverClass=com.mysql.cj.jdbc.Driver
database.validationQuery=SELECT 1 FROM DUAL
database.dialect=org.hibernate.dialect.MySQL8Dialect

Restart the application.

3.3 Using Local-File Integration

By default, when you navigate to the local-file integration page (e.g. http://localhost:4200/integration/local-file when running locally), you will be prompted to enable file-polling.

To enable this manually instead:

Set the following in conf/default.properties:

file.polling.enabled=true

# parent folder under which the folder structure for file saving/reading, will be created; change if required
file.polling.root.path=./data/file-store

Restart the application.
Revisit the local-file integration page, and enter a name for the root folder.
Follow the SFTP folder-structure documentation to set up file send and receive (local-file integration uses the same folder-structure conventions as SFTP).

3.4 Sending/Receiving Large Files

To raise the maximum file/message size limits,

Adjust the following in conf/default.properties:

For outgoing messages, the max outgoing file size (in bytes):
```
outbound.max.size=314572800          # e.g. 300MB in bytes
```

For incoming messages:

ingress.max.payload.size=314572800   # e.g. 300MB in bytes
http.receive.socket.timeout=120000   # e.g. 5 minutes, if large files need more time to transfer
response.timeout=130000              # should be set to (http.receive.socket.timeout + 10000)

Restart the application.
Review and increase the partner-level Transmission Timeout for any partners exchanging large files, so that outgoing transmissions are not prematurely marked as failed.

3.5 Setting Up to Run as a Windows Service

You can use NSSM (the Non-Sucking Service Manager) to run AS2 Gateway as a Windows service.

Install NSSM.
Open PowerShell as Administrator.

Create the service (this creates it in a stopped state):

<nssm-exe-path-prefix>\nssm.exe install AS2Gateway <as2gx-installation-folder>\bin\as2gx.bat

Start the service:
```
<nssm-exe-path-prefix>\nssm.exe start AS2Gateway
```
Once started, you can access the application through your browser as usual.

Verify the service status:

Get-WmiObject win32_service | Where-Object {$_.PathName -like '*nssm*'} | Select-Object Name, DisplayName, State, PathName

4 Configuration References

Settings can be applied via environment variables (replacing dots . on property key with underscores _), or added to conf/application.properties or conf/default.properties. Standalone release merges backend and broker services, so you can configure each setting on just one of above two files.

Changes take effect after application restart.