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.
Join the DZone community and get the full member experience.
Join For Free
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!
Akka (toolkit)
intellij
Java (programming language)
application
Published at DZone with permission of Daniel Ciocirlan. See the original article here.
Opinions expressed by DZone contributors are their own.
Trending
-
RBAC With API Gateway and Open Policy Agent (OPA)
-
Microservices With Apache Camel and Quarkus
-
A Complete Guide to AWS File Handling and How It Is Revolutionizing Cloud Storage
-
The SPACE Framework for Developer Productivity
Comments