Getting started
The Kalix development tools help you to get started quickly. They include:
-
A Maven archetype that generates the recommended project structure. The generated project is a regular Spring Boot project with a few configurations to integrate it seamlessly with Kalix.
-
A Maven plugin to help you deploy your application to Kalix.
The generated project also contains configuration for packaging and deploying the service.
Prerequisites
Before you start, make sure you have the following:
-
JDK 17 or later
-
Apache Maven 3.6 or later
-
Docker 20.10.14 or higher (to run locally)
To deploy the Kalix service, you need:
-
A configured registry in which to publish the service container image. Refer to Configuring registries for more information on how to make your Docker registry available to Kalix.
1. Generate and build the Kalix project
The Maven archetype template prompts you to specify the project’s group ID, name and version interactively. Run it using the commands shown for your OS.
Follow these steps to generate and build your project:
-
From a command window, run the template in a convenient location:
- Linux or macOS
-
mvn archetype:generate \ -DarchetypeGroupId=io.kalix \ -DarchetypeArtifactId=kalix-spring-boot-archetype \ -DarchetypeVersion=1.5.2
- Windows 10+
-
mvn archetype:generate ^ -DarchetypeGroupId=io.kalix ^ -DarchetypeArtifactId=kalix-spring-boot-archetype ^ -DarchetypeVersion=1.5.2
-
Navigate to the new project directory.
-
Open it on your preferred IDE / Editor.
2. Examine the project
The initial project contains a Main
class for a Spring Boot application. The application is already configured to wire and register all Kalix components
it finds in the classpath.
@SpringBootApplication (1)
public class Main {
private static final Logger logger = LoggerFactory.getLogger(Main.class);
public static void main(String[] args) {
logger.info("Starting Kalix Application");
SpringApplication.run(Main.class, args); (2)
}
}
1 | Main class is annotated with @SpringBootApplication . |
2 | The application is started like any other Spring Boot application. |
3. Implementing first component
Kalix have different kinds of components that you can use to implement your application. The list of components are:
For this Getting started walk-through, we will implement a Counter based on a Value Entity. It’s a simple counter that receives commands to increase the counter.
@TypeId("counter") (1)
@Id("counter_id") (2)
public class CounterEntity extends ValueEntity<Integer> { (3)
@Override
public Integer emptyState() { return 0; } (4)
@PostMapping("/counter/{counter_id}/increase") (5)
public Effect<Number> increaseBy(@RequestBody Number increaseBy) {
int newCounter = currentState() + increaseBy.value(); (6)
return effects()
.updateState(newCounter) (7)
.thenReply(new Number(newCounter));
}
}
1 | Every Entity must be annotated with @TypeId with a stable identifier. This identifier should be unique among the different existing entities within a Kalix application. |
2 | The @Id value should be unique per entity and map to some field being received on the route path, in this example it’s the counter_id . |
3 | The CounterEntity class should extend kalix.javasdk.valueentity.ValueEntity . |
4 | The initial state of each counter is defined as 0. |
5 | The method is accessible as a POST endpoint on /counter/{counter_id}/increase , where counter_id will be its unique identifier.
Note that it matches the @Id value. |
6 | Its increaseBy method receives a Number as input and increases the counter by adding it to the current state. |
7 | Finally, using the Effect API, we instruct Kalix to persist the new state, and we build a reply. |
The Number
record in this example is used as input for the increaseBy
method and as to return the
counter’s current state.
package com.example;
public record Number(Integer value) {}
The project also includes a dependency on the Kalix Java SDK Test Kit. Please consult the component specific pages to learn more about writing unit tests and integration tests for your application.
4. Package service
The project is configured to package your service into a Docker image which can be deployed to Kalix. The Docker image
name can be changed in the pom.xml
file’s properties
section. Update this file to publish your image to your Docker repository.
This uses JDK 17 and the image is based on the Eclipse Adoptium JDK image (formerly Adopt OpenJDK). Choose a different image in the docker-maven-plugin
configuration pom.xml
file.
mvn install
For more details see Development Process - Package service. |
5. Run locally
To start your service locally, run:
mvn kalix:runAll
This command will start your Kalix service and a companion Kalix Runtime as configured in docker-compose.yml
file.
If you prefer, you can also start docker-compose directly by running docker-compose up
in one terminal and in another terminal start your Kalix service with:
mvn kalix:run
With both the runtime and your service running, any defined endpoints should be available at localhost:9000
,
the runtime local address.
curl -XPOST -H "Content-Type: application/json" localhost:9000/counter/foo/increase -d '{ "value": 10 }'
6. Deploy to Kalix
To deploy your service to Kalix:
First make sure you have updated the dockerImage
property in the pom.xml
to point at your Docker registry.
Then use the deploy
target to build the container image, publish it to the container registry as configured in the pom.xml
file, and the target kalix:deploy
to automatically deploy the service to Kalix:
mvn deploy kalix:deploy
If you time stamp your image. For example, <dockerTag>${project.version}-${build.timestamp}</dockerTag> you must always run both targets in one pass, i.e. mvn deploy kalix:deploy . You cannot run mvn deploy first and then mvn kalix:deploy because they will have different timestamps and thus different `dockerTag`s. This makes it impossible to reference the image in the repository from the second target.
|
-
When using the CLI, in your command window, you can set your Kalix project to be the current project:
kalix config set project <project-name>
-
Deploy your service following the instructions at Development Process - Deploy to Kalix.