PingGateway 2024.9

Next steps

This section describes some basic options to help you with PingGateway. For information about other installation options, refer to the Installation guide.

Add a base configuration file

The entry point for requests coming in to PingGateway is a JSON-encoded configuration file, expected by default at:

  • Linux

  • Windows

$HOME/.openig/config/config.json
%appdata%\OpenIG\config\config.json

The base configuration file initializes a heap of objects and provides the main handler to receive incoming requests. Configuration in the file is inherited by all applicable objects in the configuration.

At startup, if PingGateway doesn’t find a base configuration file, it provides a default version given in Default configuration. The default looks for routes in:

  • Linux

  • Windows

$HOME/.openig/config/routes
%appdata%\OpenIG\config\routes

Consider adding a custom config.json for these reasons:

  • To prevent using the default config.json, whose configuration might not be appropriate in your deployment.

  • To define an object once in config.json, and then use it multiple times in your configuration.

After adding or editing config.json, stop and restart PingGateway to bring the changes into effect.

For more information, refer to GatewayHttpApplication (config.json ), Heap objects, and Router

Add a base configuration for PingGateway

  1. Add the following file to PingGateway:

    • Linux

    • Windows

    $HOME/.openig/config/config.json
    %appdata%\OpenIG\config\config.json
    {
  "handler": {
    "type": "Router",
    "name": "_router",
    "baseURI": "http://app.example.com:8081",
    "capture": "all"
  },
  "heap": [
    {
      "name": "JwtSession",
      "type": "JwtSession"
    },
    {
      "name": "capture",
      "type": "CaptureDecorator",
      "config": {
        "captureEntity": true,
        "_captureContext": true
      }
    }
  ]
}

    Notice the following features of the file:

    • The handler contains a main router named _router. When PingGateway receives an incoming request, _router routes the request to the first route in the configuration whose condition is satisfied.

    • The baseURI changes the request URI to point the request to the sample application.

    • The capture captures the body of the HTTP request and response.

    • The JwtSession object in the heap can be used in routes to store the session information as JSON Web Tokens (JWT) in a cookie. For more information, refer to JwtSession.

  2. Stop and restart PingGateway.

  3. Check that the route system log includes a message that the file is loaded into the config:

    INFO  o.f.openig.web.Initializer - Reading the configuration from ...config.json

Add a default route

When there are multiple routes in the PingGateway configuration, they are ordered lexicographically, by route name. For example, 01-static.json is ordered before zz-default.json.

When PingGateway processes a request, the request traverses the routes in the configuration. If the request matches the condition for 01-static.json it is processed by that route. Otherwise, it passes to the next route in the configuration. If a route has no condition, it can process any request.

A default route is the last route in a configuration to which a request is routed. If a request matches no other route in the configuration, it is processed by the default route.

Add a default route to prevent errors described in No handler to dispatch to.

  1. Add the following route to PingGateway:

    • Linux

    • Windows

    $HOME/.openig/config/routes/zz-default.json
    %appdata%\OpenIG\config\routes\zz-default.json
    {
  "handler": "ReverseProxyHandler"
}

    Notice the following features of the route:

    • The route name starts with zz, so it is the last route that is loaded into the configuration.

    • There is no condition property, so the route processes all requests.

    • The route calls a ReverseProxyHandler with the default configuration, which proxies the request to the application and returns the response, without changing either the request or the response.

  2. Check that the route system log includes a message that the file is loaded into the config:

    INFO  o.f.o.handler.router.RouterHandler - Loaded the route with id
'zz-default' registered with the name 'zz-default'

Switch from production mode to development mode

To prevent unwanted changes to the configuration, PingGateway is by default in production mode after installation. For a description of the modes and information about switching between modes, refer to Operating modes.

Use PingGateway Studio

PingGateway Studio is a user interface to help you build and deploy your PingGateway configuration. For more information, refer to the Studio guide.