Getting started

Prerequisites

For this guide you need the following installed:

• JDK >= 21
• Docker >= 19.0.3 (including buildx and compose)

Create an example project

We will create your first backend within minutes.

Quinimbus CLI

It is recommended to use the Quinimbus CLI to manage your Quinimbus projects. Simply download the latest version at the download page and put it somewhere in your PATH.

Simply run the following command:

quinimbus project create myblog

This will create a new Quinimbus project named myblog in the directory myblog.

INFO

There are options available to adjust the project creation, see quinimbus project create -h for more information.

Project structure

Let's take a look at the generated project structure

pom.xml

In the pom.xml you can find some interesting parts.

<properties>
    <project.build.sourceEncoding>UTF-8</project.build.sourceEncoding>
    <maven.compiler.release>21</maven.compiler.release>
    <quarkus.version>3.8.6</quarkus.version>
    <quinimbus.version>0.1-SNAPSHOT</quinimbus.version>
</properties>

In the properties section you can define the version of quinimbus to use. As the example is using Quarkus as base framework you can also define that version to use.

<dependencyManagement>
    <dependencies>
        <dependency>
            <groupId>io.quarkus.platform</groupId>
            <artifactId>quarkus-bom</artifactId>
            <version>${quarkus.version}</version>
            <type>pom</type>
            <scope>import</scope>
        </dependency>
        <dependency>
            <groupId>cloud.quinimbus</groupId>
            <artifactId>bom</artifactId>
            <version>${quinimbus.version}</version>
            <type>pom</type>
            <scope>import</scope>
        </dependency>
    </dependencies>
</dependencyManagement>

Besides the platform BOM from Quarkus there is also the BOM from Quinimbus. That way you have a central place to control the version of the Quinimbus modules. We should skip the specific dependencies in the dependencies section and head over to the build configuration.

<plugin>
    <groupId>org.apache.maven.plugins</groupId>
    <artifactId>maven-compiler-plugin</artifactId>
    <version>3.13.0</version>
    <configuration>
        <parameters>true</parameters>
        <annotationProcessorPaths>
            <path>
                <groupId>cloud.quinimbus</groupId>
                <artifactId>magic-generator</artifactId>
                <version>0.1-SNAPSHOT</version>
            </path>
            <!-- [...] -->
        </annotationProcessorPaths>
        <!-- [...] -->
    </configuration>
</plugin>

The Quinimbus MAGIC generator has to be added to the compiler configuration. This way all the needed classes can be automatically generated. For details please look into the MAGIC configuration

/src/main/resources/application.yaml

This file is the default place for configuration values in Quarkus. Quinimbus can use these values as configuration source so you just have to manage these at one place. Let's look at the Quinimbus specific part.

quinimbus:
    binary:
        stores:
            myblog:
                type: file
                rootPath: ./data/binary
        persistence-integration:
            schemas:
                myblog:
                    store: myblog
    persistence:
        schemas:
            myblog:
                type: record
                classes:
                    - io.company.cloud.myblog.domain.BlogEntry
                    - io.company.cloud.myblog.domain.BlogEntryComment
                    - io.company.cloud.myblog.domain.Category
        storages:
            myblog:
                type: mongo
                schema: myblog
                host: localhost
                username: mongoroot
                password: mongorootpassword

The only configuration part in this example is the one for the persistence and the binary module. You can see the configuration for the schema myblog and the storage myblog.

Java classes

There are just three classes in the domain package describing an example data model, for example the BlogEntry:

@Entity(schema = @Schema(id = "myblog", version = 1))
@GenerateRepository
@GenerateRestEndpoints
@GenerateAdminListView
public record BlogEntry(
        @EntityIdField(generate = @GenerateID(generate = true, generator = "friendly")) String uid,
        @Naming @Searchable String title,
        String text,
        @EntityField(type = String.class) List<String> tags,
        LocalDate published,
        EmbeddableBinary image,
        @References(Category.class) String category) {}

This is a default Java record, annotated with several meta annotations by Quinimbus Persistence and Quinimbus MAGIC. For details please look into the specific documentations (Persistence and MAGIC)

The first deploy

In the generated example project there is also a ready to use Dockerfile, docker-bake.hcl and docker-compose.yml, but it is even easier to simply use the cli again. You can build and start your example project using the following commands.

quinimbus project build-images
quinimbus project run-containers

During the build process MAGIC is generating the required classes and a jar file is generated. The compose stack will start a mongo container and a container for your built application. Also an admin-ui is created using VueJS. There will be an API at port 8080 with several generated endpoints, for example for the blog entries:

• GET /blogEntries will return all saved blog entries as JSON
• POST /blogEntries will allow you to create a new blog entry
• GET /blogEntries/by/title/{title} to get all blog entries with a specific title as JSON
• GET /blogEntry/{uid} will return a specific blog entry as JSON
• PUT /blogEntry/{uid} for replacing a specific blog entry
• DELETE /blogEntry/{uid} is the endpoint to remove a specific entry

If you open http://localhost:8081 you can access the generated admin-ui.

Next steps

• You can define your own data model, see Persistence
• You can define your own API endpoints, see REST
• You can add binary fields to your data model, see Binary
• And many more...

WARNING

This getting started guide is not complete yet, please come back soon.