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

§Embedding an Akka Http server in your application

Play Akka HTTP server is also configurable as a embedded Play server. The simplest way to start an Play Akka HTTP Server is to use the AkkaHttpServer 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.AkkaHttpServer

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

  try {
    testRequest(9000)
  } finally {
    //#stop-akka-http
    server.stop()
    //#stop-akka-http
  }
}

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.AkkaHttpServer
import play.core.server._

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

You may want to customise some of the components that Play provides, for example, the HTTP error handler. A simple way of doing this is by using Play’s components traits, the AkkaHttpServerComponents trait is provided for this purpose, and can be conveniently combined with BuiltInComponents to build the application that it requires:

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

import scala.concurrent.Future

val components = new AkkaHttpServerComponents with BuiltInComponents with NoHttpFiltersComponents {

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

  override lazy val httpErrorHandler = new DefaultHttpErrorHandler(
    environment,
    configuration,
    sourceMapper,
    Some(router)
  ) {

    protected override def onNotFound(request: RequestHeader, message: String): Future[Result] = {
      Future.successful(Results.NotFound("Nothing was found!"))
    }
  }
}
val server = components.server

In this case, 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.

Another way is to create a Play Application via GuiceApplicationBuilder in combination with the fromApplication method:

import play.api.inject.guice.GuiceApplicationBuilder
import play.api.mvc._
import play.api.routing.SimpleRouterImpl
import play.api.routing.sird._
import play.core.server.AkkaHttpServer
import play.core.server.ServerConfig

val server = AkkaHttpServer.fromApplication(
  GuiceApplicationBuilder()
    .router(new SimpleRouterImpl({
      case GET(p"/hello/$to") =>
        Action {
          Results.Ok(s"Hello $to")
        }
    }))
    .build(),
  ServerConfig(
    port = Some(19000),
    address = "127.0.0.1"
  )
)
//#config-akka-http

try {
  testRequest(19000)
} finally {
  server.stop()
}

Next: Embedding Play with Netty Server

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.