Getting Started with Kalix
- Johan Andrén.
- Principal Engineer, Lightbend.
- 23 June 2022,
- 5 minute read
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.
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
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: