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.

The Akka Serverless proxy is required running local instances of a service. The proxy is packaged in a Docker container image available on the Akka Serverless-Public container registry. The example docker compose files is configured to leverage the proxy and run the application locally.

It also contains the configuration to start a local Google Pub/Sub emulator that the Akka Serverless proxy connects to when you make use of Publishing and subscribing to topics on a broker in your service.

Pre-requisites

  • Docker 19.03 or higher installed and accessible on your local computer

  • Access to the gcr.io/akkaserverless-public Docker registry from your local computer

  • Your service container image.

Starting the service

To start the proxy, run the following command from the directory with the docker-compose.yml file:

  1. Start the proxy

    Mac and Windows
    docker compose up
    Linux
    docker-compose -f docker-compose.yml -f docker-compose.linux.yml up
  2. Start the service

    mvn compile exec:java

Exercise the service

Now the service is ready to accept commands on localhost:9000.

Use curl to call your service via HTTP, or grpcurl to use the gRPC endpoints directly.

This curl command calls the "CounterService" from the kickstart example, you will need to adapt it depending on the API of your service.

Linux or macOS
curl \
  -XPOST \ (1)
  -H "Content-Type: application/json" \ (2)
  -d '{"counterId": "foo"}' \ (3)
  localhost:9000/com.example.CounterService/GetCurrentCounter (4)
Windows 10+
curl ^
  -XPOST ^ (1)
  -H "Content-Type: application/json" ^ (2)
  -d '{"counterId": "foo"}' ^ (3)
  localhost:9000/com.example.CounterService/GetCurrentCounter (4)

The curl command takes

1 a flag to send a POST request,
2 set the content type to JSON,
3 the message in JSON format,
4 the URL with the RPC procedure name which deducts from the protobuf definition of the component we’re calling.

All Akka Serverless APIs are exposed as regular HTTP endpoints which you can call with curl. Protobuf annotations allow controlling the mapping to HTTP as discussed in Transcoding HTTP.

This grpcurl command line calls the same "Counter Service", from the kickstart example, you will need to adapt it depending on the API of your service.

Linux or macOS
grpcurl \
  -d '{"counterId": "foo"}' \ (1)
  -plaintext localhost:9000 \ (2)
  com.example.CounterService/GetCurrentCounter (3)
Windows 10+
grpcurl ^
  -d '{"counterId": "foo"}' ^ (1)
  -plaintext localhost:9000 ^ (2)
  com.example.CounterService/GetCurrentCounter (3)

The grpcurl command takes

1 the message in JSON format with -d,
2 the address to the proxy (using plain text instead of TLS),
3 and the RPC procedure name which deducts from the protobuf definition of the component we’re calling.

Shut down the proxy

The command below shows how to shut down the proxy. Shutting down the proxy removes all data, which is kept in memory.

docker stop akkaserverless-proxy

To delete the proxy container

docker rm akkaserverless-proxy