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.

In order to run your service locally, you must run the Akka Serverless proxy, which we provide as a Docker image. The examples include docker compose files with the configuration required to run the proxy for a locally running application. It also contains the configuration to start a local Google Pub/Sub emulator that the Akka Serverless proxy will connect 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:

Start the proxy

macOS and Windows

docker compose up

Linux

docker-compose -f docker-compose.yml -f docker-compose.linux.yml up

Start the service
```
npm start
```

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