Running 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. To start and stop multiple services, you can create scripts using the same generalized commands.


  • Docker installed and accessible on your local computer.

  • Access to the docker registry from your local computer.

  • Your service container image.

Starting the service

From a command prompt, create Docker network. The following creates a network named akkasls-lan, but you can use any name.

docker network create -d bridge akkasls-lan

Retrieve the image id of your service image with the docker images command:

$ docker images | grep shopping-cart
myuser/shopping-cart           1.32     f30694769aab   2 hours ago    177MB
myuser/shopping-cart           latest   f30694769aab   2 hours ago    177MB

Run your service container in Docker. In the following example, the container name is shopping-cart, the service container image id is f30694769aab, and it connects to the akkasls-lan network we created earlier.

docker run -d --name shopping-cart --network akkasls-lan f30694769aab

Use Docker inspect to retrieve the address of the running container in the range of the akkasls-lan network.

service_address=$(docker inspect -f '{{range.NetworkSettings.Networks}}{{.IPAddress}}{{end}}' shopping-cart)

Start the proxy.

docker run -d --name akkaserverless-proxy --network akkasls-lan -p 9000:9000 \
  --env USER_FUNCTION_HOST=$service_address \

The parameters to this command include:

  • The proxy image that contains the functional sub-set we need for local testing.

  • A connection to the akkasls-lan network that exposes the proxy to the 9000 port of the docker host.

  • The environment variable USER_FUNCTION_HOST, set to the service container’s address. The proxy uses this IP to connect to the user function.

Now we can inspect the logs of the proxy to see if it found the service order:

docker logs akkaserverless-proxy

The following line in the log is written when the proxy registers the Entities of the service.

2021-01-08 07:11:03.779 com.akkaserverless.proxy.DiscoveryManager - Received Spec from user function with info...

The following line, which should be at the bottom of the startup portion of the log, shows that the proxy now accepts connections on the address ''

2021-01-08 07:11:04.290 INFO io.akkaserverless.proxy.DiscoveryManager - Akka Serverless proxy online at /

Now the service is ready to accept commands on

Exercise the service

Try exercising the service with grpcurl:

grpcurl \
  -d '{"userId": "3232", "productId": "4711", "name": "Sun glasses", "quantity": 3}' \
  -plaintext localhost:9000 \

The grpcurl command takes the command data with -d, the address to the proxy (using plain text instead of TLS), and the RPC procedure name.

For the shopping cart example, retrieve the updated cart with the GetCart procedure:

grpcurl \
  -d '{"userId": "3232"}' \
  -plaintext localhost:9000 \

Shut down the service

The steps below show how to shut down the service and the proxy, using the example service shopping-cart from the previous section. Shutting down the proxy removes all data, which is kept in memory.

docker stop shopping-cart
docker stop akkaserverless-proxy

To delete the order and proxy containers:

docker rm shopping-cart
docker rm akkaserverless-proxy

Finally, delete the akkasls-lan network used by the containers.

docker network rm akkasls-lan