While designing your service it is useful to read designing services
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 JavaScript section
No additional tooling is required for local development. To build and deploy to a cluster:
- Docker; see https://docs.docker.com/engine/install/
- Akka Serverless CLI (
akkasls
); see https://developer.lightbend.com/docs/akka-serverless/getting-started/set-up-development-env.html#_akka_serverless_cli
To build, at a minimum you need to generate and process sources, particularly when using an IDE. A convenience is compile your project:
npm install
npm run build
Basic skeleton unit tests for each method in each service will be generated by the build
phase, but these will need to be fleshed out with assertions as behavior is implemented.
Mocha is the testing framework employed, and Chai is used for assertions. To execute the tests:
npm run test
These tests leverage the mock event-sourced entity classes provided by testkit.js
. These classes mimic the minimal required machinery to execute commands and handle events against a single entity for simple unit testing.
In future, more complicated testing can leverage the Akka Serverless integration test-kit which runs the proxy inside docker (see this example).
In order to run your application locally, you must run the Akka Serverless proxy. The included docker-compose
file contains the configuration required to run the proxy for a locally running application. 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.
docker-compose -f docker-compose.yml -f docker-compose.linux.yml up
To start the application locally, use the following commands:
Be sure to have performed
npm install
for the first time!
npm run build && npm run start
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.MyServiceEntity/GetValue -d '{"entityId": "foo"}'
The command handler for `GetValue` is not implemented, yet
For example, given grpcurl
:
> grpcurl -plaintext -d '{"entityId": "foo"}' localhost:9000 ${package}.MyServiceEntity/GetValue
ERROR:
Code: Unknown
Message: The command handler for `GetValue` is not implemented, yet
Note: The failure is to be expected if you have not yet provided an implementation of
GetValue
in your entity.
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 update the akkasls.dockerImage
property in the pom.xml
and refer to
Configuring registries
for more information on how to make your docker image available to Akka Serverless.
Finally you can or use the Akka Serverless Console
to create a project and then deploy your service into the project either by using npm run deploy
,
through the akkasls
CLI or via the web interface. When using npm run deploy
, NPM will also
conveniently package and publish your docker image prior to deployment.