Configuring the server - Skullabs/kikaha GitHub Wiki

You can start using Kikaha without defining any configuration, since sensible default values are provided. Later on you might need to amend the settings to change the default behavior or adapt for specific runtime environments. Typical examples of settings that you might amend:

• Change listening port and address
• Defining authentication rules
• Configuring rewrite routes
• Configuring reverse proxy routes

Kikaha's configuration system was quite inspired on the Typesafe Config library. In fact, it served as the main configuration abstraction for Kikaha since its first version. Despite is was a very reliable and well tested library it also had a very verbose internal API, which made the code that relied on it hard to maintain. The new configuration abstraction is YML-based, but kept the best features from Config library, merging configuration files between modules.

Where configuration is read from?

Every Kikaha module has a META-INF/defaults.yml file. These files should contain all required configuration a module should had. During the server bootstrap all defaults.yml files found at the classpath are read and merged with all conf/application.conf files. This allow developers to write their custom conf/application.yml and place it on your project to change the server's default parameters.

If you are testing your source code, and need special configuration parameters in order to setup your test environment, you can create a file called conf/application-test.yml. Any parameter set there will override those set at your conf/application.yml.

Creating a configuration file for your project

Any file placed at the resources folder will be available at the classpath of your application. You can create the conf/application.yml at that folder and overwrite any server parameter you need to get your application up and running.

Once it is a simple YML file, you can also put any extra parameter you want on it. The bellow sample code shows you how to consume a configuration entry from your conf/application.yml file.

package sample;

import javax.inject.*;
import kikaha.config.Config;

@Singleton
class ASingletonServiceThatCanReadTheConfiguration {

  @Inject
  Config config;

  public String getIntegrationUsername(){
    return config.getString( "my-conf.integration.username" );
  }
}

Default configuration parameters

The bellow configuration file describes all the parameters Kikaha brings out-of-box. You can override it for any propose you need by creating your our conf/application.yml file and defining some configuration entries.

# Default server configuration
server:

  # Websocket configuration
  websocket:
    # The default Content serializer for websocket responses
    default-serializer: "text/plain"
    # The default Content unserializer for websocket requests
    default-unserializer: "text/plain"
    # Defines the max number of threads to handle incomming websocket requests
    # If set to a number lower than 1, it will create a dynamic thread pool 
    # to handler requests.
    worker-threads: -1

  # HTTP listener configurations
  http:
    host: '0.0.0.0'
    port: 9000
    enabled: true

  # HTTPS listener configurations
  https:
    host: '0.0.0.0'
    port: 9001

    keystore: "server.keystore"
    truststore: "server.truststore"
    cert-security-provider: "TLS"
    keystore-security-provider: "JKS"
    password: "password"
    enabled: false

    redirect-to-http: true

  # Undertow internals
  undertow:
    io-threads: -1
    worker-threads: -1
    buffer-size: 1024

    server-options:
      ENABLE_STATISTICS: false
      RECORD_REQUEST_START_TIME: false

    socket-options:
      BACKLOG: 20000

  # Static asset routing
  static:
    enabled: false

  # Smart routes
  smart-routes:
    # Rewrite routes (empty by default)
    rewrite:
    # Reverse proxy routes (empty by default)
    reverse:
    # Request filtering (empty by default)
    filter:
    # CORS support
    cors:
      enabled: false
      always-allow-origin: false
      always-allow-credentials: false
      allowed-methods:
      allowed-hosts:

  # Authentication/Authorization
  auth:

    # Configuration for fixed-user-and-pass Identity Manager
    fixed-auth:
      username: "admin"
      password: "admin"
      role: "admin"

    # Configuration for Form-based AuthMechanism
    form-auth:
      login-page: "/auth/"
      error-page: "/auth/error/"
      permission-denied-page: ""

    security-context-factory: kikaha.core.modules.security.DefaultSecurityContextFactory

    # Available IdentityManagers
    identity-managers:
      default: kikaha.core.modules.security.FixedUserAndPasswordIdentityManager
      fixed: kikaha.core.modules.security.FixedUserAndPasswordIdentityManager

    # Available AuthMechanisms
    auth-mechanisms:
      basic: kikaha.core.modules.security.BasicAuthenticationMechanism
      form: kikaha.core.modules.security.FormAuthenticationMechanism

    # Auth rules (empty by default)
    rules:

  # Configuration for Mustache templates
  mustache:
    cache-templates: false

  # Configurations for micro-Routing API
  urouting:
    default-encoding: "UTF-8"
    default-content-type: "text/plain"
    exception-handler: kikaha.urouting.UnhandledExceptionHandler