Configuration

Pillars is configured using YAML v1.2 files.

Pillars Configuration

Pillars configuration is structured as follows:

name: Bookstore
log:
  level: info
  format: enhanced
  output:
    type: console
db:
  host: localhost
  port: 5432
  database: pillars_example
  username: postgres
  password: postgres
  pool-size: 10
  debug: false
  probe:
    timeout: PT5s
    interval: PT10s
    failure-count: 3
  logging:
    enabled: true
    level: info
    statements: true
    timing: true
db-migration:
  url: jdbc:postgresql://localhost:5432/pillars_example
  username: postgres
  password: postgres
  system-schema: public
  app-schema: public
  baseline-version: "0"
api:
  enabled: true
  http:
    host: 0.0.0.0
    port: 9876
    logging:
      enabled: true
      headers: true
      body: true
      level: info
  open-api:
    enabled: false
    path-prefix: ["docs"]
    yaml-name: "pillars-example.yaml"
    context-path: []
    use-relative-paths: true
    show-extensions: false
admin:
  enabled: true
  http:
    host: 0.0.0.0
    port: 19876
    logging:
      enabled: true
      headers: true
      body: true
      level: debug
  open-api:
    enabled: false
    path-prefix: ["docs"]
    yaml-name: "pillars-example.yaml"
    context-path: []
    use-relative-paths: true
    show-extensions: false
observability:
  enabled: true
  service-name: bookstore
  metrics:
    enabled: true
  traces:
    enabled: true
http-client:
  follow-redirect: true
  user-agent: pillars/bookstore
  logging:
    enabled: true
    headers: true
    body: true
    level: info
feature-flags:
  enabled: true
  flags:
    - name: feature-1
      status: enabled
    - name: feature-2
      status: disabled
If you are using the EntryPoint trait, the path to this file must be given to the application using the --config command line option.

The config must contain the following keys:

  • name: the name of the application

  • api: the API server configuration

  • admin: the admin server configuration

  • observability: the observability configuration

The logging configuration is optional and can be omitted if you are happy with the default configuration.

The db and feature-flags sections are needed only if you include the db and feature-flags modules respectively.

API Configuration

The API configuration is structured as follows:

api:
  enabled: true
  http:
    host: 0.0.0.0
    port: 9876
    logging:
      enabled: true
      headers: true
      body: true
      level: info
  open-api:
    enabled: false
    path-prefix: ["docs"]
    yaml-name: "pillars-example.yaml"
    context-path: []
    use-relative-paths: true
    show-extensions: false

It contains the following keys:

  • enabled: whether the API server is enabled or not

  • http: the HTTP server configuration:

    • host: the host to bind to. Default is 0.0.0.0, i.e. all interfaces.

    • port: the port to bind to. Default is 9876.

    • logging: The HTTP logging configuration:

      • enabled: whether to enable HTTP access logging or not. Default is false.

      • headers: whether to log HTTP headers or not. Default is false.

      • body: whether to log HTTP bodies or not. Default is false.

      • level: the log level. Possible values are trace, debug, info, warn, error. Default is debug.

    • open-api: the OpenAPI configuration:

      • enabled: whether to enable OpenAPI or not. Default is false.

      • path-prefix: the path prefix for the OpenAPI documentation. Default is ["docs"].

      • yaml-name: the name of the OpenAPI YAML file. Default is pillars.yaml.

      • context-path: the context path for the OpenAPI documentation. Default is /.

      • use-relative-paths: whether to use relative paths or not. Default is true.

      • show-extensions: whether to show extensions or not. Default is false.

Admin Configuration

The admin configuration is structured as follows:

admin:
  enabled: true
  http:
    host: 0.0.0.0
    port: 19876
    logging:
      enabled: true
      headers: true
      body: true
      level: debug
  open-api:
    enabled: false
    path-prefix: ["docs"]
    yaml-name: "pillars-example.yaml"
    context-path: []
    use-relative-paths: true
    show-extensions: false

It contains the following keys:

  • enabled: whether the admin server is enabled or not

  • http: the HTTP server configuration:

    • host: the host to bind to. Default is 0.0.0.0, i.e. all interfaces.

    • port: the port to bind to. Default is 19876.

    • logging: The HTTP logging configuration:

      • enabled: whether to enable HTTP access logging or not. Default is false.

      • headers: whether to log HTTP headers or not. Default is false.

      • body: whether to log HTTP bodies or not. Default is false.

      • level: the log level. Possible values are trace, debug, info, warn, error. Default is debug.

    • open-api: the OpenAPI configuration:

      • enabled: whether to enable OpenAPI or not. Default is false.

      • path-prefix: the path prefix for the OpenAPI documentation. Default is ["docs"].

      • yaml-name: the name of the OpenAPI YAML file. Default is pillars.yaml.

      • context-path: the context path for the OpenAPI documentation. Default is /.

      • use-relative-paths: whether to use relative paths or not. Default is true.

      • show-extensions: whether to show extensions or not. Default is false.

Observability Configuration

The observability configuration is structured as follows:

observability:
  enabled: true
  service-name: bookstore
  metrics:
    enabled: true
  traces:
    enabled: true

It contains the following keys:

  • enabled: whether observability is enabled or not

  • service-name: the name of the service.Default is pillars.

  • metrics: the metrics configuration:

    • enabled: whether metrics are enabled or not. Default is false.

  • traces: the traces configuration:

    • enabled: whether traces are enabled or not. Default is false.

Logging Configuration

The logging configuration is structured as follows:

log:
  level: info
  format: enhanced
  output:
    type: console

It contains the following keys:

  • level: the log level. Possible values are trace, debug, info, warn, error. Default is info.

  • format: the log format. Possible values are json, simple, colored, classic, compact, enhanced, advanced, strict. For more details, refer to the scribe documentation. Default is enhanced.

  • output: the log output.

    • type: the log output type. Possible values are console or file. Default is console.

    • path: the path to the log file. It is used only if output.type is file.

Database Configuration

The database configuration is structured as follows:

db:
  host: localhost
  port: 5432
  database: pillars_example
  username: postgres
  password: postgres
  pool-size: 10
  debug: false
  probe:
    timeout: PT5s
    interval: PT10s
    failure-count: 3
  logging:
    enabled: true
    level: info
    statements: true
    timing: true

It contains the following keys:

  • host: the database host. Default is localhost.

  • port: the database port. Default is 5432.

  • database: the database name.

  • user: the database user.

  • password: the database password.

  • pool-size: the database connection pool size. Default is 32.

  • debug: whether to enable database debug logging or not. Default is false.

  • probe: the database probe configuration:

    • timeout: the probe timeout. Default is 5s.

    • interval: the probe interval. Default is 10s.

    • failure-count: the number of consecutive failures before the database is considered down. Default is 3.

Feature Flags Configuration

The feature flags configuration is structured as follows:

feature-flags:
  enabled: true
  flags:
    - name: feature-1
      status: enabled
    - name: feature-2
      status: disabled

It contains the following keys:

  • enabled: whether feature flags are enabled or not

  • flags: the feature flags definition:

    • name: the name of the feature flag

    • status: the status of the feature flag. Possible values are enabled or disabled.

Application Configuration

You can define the configuration of your application in the same file as the Pillars configuration. It must be under the app key.

In order to read the configuration, you need to use the configReader method of the Pillars instance.

object app extends pillars.EntryPoint:
    def app: pillars.App[IO] = new pillars.App[IO]:
        def infos: AppInfo = BuildInfo.toAppInfo

        def run(using p: Pillars[IO]): IO[Unit] =
            import p.*
            for
                config <- configReader[BookstoreConfig]
                _ <- IO.println(s"Config: $config")
            yield ()

The configuration class must be a case class and there must be at least a circe Decoder defined for it.

package example

import io.circe.Codec

case class BookstoreConfig(enabled: Boolean = true, users: UsersConfig = UsersConfig())
object BookstoreConfig:
    given Codec[BookstoreConfig] = Codec.AsObject.derived

case class UsersConfig(init: Boolean = false)
object UsersConfig:
    given Codec[UsersConfig] = Codec.AsObject.derived