Quickstart project: Customer Registry

Designing

To understand the Kalix concepts that are the basis for this example, see Designing services in the documentation.

Developing

This project demonstrates the use of Value Entity and View components. To understand more about these components, see Developing services and in particular the Java section

Building

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

mvn compile

Running Locally

To run the example locally, you must run the Kalix proxy. The included docker-compose 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 Kalix proxy will connect to. To start the proxy, run the following command from this directory:

docker-compose up

To start the application locally, the exec-maven-plugin is used. Use the following command:

mvn compile exec:exec

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:

Create a customer with:

grpcurl --plaintext -d '{"customer_id": "wip", "email": "wip@example.com", "name": "Very Important", "address": {"street": "Road 1", "city": "The Capital"}}' localhost:9000  customer.api.CustomerService/Create

Retrieve the customer:

grpcurl --plaintext -d '{"customer_id": "wip"}' localhost:9000  customer.api.CustomerService/GetCustomer

Change name:

grpcurl --plaintext -d '{"customer_id": "wip", "new_name": "Most Important"}' localhost:9000 customer.api.CustomerService/ChangeName

Change address:

grpcurl --plaintext -d '{"customer_id": "wip", "new_address": {"street": "Street 1", "city": "The City"}}' localhost:9000 customer.api.CustomerService/ChangeAddress

Deploying

To deploy your service, install the kalix 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 dockerImage property in the pom.xml and refer to Configuring registries for more information on how to make your docker image available to Kalix.