{{announcement.body}}
{{announcement.title}}

Akka HTTP From Zero to Heroku in 10 Minutes

DZone 's Guide to

Akka HTTP From Zero to Heroku in 10 Minutes

Start your very first Akka HTTP server and deploy it live in just a few steps.

· Microservices Zone ·
Free Resource
This article is for newbies to Akka HTTP and for those who have written some Akka HTTP but have never deployed their own server. Here I'll teach you what you need to know and do so that you have your first server up and running on Heroku in just a few minutes.

This article is also available over at the Rock the JVM blog or in video here (where I'll explain some additional things) or right below:


We'll be working in IntelliJ IDEA which creates an SBT project structure quickly, but you can also use the sbt command line to do the same things we do here. So here goes:

Step 1 - Intro


We'll start by creating a vanilla Scala-SBT project in intelliJ:



And after you click Finish, IntelliJ will create the appropriate project structure for you. Go to the src/ folder, and create a package and then an application under it. I created a package called server and under it I started a simple MyServer.scala:
Java
 




x


 
1
object MyServer {
2
  def main(args: Array[String]): Unit = {
3
    // will write in due time
4
  }
5
}


Once you've done that, it's time to "register" it as the runnable application so Heroku can identify it.

Step 2 - The Boilerplate


IntelliJ will create a project/ folder, where you will need to add a file called plugins.sbt and add an SBT plugin so you can package your application at the time you will deploy it to Heroku:
Java
 




xxxxxxxxxx
1


 
1
addSbtPlugin("com.typesafe.sbt" % "sbt-native-packager" % "1.3.12")


Then under your build.sbt you'll need to install the Akka libraries, refer to the packaging plugin and register the main class. Here is the entire content of the file:
Java
 




xxxxxxxxxx
1
21


 
1
name := "akka-http-test"
2
 
          
3
version := "0.1"
4
 
          
5
scalaVersion := "2.12.4"
6
 
          
7
// this will add the ability to "stage" which is required for Heroku
8
enablePlugins(JavaAppPackaging)
9
 
          
10
// this specifies which class is the main class in the package
11
mainClass in Compile := Some("server.MyServer")
12
 
          
13
val akkaVersion = "2.6.5"
14
val akkaHttpVersion = "10.1.12"
15
 
          
16
// add the Akka HTTP libraries
17
libraryDependencies ++= Seq(
18
  "com.typesafe.akka" %% "akka-stream" % akkaVersion,
19
  "com.typesafe.akka" %% "akka-actor-typed" % akkaVersion,
20
  "com.typesafe.akka" %% "akka-http" % akkaHttpVersion
21
)


After that, IntelliJ will usually pop up a small dialog asking you to "Import Changes". Click that and wait for a minute to download and install the libraries and plugin. Otherwise, go to View -> Tool Windows -> SBT and click on the tiny refresh icon to do the same thing.

After you don't see any red in build.sbt, you're good to go and you can write the actual code of your server

Step 3 - The Fun Part


It's probably the place we care about the most: the actual writing of the logic that will be our server. Akka HTTP is a huge set of libraries and with lots of capabilities. In this article I'll focus on a server that when hit with a GET request, will respond with a small HTML which will be seen in your browser. So here goes. Go to MyServer.scala and add any HTML you fancy:
Java
 




xxxxxxxxxx
1


 
1
val content =
2
    """
3
<html>
4
 <head></head>
5
 <body>
6
   This is an HTML page served by Akka HTTP!
7
 </body>
8
</html>
9
    """


Then you will define the logic of the server by a Directive, which is a fancy DSL to compose routing mechanisms very quickly:
Java
 




xxxxxxxxxx
1


 
1
import akka.http.scaladsl.server.Directives._
2
import akka.http.scaladsl.model.{ContentTypes, HttpEntity}


and inside your server application:
Java
 




xxxxxxxxxx
1


 
1
val route = get {
2
  complete(
3
    HttpEntity(
4
      ContentTypes.`text/html(UTF-8)`,
5
      content
6
    )
7
  )
8
}


which means that this server will respond to any GET request with an HTTP response with the content type text/html(UTF-8), and with the payload given by the content (HTML string) you defined earlier).

Then in the main method, you need to actually bind this routing logic on a hostname/port combination. On Heroku, you can't bind to localhost, so you will bind to 0.0.0.0. Here's how the main method looks like:
Java
 




xxxxxxxxxx
1
14


 
1
import akka.actor.ActorSystem
2
import akka.http.scaladsl.Http
3
 
          
4
def main(args: Array[String]): Unit = {
5
  // Akka HTTP needs an actor system to run
6
  implicit val system = ActorSystem("Server")
7
 
          
8
  // set hostname/port combination
9
  val host = "0.0.0.0"
10
  val port: Int = sys.env.getOrElse("PORT", "8080").toInt
11
 
          
12
  // this actually starts the server
13
  Http().bindAndHandle(route, host, port)
14
}


And that's it! Your application is now ready. All you have to do is deploy it to Heroku.

Step 4 - The Deploy


Do the steps below, they will take just a couple of minutes:

1. If you don't have a Heroku account, create one.
2. Then, create a new app, give it a name.
3. After that, make sure you install the Heroku command line.

After you have the Heroku command line, open a terminal and go to the directory of your Akka HTTP project, and run the following: first, make your project a Git repository:
Java
 




xxxxxxxxxx
1


 
1
$ git init
2
$ git add .
3
$ git commit -m "my first server"


Then, login to Heroku and make Heroku detect this project as a Scala application:
Java
 




xxxxxxxxxx
1


 
1
$ heroku login


which will also add the heroku remote for this project. After that, all you have to do is
Java
 




xxxxxxxxxx
1


 
1
$ git push heroku master


Part 5 - Enjoy


Navigate to https://replace-this-with-your-akka-http-server.herokuapp.com and see your first Akka HTTP server in action!

If you like this article, check out Rock the JVM here on DZone, on our blog, on Twitter, LinkedIn and YouTube!

Topics:
akka, akka http, heroku, microservices, scala, tutorial

Published at DZone with permission of Daniel Ciocirlan . See the original article here.

Opinions expressed by DZone contributors are their own.

{{ parent.title || parent.header.title}}

{{ parent.tldr }}

{{ parent.urlSource.name }}