Running Multi-Nodes Akka Cluster on Docker

Akka a great actor framework for the JVM.  Akka is high performance with high throughput and low latency, resilient by Design.  It's possible to use Akka with Java however I always used and recommend you use with Scala.

Create actors systems is pretty easy however creating multiple nodes on Akka cluster locally could be boring and error-prone. So I want to show how easy is to create an Akka cluster using Scala and Docker(Engine & Docker-Compose). We will create a very simple actor system, we will just log events on the cluster however you can use this as a base to do more complex code.


In this project, we will use Scala 2.12.3, Akka 2.5.6. Here we are defining these versions and also the docker configuration so we will generate a Dockerfile based on this project.

We will be using SBT 0.13.8 -- You can define SBT on the file project/



We also need to add the docker plugin on SBT. We do it by editing the file project/plugins.sbt.


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

OK. Now we can go to the code. Let's create a Main.scala at src/main/scala.


Here we have an ActorSystem and we are registering a ClusterListener which is an actor that will be notified about all cluster events and when this actor boot up he will register itself on the cluster. This registration is defined on the preStart function.


Here we define the cluster configurations for Akka cluster. We defined the actor provider to be akka.cluster.ClusterActorRefProvider. One big important thing here is the seeds-node these nodes need to be up in order to other nodes join the cluster. You don't need to have all your nodes as seeds usually folks add 2-3 nodes as seeds. So seeds nodes address is: akka.tcp://default@akkaseed:2552 So we need to have a node running on port 2552.


Finally, we have the docker-compose configuration. There are only 2 containers here. Seed and node. So this will create a cluster with 2 nodes. However, we will be able to scale the node image to N nodes.

Building & Running

Now is the fun part -).  Open Linux the terminal, we need to build the Docker image and then we can run docker compose. So letś do it:

$ sbt clean compile docker:publishLocal
$ docker-compose up

That's it we have the cluster Up and running.

Akka 2 Node Cluster Running - docker-compose up

Scaling Up the Cluster

We can scale the cluster to N nodes - So right now we only have 2 nodes, Let's scala the cluster to 10 nodes. We do it with docker compose by $ docker-compose scale node=10 That's it you should have something like this.

Scaling up the cluster - docker-compose scale node=10

Akka Cluster Logs - After Scale Up to 10 nodes

This is great for development and debugging. For production, I recommend using Kubernetes. You can get all the source code on my GitHub here.

Diego Pacheco

Popular posts from this blog

Kafka Streams with Java 15

Rust and Java Interoperability

HMAC in Java