app.yaml

This section explains how to set up the app.yaml configuration file, which is crucial for the basic startup process as it contains essential settings needed to run aqilink successfully, such as the license key, tracing and logging. While most parameters are optional and adjustable based on your needs, some are critical for proper operation.

Parameter Overview

The table highlights all available top-level properties in the app.yaml that can be used to set up aqilink. For details, refer to the related property explanations in the next section.

Parameter	Mandatory	Type	Default	Description
aqilinkLicense	Yes	string		Containts the license key to run aqilink. Refer to License Key below.
logging	No	Object		Specify the logging behavior, including log output, format, and other properties like log levels for monitoring and troubleshooting. Refer to Logging below.
metrics	No	Object		Collect metrics for Prometheus, the open-source monitoring and alerting toolkit. Refer to Metrics below.
port	No	number	3000	Allows overriding the default port of the SAP HTTP Content Server. Refer to Port below.
tracing	No	Object		Enable tracing with external tools that support the OpenTelemetry Protocol (OTLP) and Zipkin. Refer to Tracing below.
tls	No	Object		Enables the SAP HTTP Content Server endpoint to operate over TLS (Transport Layer Security), securing the communication by encrypting data transferred between the client and the server. Refer to Transport Layer Security (TLS) below.
privateKeyPath	No	string		The use of encrypted passwords necessitates a private key. This parameter points to the key within the container. Refer to Password Encryption below.

Parameter in Detail

The parameter from the table above explained in detail.

License Key

The most important setting in the app.yaml is the license key. This key must be stored under the aqilinkLicense property. If a license key is not provided, or if the key is invalid or expired, aqilink will operate in read-only mode. In read-only mode, the application will not start at all. If the license expires while the app is running, storing documents from the SAP system to the archive will no longer be possible.

Example

aqilinkLicense: 12345-67890-09876-54321

Logging

Logging is essential for gaining visibility into the application's operation, enabling effective diagnosis of issues and monitoring of performance. This section explains how to configure and control logging behavior and log output in aqilink.

Example

logging:
  level: info
  caller: false
  structured: true
  timeFormat: 2006-01-02T15:04:05Z07:00
  fieldName: 
    timestamp: time
    level: level
    caller: caller
    message: message
    error: error

Below is a detailed explanation of all the parameters for the logging section used in the example above.

Parameter	Mandatory	Type	Default	Description
level	No	string	info	Specify the log level to control the granularity of information captured in the logs. Available log levels: trace debug info (default) warn error fatal panic disabled (used to disable the logging)
caller	No	boolean	false	This logs the affected source, providing a detailed record that can help in troubleshooting and understanding the context of operations.
structured	No	boolean	true	Formats the log output using JSON syntax, which enhances readability and facilitates easier integration with log management tools.
timeFormat	No	string	2006-01-02T15:04:05Z07:00	Specifies the format (ISO 8601) used to display the timestamp in log outputs. Refer to Timeformat Reference.
fieldname	No	Object		Object to override default names. Refer below to Specify Parameter fieldname.

Specify Parameter fieldname

There may be situations where it's necessary to modify the default field names in the log output to align with organizational standards. This can help facilitate easier integration with log management tools and ensure consistency across reporting systems. The following field names can be overridden:

Parameter	Mandatory	Type	Default	Description
timestamp	No	string	timestamp	Override the timestamp field name according to your needs to specify the name through which the timestamp value can be accessed.
level	No	string	level	Override the level field name according to your needs to specify the name through which the value can be accessed.
caller	No	string	caller	Override the caller field name according to your needs to specify the name through which the value can be accessed.
message	No	string	message	SOverride the message field name according to your needs to specify the name through which the message value can be accessed.
error	No	string	error	Override the error field name according to your needs to specify the name through which the error value can be accessed.

Metrics

It is possible to gain insights into the HTTP traffic directed through aqilink. To achieve this, the interface can expose an endpoint compatible with the open-source monitoring and alerting toolkit, Prometheus. To enable this endpoint, configure the following parameter for key metrics in the app.yaml.

Parameter	Mandatory	Type	Default	Description
enabled	No	Boolean	false	By default, the endpoint for Prometheus is disabled. Enable it by setting this parameter to true.
path	No	string	/metrics	The name of the endpoint that is accessible by Prometheus. Make sure the path always starts with a slash!
tls	No	Object		Configure TLS for the /metrics endpoint. Refer to Transport Layer Security (TLS) below.
port	No	number	9090	The port number where the endpoint for Prometheus is accessible.

astuce

For visualizing the data collected by Prometheus, you can use tools like Grafana, for example.

attention

Neither Prometheus nor Grafana are included with the aqilink package. If you wish to use them, you must install and configure them separately. The settings above only expose the endpoint with the structure required by Prometheus.

Example

metrics:
  enabled: true
  path: /metrics
  tls: 
    enabled: true
    certPath: path/to/certificate/certificate.crt
    keyPath: path/to/certificate/keyfile.pem
  port: 9090

Port

Overrides the default port of the SAP HTTP Content Server. The default port exposed by the aqilink image is 3000. This setting allows you to specify a custom port to meet network configuration requirements or to avoid conflicts with other services running on the default port. Ensure that the specified port is open and properly configured in the network and firewall settings to allow seamless communication between aqilink and the SAP system.

Example

port: 3001

Tracing

aqilink supports all tracing systems compatible with the OpenTelemetry Protocol (OTLP) and Zipkin. This flexibility enables seamless integration with a broad array of tracing and monitoring solutions, providing enhanced observability and troubleshooting capabilities across diverse environments.

Parameter	Mandatory	Type	Default	Description
enabled	No	boolean	false	Enable or disable the tracing support.
type	No	string		Specify the type of tracing tool to be used. Allowed values are: otlp (Refer to OpenTelemetry Protocol below), zipkin (Refer to Zipkin below)

OpenTelemetry Protocol (OTLP)

OTLP is a standard protocol used for transmitting observability data, including traces, metrics, and logs, between different systems and platforms, enabling effective, vendor-neutral monitoring. Use the following parameter to specify the OTLP connection.

Parameter	Mandatory	Type	Default	Description
endpoint	Yes	string		The application's endpoint for the desired OTLP implementation (e.g., Jaeger). It must be a valid URL starting with either http or https.
protocol	No	string		The protocol used for connecting to the endpoint. Allowed values are http, grpc .
insecure	No	boolean	false	Determines whether to secure the connection to the OTLP server. Default is always to enforce a secure connection.

Zipkin

Zipkin is a distributed tracing system designed to help collect and analyze latency data from various microservices, allowing for performance monitoring and troubleshooting of complex, distributed systems.

Parameter	Mandatory	Type	Default	Description
endpoint	Yes	string		Specify the endpoint for Zipkin. It must be a valid URL starting with http or https that corresponds to the Zipkin server.

Example

tracing:
  enabled: true
  type: otlp
  protocol: http
  insecure: true
  endpoint: jaeger:4318

Transport Layer Security (TLS)

Use secure communication directly without relying on an external proxy. By configuring TLS, you can secure communication between clients and the aqilink server using SSL/TLS certificates, ensuring data encryption and secure connections.

Parameter	Mandatory	Type	Default	Description
enabled	No	boolean	false	Enabled or disable TLS for the endpoint.
certPath	No	string		File path to the SSL/TLS certificate.
keyPath	No	string		File path to the corresponding key of the certificate above.

Example

tls: 
  enabled: true
  certPath: path/to/certificate/certificate.crt
  keyPath: path/to/certificate/keyfile.pem

Password Encryption

Using encrypted passwords requires specifying the privateKeyPath parameter. The value should indicate the path to the private key within the container, which is used to decrypt the passwords. The private key must be either mapped to the container or copied into the image in advance. If password encryption is not needed, this setting can be omitted. The encryption utilizes the RSA mechanism.

astuce

For details on generating key pairs and setting up password encryption, refer to Password Encryption.

Example

privateKeyPath: /app/configs/privateKey.pem

Example Configuration

This is a sample configuration that includes the properties, as explained above.

Example

aqilinkLicense: 12345-67890-09876-54321
logging:
  level: 1
  caller: false
  structured: true
  timeFormat: 2006-01-02T15:04:05Z07:00
  fieldName: 
    timestamp: time
    level: level
    caller: caller
    message: message
    error: error
metrics:
  enabled: true
  path: /metrics
  tls: 
    enabled: true
    certPath: path/to/certificate/certificate.crt
    keyPath: path/to/certificate/keyfile.pem
port: 3001
tracing:
  enabled: true
  type: otlp
  protocol: http
  insecure: true
  endpoint: jaeger:4318
tls: 
  enabled: true
  certPath: path/to/certificate/certificate.crt
  keyPath: path/to/certificate/keyfile.pem
privateKeyPath: /app/configs/privateKey.pem