My Akkaserverless Project

Designing

While designing your service it is useful to read designing services.

Developing

This project has a bare-bones skeleton service ready to go, but in order to adapt and extend it it may be useful to read up on developing services and in particular the JVM section.

Building

You can use sbt to build your project, which will also take care of generating code based on the .proto definitions:

sbt compile

Running Locally

In order to run your application locally, you must run the Akka Serverless proxy. The included docker-compose.yml file contains 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. To start the proxy, run the following command from this directory:

docker-compose up

On Linux this requires Docker 20.10 or later (moby/moby#40007), or for a USER_FUNCTION_HOST environment variable to be set manually.

To start the application locally, start it from your IDE or use:

sbt run

With both the proxy and your application running, any defined endpoints should be available at http://localhost:9000. In addition to the defined gRPC interface, each method has a corresponding HTTP endpoint. Unless configured otherwise (see Transcoding HTTP), this endpoint accepts POST requests at the path /[package].[entity name]/[method]. For example, using curl:

> curl -XPOST -H "Content-Type: application/json" localhost:9000/com.example.CounterService/GetCurrentCounter -d '{"counterId": "foo"}'
The command handler for `GetCurrentCounter` is not implemented, yet

For example, using grpcurl:

> grpcurl -plaintext -d '{"counterId": "foo"}' localhost:9000 com.example.CounterService/GetCurrentCounter 
ERROR:
  Code: Unknown
  Message: The command handler for `GetCurrentCounter` is not implemented, yet

Note: The failure is to be expected if you have not yet provided an implementation of GetCurrentCounter in your entity.

Deploying

To deploy your service, install the akkasls CLI as documented in Setting up a local development environment and configure a Docker Registry to upload your Docker image to.

You will need to set your docker.username as a system property:

sbt -Ddocker.username=mary docker:publish

Refer to Configuring registries for more information on how to make your Docker image available to Akka Serverless.

You can now deploy your service through the akkasls CLI:

$ akkasls auth login

If this is your first time using Akka Serverless, this will let you register an account, create your first project and set it as the default.

Now:

$ akkasls services deploy \
    my-service \
    my-container-uri/container-name:tag-name

Once the service has been successfully started (this may take a while), you can create an ad-hoc proxy to call it from your local machine:

$ akkasls services proxy my-service
Listening on 127.0.0.1:8080

Or expose it to the Internet:

akkasls service expose my-service