Check Socko out on GitHub


Socko User Guide - Configuration


Socko’s configuration is defined in WebServerConfig.

Web server configuration is immutable. To change the configuration, a new WebServer class must be instanced with the new configuration and started.

Socko configuration settings can be grouped as: - Network - Web Logs - SPDY

Loading Configuration

Configuration can be changed in code or in the project’s Akka configuration file.

For example, to change the port from the default 8888 to 7777 in code:

val webServer = new WebServer(WebServerConfig(port=7777), routes)

To change the port to 9999 in your Akka configuration file, first define an object to load the settings from application.conf. Note the setting will be named akka-config-example.

object MyWebServerConfig extends ExtensionId[WebServerConfig] with ExtensionIdProvider {
      override def lookup = MyWebServerConfig
      override def createExtension(system: ExtendedActorSystem) =
        new WebServerConfig(system.settings.config, "akka-config-example")

Then, start the actor system and load the configuration from that system.

val actorSystem = ActorSystem("AkkaConfigActorSystem")
    val myWebServerConfig = MyWebServerConfig(actorSystem)

Lastly, add the following your application.conf

akka-config-example {

A complete example application.conf can be found in WebServerConfig.

Network Settings

Common settings are:

Refer to the api documentation of WebServerConfig for all settings.

Web Log Settings

Socko supports 3 web log formats:


** COMMON ** - leon [01/Jul/2002:12:11:52 +0000] "GET /index.html HTTP/1.1" 200 431 ""

** COMBINED ** - leon [01/Jul/2002:12:11:52 +0000] "GET /index.html HTTP/1.1" 200 431 "" "Mozilla/4.05 [en] (WinNT; I)"

#Software: Socko
#Version: 1.0
#Date: 2002-05-02 17:42:15
#Fields: date time c-ip cs-username s-ip s-port cs-method cs-uri-stem cs-uri-query sc-status sc-bytes cs-bytes time-taken cs(User-Agent) cs(Referrer)
2002-05-24 20:18:01 - 80 GET /Default.htm - 200 7930 248 31 Mozilla/4.0+(compatible;+MSIE+5.01;+Windows+2000+Server)

Turning On Web Logs

By default, web logs are turned OFF.

To turn web logs on, add the following web-log section to your application.conf

akka-config-example {
  # Optional web log. If not supplied, web server activity logging is turned off.
  web-log {
    # Optional path of actor to which web log events will be sent for writing. If not specified, the default
    # web log writer will be created
    custom-actor-path = 

    # Optional web log format: Common (Default), Combined or Extended 
    format = Common

You can also turn it on programmatically as illustrated in the web log example app.

// Turn on web logs
    // Web logs will be written to the logger. You can control output via logback.xml.
    val config = WebServerConfig(webLog = Some(WebLogConfig()))
    val webServer = new WebServer(config, routes, actorSystem)

When turned on, the default behaviour is to write web logs to your installed Akka logger using WebLogWriter. The Akka logger asynchronously writes to the log so it will not slow down your application down.

To activate Akka logging, add the following to application.conf:

akka {
  event-handlers = ["akka.event.slf4j.Slf4jEventHandler"]
  loglevel = "DEBUG"

You can configure where web logs are written by configuring your installed logger. For example, if you are using Logback, you can write to a daily rolling file by changing logback.xml to include:

      <appender name="STDOUT" class="ch.qos.logback.core.ConsoleAppender">
          <pattern>%d{HH:mm:ss.SSS} [%thread] [%X{sourceThread}] %-5level %logger{36} %X{akkaSource} - %msg%n</pattern>

      <appender name="WEBLOG" class="ch.qos.logback.core.rolling.RollingFileAppender">
        <rollingPolicy class="ch.qos.logback.core.rolling.TimeBasedRollingPolicy">
          <!-- daily rollover -->

          <!-- keep 30 days' worth of history -->

      <logger name="org.mashupbots.socko.infrastructure.WebLogWriter" level="info" additivity="false">
        <appender-ref ref="WEBLOG" />

      <root level="info">
        <appender-ref ref="STDOUT" />

Recording Web Logs Events

Web log events can be recorded via the processing context.

Custom Web Log Output

If you prefer to use your own method and/or format of writing web logs, you can specify the path of a custom actor to recieve WebLogEvent messages in your application.conf.

akka-config-example {
  web-log {
    custom-actor-path = "akka://my-system/user/my-web-log-writer"

For more details, refer to the custom web log example app.

SPDY Settings

SPDY is an experimental networking protocol used in speeding up delivery of web content.

It is currently supported in the Chrome and Firefox (v11+) browsers.

Steps to enabling SPDY:

  1. You will need to run with JDK 7

  2. Setup JVM Bootup classes

    SPDY uses a special extension to TLS/SSL called Next Protocol Negotiation. This is not currently supported by Java JDK. However, the Jetty team has kindly open sourced their implementation.

    Refer to Jetty NPN for the correct version and download it from the maven repository.

    Add the JAR to your JVM boot parameters: -Xbootclasspath/p:/path/to/npn-boot-1.0.0.v20120402.jar.

  3. Set Web Server Configuration

    You will need to turn on SSL and enable SPDY in your configuration.

val keyStoreFile = new File(contentDir, "testKeyStore")
        val keyStoreFilePassword = "password"
        val sslConfig = SslConfig(keyStoreFile, keyStoreFilePassword, None, None)
        val httpConfig = HttpConfig(spdyEnabled = true)
        val webServerConfig = WebServerConfig(hostname="", webLog = Some(WebLogConfig()), ssl = Some(sslConfig), http = httpConfig)
        val webServer = new WebServer(webServerConfig, routes, actorSystem)