1. Home
2. Working with Play
3. Play for Scala developers
4. Advanced topics
5. Embedding Play

§Embedding a Netty server in your application

While Play apps are most commonly used as their own container, you can also embed a Play server into your own existing application. This can be used in conjunction with the Twirl template compiler and Play routes compiler, but these are of course not necessary. A common use case is an application with only a few simple routes. To use Netty Server embedded, you will need the following dependency:

libraryDependencies ++= Seq(
  nettyServer
)

One way to start a Play Netty Server is to use the NettyServer factory methods. If all you need to do is provide some straightforward routes, you may decide to use the String Interpolating Routing DSL in combination with the fromRouterWithComponents method:

import play.api.mvc._
import play.api.routing.sird._
import play.core.server._

val server = NettyServer.fromRouterWithComponents() { components =>
  import components.{ defaultActionBuilder => Action }
  {
    case GET(p"/hello/$to") =>
      Action {
        Results.Ok(s"Hello $to")
      }
  }
}

By default, this will start a server on port 9000 in prod mode. You can configure the server by passing in a ServerConfig:

import play.api.mvc._
import play.api.routing.sird._
import play.core.server._

val server = NettyServer.fromRouterWithComponents(
  ServerConfig(
    port = Some(19000),
    address = "127.0.0.1"
  )
) { components =>
  import components.{ defaultActionBuilder => Action }
  {
    case GET(p"/hello/$to") =>
      Action {
        Results.Ok(s"Hello $to")
      }
  }
}

Play also provides components traits that make it easy to customize other components besides the router. The NettyServerComponents trait is provided for this purpose, and can be conveniently combined with BuiltInComponents to build the application that it requires. In this example we use DefaultNettyServerComponents, which is equivalent to NettyServerComponents with BuiltInComponents with NoHttpFiltersComponents:

import play.api.http.DefaultHttpErrorHandler
import play.api.mvc._
import play.api.routing.Router
import play.api.routing.sird._
import play.core.server._

import scala.concurrent.Future

val components = new DefaultNettyServerComponents {
  lazy val router = Router.from {
    case GET(p"/hello/$to") =>
      Action {
        Results.Ok(s"Hello $to")
      }
  }

  override lazy val httpErrorHandler: DefaultHttpErrorHandler =
    new DefaultHttpErrorHandler(environment, configuration, devContext.map(_.sourceMapper), Some(router)) {
      protected override def onNotFound(request: RequestHeader, message: String) = {
        Future.successful(Results.NotFound("Nothing was found!"))
      }
    }
}
val server = components.server

Here the only method you need to implement is router. Everything else has a default implementation that can be customized by overriding methods, such as in the case of httpErrorHandler above. The server configuration can be overridden by overriding the serverConfig property.

To stop the server once you’ve started it, simply call the stop method:

server.stop()

Note: Play requires an application secret to be configured in order to start. This can be configured by providing an application.conf file in your application, or using the play.http.secret.key system property.

§Logging configuration

When using Netty as an embedded server, no logging dependencies are included by default. If you want to also add logging to the embedded application, you can add the Play logback module:

libraryDependencies ++= Seq(
  logback
)

And later call the LoggerConfigurator API:

import play.api.mvc._
import play.api.routing.Router
import play.api.routing.sird._
import play.api._
import play.core.server._

val environment = Environment.simple(mode = Mode.Prod)
val context     = ApplicationLoader.Context.create(environment)

// Do the logging configuration
LoggerConfigurator(context.environment.classLoader).foreach {
  _.configure(context.environment, context.initialConfiguration, Map.empty)
}

val components = new DefaultNettyServerComponents {
  override def router: Router = Router.from {
    case GET(p"/hello/$to") =>
      Action {
        Results.Ok(s"Hello $to")
      }
  }
}

val server = components.server

Next: Common topics

Found an error in this documentation? The source code for this page can be found here. After reading the documentation guidelines, please feel free to contribute a pull request. Have questions or advice to share? Go to our community forums to start a conversation with the community.