import ballerina/config;
import ballerina/http;
import ballerina/log;
listener http:Listener helloWorldEP
    = new(config:getAsInt("hello.http.port", 9095), config = {
        secureSocket: {
            keyStore: {
                path: "${ballerina.home}/bre/security/ballerinaKeystore.p12",
                password: config:getAsString("hello.keystore.password")
            }
        }
});@http:ServiceConfig {
    basePath: "/hello"
}
service helloWorld on helloWorldEP {    @http:ResourceConfig {
        methods: ["GET"],
        path: "/"
    }
    resource function sayHello(http:Caller caller, http:Request req) {
        var result = caller->respond("Hello World!");
        if (result is error) {
           log:printError("Failed to respond to the caller", err = result);
        }
    }
}

Config

The ballerina/config module provides an API to read configurations from various sources such as files, environment variables and CLI parameters.

import ballerina/config;
import ballerina/http;
import ballerina/log;
listener http:Listener helloWorldEP
    = new(config:getAsInt("hello.http.port", 9095), config = {
        secureSocket: {
            keyStore: {
                path: "${ballerina.home}/bre/security/ballerinaKeystore.p12",
                password: config:getAsString("hello.keystore.password")
            }
        }
});

The Ballerina Config API allows you to look up values from configuration files, CLI parameters and environment variables. The precedence order for configuration resolution is as follows:

  • CLI parameters

  • Environment variables

  • Configuration files

If a specific configuration defined in the file is also defined as an environment variable, the environment variable takes precedence. Similarly, if the same is set as a CLI parameter, it replaces the environment variable value.

The configuration file is in TOML(v0.4) format.

The configuration API is particularly useful for configuring services. In this example, the port and keystore password are read through the configuration API instead of hard coding it in the source file. The configuration APIs accept a key and an optional default value. If a mapping does not exist for the specified key, the default value is returned as the configuration value. The default values of these optional configurations are the default values of the return types of the functions.

@http:ServiceConfig {
    basePath: "/hello"
}
service helloWorld on helloWorldEP {
    @http:ResourceConfig {
        methods: ["GET"],
        path: "/"
    }
    resource function sayHello(http:Caller caller, http:Request req) {
        var result = caller->respond("Hello World!");
        if (result is error) {
           log:printError("Failed to respond to the caller", err = result);
        }
    }
}
# Sensitive data such as passwords can be encrypted and accessed securely in code. To encrypt a value, the
# `ballerina encrypt` command is used. It prompts the user to enter the value and a secret. In this example,
# `ballerina` is the value and `12345` is the secret.
$ ballerina encrypt
Enter value:
Enter secret:
Re-enter secret to verify:
Add the following to the configuration file:
<key>="@encrypted:{69P5VGO+hOomLWhoY28gJiGPmBzWvzlmGGWA9X3uWZM=}"
Or provide it as a command line argument:
--<key>=@encrypted:{69P5VGO+hOomLWhoY28gJiGPmBzWvzlmGGWA9X3uWZM=}
# The secret needs to be provided if a configuration contains an encrypted value. The secret can be provided
# via a `secret.txt` file or via the CLI. In this example, the CLI is used.
$ ballerina run config_api.bal
ballerina: enter secret for config value decryption:
# To specify a configuration file explicitly, use the `--b7a.config.file=<path_to_configuration_file>` property.
# If this property is not set, Ballerina looks for a `ballerina.conf` file in the current directory. The path
# to the configuration file can be either an absolute or a relative path.
# To run this example, place the following configurations in a file and provide its path.
# ```
# [hello.http]
#  port=8085
# [hello.keystore]
#  password="@encrypted:{69P5VGO+hOomLWhoY28gJiGPmBzWvzlmGGWA9X3uWZM=}"
#
# ```
$ ballerina run config_api.bal --b7a.config.file=path/to/conf/file/custom-config-file-name.conf
ballerina: enter secret for config value decryption:
ballerina: started HTTPS/WSS listener 0.0.0.0:8085
# The same configurations given via a configuration file can also be given via CLI parameters. <br>
# e.g., hello.http.port
$ ballerina run config_api.bal --hello.http.port=8085 --hello.keystore.password=@encrypted:{69P5VGO+hOomLWhoY28gJiGPmBzWvzlmGGWA9X3uWZM=}
ballerina: enter secret for config value decryption:
ballerina: started HTTPS/WSS listener 0.0.0.0:8085