Quick Start

Alpha version — The annotation API and interfaces may change without backward compatibility. Not recommended for production use.

Prerequisites

JDK 21+ and Gradle 8+ (or use ./gradlew)
Docker and Docker Compose

Install the starter

Clone or download quatrion-starter:


git clone https://github.com/mderkowski82/quatrion-starter.git
cd quatrion-starter

Option 1 — Dev mode (hot-reload)

Infrastructure required — before starting the backend or frontend you must first launch Docker Compose, which provides the PostgreSQL database and Keycloak.

The docker-compose.infra.yml file is located in the quatrion-starter directory of the quatrion-starter repository. Make sure you have cloned the repository and are inside that directory, then run:


docker compose -f docker-compose.infra.yml up -d

Make sure Docker Desktop (or Docker Engine) is running on your machine.

Start infrastructure (PostgreSQL + Keycloak)


docker compose -f docker-compose.infra.yml up -d

Start backend with live reload


./gradlew quarkusDev

URL	Service
`http://localhost:8080`	Backend API
`http://localhost:8080/q/swagger-ui`	Swagger UI
`http://localhost:8180`	Keycloak Admin (`admin` / `admin`)

Environment variables

Copy .env.example → .env and fill in:

Variable	Description
`PORTAL_DB_USER` / `PORTAL_DB_PASSWORD`	PostgreSQL credentials
`KEYCLOAK_CLIENT_SECRET`	Keycloak frontend client secret
`KEYCLOAK_BACKEND_CLIENT_SECRET`	Keycloak backend service account secret
`AUTH_SECRET`	Auth.js signing secret (`openssl rand -hex 32`)
`LICENSE_KEY`	Quatrion Portal license key

Frontend

The frontend must be built manually from the source code available at: https://github.com/mderkowski82/quatrion-frontend


git clone https://github.com/mderkowski82/quatrion-frontend.git
cd quatrion-frontend
npm install
npm run build
npm start

Default Keycloak accounts (dev)

User	Password	Role
`admin@example.com`	`admin123`	`portal-admin`
`user@example.com`	`user123`	`portal-user`

Project structure

- docker-compose.yml
- docker-compose.infra.yml
- Dockerfile
- keycloak/realm-export.json
- .env.example

Adding your first entity

Step 1 — Create a JPA entity with Quatrion annotations:


// src/main/kotlin/com/example/portal/entity/Customer.kt
@Entity @Table(name = "customer")
@PortalEntity(label = "Customer", module = "CRM", icon = "users", order = 1)
class Customer {
    @Id @GeneratedValue(strategy = GenerationType.IDENTITY)
    var id: Long = 0
 
    @Column(length = 100, nullable = false)
    @PortalField(label = "Name", order = 1, required = true,
        renderer = RendererType.TEXT, filterType = FilterType.CONTAINS)
    var name: String = ""
 
    @Column(length = 200)
    @PortalField(label = "Email", order = 2,
        renderer = RendererType.EMAIL, filterType = FilterType.CONTAINS)
    var email: String = ""
}

Step 2 — Register in AppModuleConfig:


@ApplicationScoped
class AppModuleConfig : PortalModuleConfig() {
    override fun modules() = listOf(
        ModuleDef(
            name = "CRM", label = "CRM", icon = "users", order = 1,
            defaultEntity = Customer::class.java,
            entities = listOf(EntityRef(entityClass = Customer::class.java, order = 1))
        )
    )
}

That’s it — the full CRUD UI (table, form, filters, search, export) is generated automatically.