Run a service locally
Running a service locally is helpful to test and debug. The following sections provide commands for starting and stopping a single service locally.
Prerequisites
In order to run your service locally, you’ll need to have the following prerequisites:
-
Java 21, we recommend Eclipse Adoptium
-
Apache Maven version 3.9 or later
Starting your service
As an example, we will use the Shopping Cart sample.
To start your service locally, run the following command from the root of your project:
mvn compile exec:java
Invoking your service
After you start the service it will accept invocations on localhost:9000
. You can use cURL in another shell to invoke your service.
Run from IntelliJ
The getting started sample and other samples include a run configuration for IntelliJ. In the toolbar you should see:
This is a Maven run configuration for mvn compile exec:java
. You can also run this with the debugger and set breakpoints in the components.
Local console
The local console gives you insights of the services that you are running locally.
To run the console you need to install:
Start the console with the following command from a separate terminal window:
akka local console
Start one or more services as described in Starting your service and they will show up in the console. You can restart the services without restarting the console.
Running a service with persistence enabled
By default, when running locally, persistence is disabled. This means the Akka Runtime will use an in-memory data store for the state of your services. This is useful for local development since it allows you to quickly start and stop your service without having to worry about cleaning the database.
However, if you want to run your service with persistence enabled to keep the data when restarting, you can configure
the service in application.conf
with akka.javasdk.dev-mode.persistence.enabled=true
or as a system property when starting the service locally.
mvn compile exec:java -Dakka.javasdk.dev-mode.persistence.enabled=true
To clean the local database look for db.mv.db
file in the root of your project and delete it.
Running a service with broker support
By default, when running locally, broker support is disabled. When running a service that declares consumers or producers locally, you need to configure the broker with property akka.javasdk.dev-mode.eventing.support=kafka
in application.conf
or as a system property when starting the service.
mvn compile exec:java -Dakka.javasdk.dev-mode.eventing.support=kafka
For Google PubSub Emulator, use akka.javasdk.dev-mode.eventing.support=google-pubsub-emulator
.
For Kafka, the local Kafka broker is expected to be available on localhost:9092 . For Google PubSub, the emulator is expected to be available on localhost:8085 .
|
Running multiple services locally
A typical application is composed of one or more services deployed to the same Akka project. When deployed under the same project, two different services can make calls to each other or subscribe to each other’s event streams by simply using their logical names.
The same can be done on your local machine by configuring the services to run on different ports. The services will discover each other by name and will be able to interact.
The default port is 9000, and only one of the services can run on the default port. The other service must be configured with another port.
This port is configured in akka.javasdk.dev-mode.http-port
property in the
src/main/resources/application.conf
file.
akka.javasdk.dev-mode.http-port=9001
With both services configured, we can start them independently by running mvn compile exec:java
in two separate terminals.
Running a local cluster
For testing clustering behavior and high availability scenarios, you can run your Akka service as a local cluster with multiple nodes. This allows you to simulate a distributed environment on your local machine.
Database requirement
To run in cluster mode, you need a shared database that all nodes can connect to. The local-nodeX.conf
files configure the application to connect to a PostgreSQL database.
Before starting your cluster nodes, you must start a local PostgreSQL database. We recommend using Docker Compose for this purpose. Create a docker-compose.yml
file with the following configuration:
services:
postgres-db:
image: postgres:17
ports:
- 5432:5432
environment:
POSTGRES_USER: postgres
POSTGRES_PASSWORD: postgres
healthcheck:
test: ["CMD", "pg_isready", "-q", "-d", "postgres", "-U", "postgres"]
interval: 5s
retries: 5
start_period: 5s
timeout: 5s
Start the database with:
docker compose up -d
Cluster configuration
You can create a local cluster with up to 3 nodes. Each node requires its own configuration file and will run on a different HTTP port.
To start each node, use the following commands in separate terminal windows:
# Node 1 (runs on port 9000)
mvn compile exec:java -Dconfig.resource=local-node1.conf
# Node 2 (runs on port 9001)
mvn compile exec:java -Dconfig.resource=local-node2.conf
# Node 3 (runs on port 9002)
mvn compile exec:java -Dconfig.resource=local-node3.conf
Port assignment
The cluster nodes use sequential port numbering based on your configured HTTP port:
-
Node 1: Uses the standard HTTP port (default: 9000)
-
Node 2: Uses standard port + 1 (default: 9001)
-
Node 3: Uses standard port + 2 (default: 9002)
If you have configured a custom HTTP port in your application.conf
(for example, 9010), the cluster nodes will use:
-
Node 1: 9010
-
Node 2: 9011
-
Node 3: 9012
This ensures that each node in the cluster has its own unique port while maintaining a predictable numbering scheme.