Document how to keep running an akka-http server in production

[richardimaoka]

There was a feedback in Twitter.

https://twitter.com/brianclapper/status/917148072718798848

those past techniques aren’t working w/ this version of Akka HTTP. Documentation for non-toy cases would be awesome. ;-)

https://twitter.com/jlprat/status/917149279399108608

Agree, readLine is just for toy cases. iirc, HttpApp listens to SIGTERM as well as readLine. Thanks for the feedback about docs! 😊

Doc samples use readline to wait, which is not recommended in production.

[richardimaoka]

Will work on it if no one else wants to pick this up in the next few days.

[bmc]

FYI, since I'm the grumpy developer who lodged the complaint about the documentation :-/, what worked perfectly for me was one of these:

With HttpApp

Override waitForShutdownSignal() like this:

override protected def waitForShutdownSignal(system: ActorSystem)
                                            (implicit ec: ExecutionContext): Future[Done] = {
  Promise[Done].future
}

Rolling your own

Something like this:

val f = for { bindingFuture <- Http().bindAndHandle(routes, host, port)
              waitOnFuture  <- Promise[Done].future }
        yield waitOnFuture
sys.addShutdownHook { 
  // cleanup logic
}
Await.ready(f, Duration.Inf)

[ktoso]

This should talk about coordinated shutdown https://doc.akka.io/docs/akka/current/scala/actors.html#coordinated-shutdown

Though we're missing that bit still in HTTP actually: #1210

So I propose to solve #1210 and then document things :)

[LogicalTime]

I think just adding the documentation for creating a future that never completes would be very helpful in the short term. Having a future that never completes feels like I'm doing something wrong.

Also, I think the current default shutdown strategies have issues when using sbt-revolver. E.g. they start up and instantly shut down. Having a nice setup that works ok for production and with sbt-revolver would really help people get started fast.

Also a link to a page with other shutdown strategies would be excellent. For example with Tomcat, I believe you can shut down the server while not being the user that owns the process. I imagine a server could be shutdown via a config file changing, or a protected http endpoint being hit. Links to some strategies would really be nice.

[viktorklang]

Prefer Future.never over Promise[Done].future as the latter will leak callbacks.

[bmc]

Wasn't aware that existed. (Clearly, I need to make a regular practice of reading the Scala API docs front to back.) Thanks, @viktorklang.

[viktorklang]

@bmc You're most welcome, Brian! :)

[git4skatz]

Could someone post a snippet of the proper way to block/suspend the main thread when using akka-http from Java?

[ktoso]

It's shown in the above snippet already, please read this ticket

[git4skatz]

What's shown above appear to me to be Scala, not Java. Also, the documentation recommends against overriding HttpApp (solution shown above) in favor of using Http.BindandHandle. Additionally, as someone new to Akka and Akka-Http a solution give in context would be valuable.

[ktoso]

Which is what this ticket is about... This ticket would be solved when we write this in the docs.
We'd welcome community help in adding this to the docs, as signaled by the "help wanted" tag.

In Java you get a CompletionStage so it's plain Java operations to await on it.

toCompletableFuture() + get()

https://docs.oracle.com/javase/8/docs/api/java/util/concurrent/CompletionStage.html#toCompletableFuture--
https://docs.oracle.com/javase/8/docs/api/java/util/concurrent/CompletableFuture.html

[bwbecker]

I'm an Akka newbie looking at the documentation on https://doc.akka.io/docs/akka-http/current/introduction.html?language=scala#. Agreed that waiting for the user to hit enter on StdIn is not ideal and a pointer to better approaches would be appreciated.