Getting Started with Kalix

Author - Johan Andrén. Principal Engineer, Lightbend.

We want to show you how easy it is to get going with Kalix and how quickly you can start building high-performance APIs and microservices.

In this article we will guide you through getting started with the needed tools to create, build and deploy your first Java based Kalix service.

Creating, deploying and managing Kalix services is done through a command line utility (CLI) which needs to be installed first. Let’s start with installing the command line client.

The steps are a little bit different depending on if you are on a Windows, MacOS or Linux machine, see individual instructions for each platform in the documentation here.

Once the client has been installed, create a Kalix account by opening a terminal window and executing:

$ kalix auth login

This will open up a browser window with the Kalix log in page.

Start creating a new account by clicking “Register” or through an existing google account.

Once the account is created you will end up in a window asking you to authorize your CLI, choose “Authorize” to give the CLI permission to deploy and manage projects and services for your account.

The CLI which was waiting for this permission will now say “You are now logged in”.

Kalix services are organized into projects, to deploy a first service we need to create a project, let’s do so with our CLI executing:

$ kalix project new my-project --region gcp-us-east1

We now have an empty project called my-project created, and selected as default when deploying services.

Implementing a Kalix service is done through one of the available Kalix SDKs, you can currently build projects using the Java or Scala SDK or the TypeScript or JavaScript SDK.

To make getting started easy, the command line client provides several quickstart projects that we can start from, take a look at the available quickstarts using:

$ kalix quickstart list

Let’s download the customer-registry-java project, build and deploy it.

$ kalix quickstart download customer-registry-java
unzipping file  customer-registry/pom.xml
unzipping file  customer-registry/README.md
unzipping file  customer-registry/docker-compose.yml
unzipping file  customer-registry/src
...

Open the project in your favorite Java IDE and take a look at the protobuf service descriptors in src/main/proto and the corresponding entity service implementation in src/main/java/customer/domain/Customer.java.

We’ll deploy the project to Kalix by first compiling the Java sources and package them as a docker image, the image is then published to docker hub where Kalix will fetch it to deploy and start the service.

To continue you will have to have the following installed and available on your PATH:

• A recent version of Docker
• JDK 11 or later
• A recent version of Apache Maven

Make sure that docker is logged in to docker hub:

$ docker login

Update the “dockerImage” property in pom.xml replacing my-docker-repo with your docker hub account name, this is where the artifact will be published.

Build, package and publish the project using maven:

$ cd customer-registry
$ mvn deploy

This will both publish the docker image to docker hub and then deploy the published image to Kalix, in the output you will see:

[info] Deploying project to Kalix
[info] Executing `kalix service deploy customer-registry johanandren/customer-registry:1.0-SNAPSHOT-20220622124847`
[info] Done.

You can use the command line to verify that the service has been deployed:

$ kalix service list
NAME                AGE   REPLICAS   STATUS   DESCRIPTION
customer-registry   82s   1          Ready

By default a deployed service is not available to the public internet, it needs to be exposed using kalix service expose customer-registry

Since this is just a sample, let’s not publish it to the world. It is also possible to create a proxy connection from your local machine, giving us access to the service without exposing it to the internet, let’s try that out:

$ kalix service proxy customer-registry --grpcui

Creating the proxy forwards port 8080 from the local machine to the running service, so we can hit it with a client, on the command line we can use curl for plain HTTP or grpcurl for gRPC calls, but the additional parameter --grpcui here gives us a nice web-UI to explore and do sample calls to our running service.

All the available methods of the deployed service can be seen in the method drop-down, each allowing triggering a call directly from your browser.

You should now be well set up to further explore what is possible with Kalix. Here are a few starting points in the documentation:

• Exposing a service to the public internet
• Map the gRPC services to nice HTTP/json endpoints
• Publishing and subscribing events to a message broker
• Querying state using views
• Fine grained service access control using ACLs

Next steps

Visit Kalix.io to learn more or register for a free trial.