AS2NG

Overview

Development Guide

Table of Contents

• Development Guide
  • Prerequisites
  • Code Organization
  • Starting a Dev Environment
  • Running Migrations
  • Updating JOOQ Entities
  • Formatting source

Prerequisites

1. Java 11 or higher (AdoptOpenJDK, Zulu Community or OpenJDK)
2. Docker
3. Docker Compose
4. direnv
5. Authenticated against the docker.pkg.github.com/freight-trust/as2ng container registry

Code Organization

The codebase is organized as follows:

├── bin                 # various utility scripts
│   ├── cli             # calls the cli module for running admin tasks on a local environment
│   ├── flyway          # run database migrations
│   ├── initialize      # initialize a local development environment
│   ├── mc              # utility script for local minio
│   └── vault           # utility script for local vault
├── docker
│   ├── as2-lib         # containerized version of as2-lib server for use in integration testing
│   ├── cli             # containerized version of the as2ng cli
│   ├── server          # containerized version of the main as2 exchange server
│   └── vault           # customised local vault build for development
├── docker-compose.yml  # docker compose based services for local development
├── docker-utils        # git submodule with utility scripts for working with docker
├── modules
│   ├── as2-lib         # simple project for pulling together and building the as2-lib dependencies
│   ├── cli             # standalone cli for performing config/admin tasks relating to the server
│   ├── common          # shared common code and configuration
│   ├── crypto          # cryptography related code
│   ├── persistence     # persistence related code such as postgres and s3
│   └── server          # main as2 exchange server code based on vert.x

Starting a Dev Environment

Run the following commands from the root directory of the repository:

$ git submodule update --init --recursive       # only required on initial checkout
$ direnv allow                                  # as and when prompted to do so

$ docker-compose up -d                          # starts the various services such as vault, minio, postgres etc
$ docker-compose tail -f                        # watch the logs for successful services startup
$ bin/initialize                                # this will generate some initial state

The initialize script will do the following:

• Enable the Public Key Infrastructure (PKI) secrets engine within Vault and generate an initial certificate authority
• Apply the database migrations located in modules/persistence/src/main/resources/db/migration to the Postgres database
• Create a S3 bucket within the Minio service as configured by the AS2NG_S3_BUCKET environment variable
• Generate some encryption key pairs
• Generate some example trading partners
• Generate some example trading channels
• Export some keystores based on the configured trading channels and partners for use within local testing as2-lib based servers

After the initialize script has successfully completed run the following:

$ ./gradlew :modules:as2-lib:runOpenAS2A        # as2-lib based test server configured with one of the exported keystores and trading channels
$ ./gradlew :modules:as2-lib:runOpenAS2B        # as2-lib based test server configured with one of the exported keystores and trading channels
$ ./gradlew :modules:server:runAS2Server        # starts the vert.x based as2 exchange server

You can now send a test message from OpenAS2A to OpenAS2B by running the following:

$ echo "Hello world" > modules/as2-lib/data/text/OpenAS2A/toOpenAS2B/test.txt

Running Migrations

After making changes to the database structure you can run the migrations against the local Postgres database as follows:

$ ./gradlew :persistence:flywayMigrate

To drop all data and structure in the DB you can use:

$ ./gradlew :persistence:flywayClean

Or you can use the utility script:

$ bin/flyway migrate
$ bin/flyway clean

For more information about the migration framework please consult the official docs.

Updating JOOQ Entities

If you have added db migrations and applied them, you will need to regenerate the jooq entities for interacting with the db. First ensure that:

1. Postgres is running.
2. Migrations have been applied correctly.
3. Manually delete the modules/persistence/src/main/java/com/freighttrust/jooq folder.

Then in the terminal run:

$ ./gradlew :persistence:jooq-codegen-primary

For more information about JOOQ please consult the official docs.

Formatting source

To format the code you can run:

$ ./gradlew ktlintFormat

Usage

Configuration

Server

System Property	Environment Variable	Description	Default
-Dhttp.host	AS2NG_HTTP_HOST	Hostname that the server is reachable from	localhost
-Dhttp.port	AS2NG_HTTP_PORT	Port that the server is reachable from	8080
-Dhttp.https	AS2NG_HTTPS_ENABLED	Whether or not https is enabled	false

Postgres

System Property	Environment Variable	Description	Default
-Dpostgres.jdbcUrl	AS2NG_JDBC_URL	JDBC style connection url	jdbc:postgresql://localhost/as2ng?user=as2ng&password=as2ng
-Dpostgres.maximumPoolSize	AS2NG_JDBC_CONNECTION_LIMIT	Maxmimum number of database connections to maintain in the connection pool	30

S3 Compliant Storage

System Property	Environment Variable	Description	Default
-Ds3.bucket	AS2NG_S3_BUCKET	Bucket to use when storing http request bodies	as2ng
-Ds3.endpoint.serviceEndpoint	AS2NG_S3_SERVICE_ENDPOINT	Base service endpoint to use when making requests	http://localhost:9000
-Ds3.endpoint.signingRegion	AS2NG_S3_SIGNING_REGION	Signing region to use when making requests	us-east-1
-Ds3.endpoint.accessKey	AS2NG_S3_ACCESS_KEY	Access key for authentication	minio
-Ds3.endpoint.secretKey	AS2NG_S3_SECRET_KEY	Secret key for authentication	12345678

License

as2ng - SSPL-1.0

as2ng documentation - Apache-2.0

(C) 2020-2021 FreightTrust and Clearing Corporation - All Rights Reserved