Getting Started with Kalix
Tags: kalix
Published: 2023-02-16 21:58:12

---
description: See how easy it is to get going with Kalix. 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.
---
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](https://docs.kalix.io/kalix/index.html).

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

```bash
$ kalix auth login
```

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

![Kalix Login](https://dev-to-uploads.s3.amazonaws.com/uploads/articles/b5x03yeij53027el0f2q.jpg)

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:

```bash
$ 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](https://docs.kalix.io/java/index.html) or the [TypeScript or JavaScript SDK](https://docs.kalix.io/javascript/index.html).

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:

```bash
$ kalix quickstart list
```

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

```bash
$ 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:

```bash
$ 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.


![Properties](https://dev-to-uploads.s3.amazonaws.com/uploads/articles/ra573f1k18j0z0t3cuto.png)

Build, package and publish the project using maven:

```bash
$ 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:

```bash
[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:

```bash
$ 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:

```bash
$ 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.

![gRPC Web UI](https://dev-to-uploads.s3.amazonaws.com/uploads/articles/kldnuioosxwi1skajiz2.png)

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](https://docs.kalix.io/kalix/using-cli.html#_expose_a_service_route)
*   [Map the gRPC services to nice HTTP/json endpoints](https://docs.kalix.io/java/writing-grpc-descriptors-protobuf.html#_transcoding_http)
*   [Publishing and subscribing events to a message broker](https://docs.kalix.io/java/actions-publishing-subscribing.html)
*   [Querying state using views](https://docs.kalix.io/java/views.html)
*   [Fine grained service access control using ACLs](https://docs.kalix.io/services/using-acls.html)

## Next steps

Visit [Kalix.io](https://kalix.io) to learn more or register for a [free trial](https://console.kalix.io/register).