Containerizing Kogito Services in Aletyx Enterprise Build of Kogito and Drools 10.0.0¶

This guide walks through deploying Aletyx Enterprise Build of Kogito services in containerized environments using Docker. You'll learn how to build optimized containers, configure database connectivity, and integrate with the Management Console.

Prerequisites¶

Before you begin, ensure you have:

Docker installed (version 20.10 or later)
Docker Compose (version 2.0 or later)
JDK JDK 17 installed for building the application
Maven 3.9.6 for project management
A Kogito project built with Quarkus

Building Optimized Containers for Kogito Services¶

Understanding the Container Structure¶

A well-designed Kogito container should:

Use a lightweight base image (An Open JDK 17-based image)
Properly organize application layers for efficient caching
Configure appropriate security settings
Set up environment-specific configurations

Dockerfile Explained¶

Here's a recommended Dockerfile for Kogito services:

FROM --platform=linux/amd64 eclipse-temurin:17-jre-alpine

# Set the working directory
WORKDIR /deployments

# Configure environment variables for runtime
ENV LANGUAGE='en_US:en'
ENV JAVA_OPTIONS="-Dquarkus.http.host=0.0.0.0 -Djava.util.logging.manager=org.jboss.logmanager.LogManager"
ARG QUARKUS_PROFILE=compose

# Set environment variable from build arg
ENV QUARKUS_PROFILE=${QUARKUS_PROFILE}

# Copy application files with proper layering for better caching
COPY target/quarkus-app/lib/ /deployments/lib/
COPY target/quarkus-app/*.jar /deployments/
COPY target/quarkus-app/app/ /deployments/app/
COPY target/quarkus-app/quarkus/ /deployments/quarkus/

# Create a non-root user for security
RUN addgroup -S kogito && adduser -S kogito -G kogito \
    && chown -R kogito:kogito /deployments

# Switch to non-root user
USER kogito

# Expose the application port
EXPOSE 8080

# Set the entrypoint with profile configuration
ENTRYPOINT [ "java", "-Dquarkus.profile=${QUARKUS_PROFILE}", "-jar", "/deployments/quarkus-run.jar" ]

Key Components Explained:¶

Base Image: eclipse-temurin:17-jre-alpine provides a lightweight JRE 17 environment on Alpine Linux
Workdir: Creates a dedicated directory for application files
Environment Variables: Sets up language and JVM options
Layering: Organizes application files in layers to optimize Docker caching
Security: Creates and uses a non-root user for running the application
Ports: Exposes port 8080 for application access
Entrypoint: Configures the command to start the application with profile-specific settings

Docker Compose for Multi-Container Deployment¶

For a complete deployment, we'll use Docker Compose to orchestrate our Kogito service, PostgreSQL database, and Management Console containers.

Full Docker Compose Configuration¶

version: "3.8"

services:
  kogito-service-postgres:
    build:
      context: ./docker-compose/postgres
    platform: linux/amd64
    ports:
      - "5432:5432"
    environment:
      POSTGRES_DB: postgres
      POSTGRES_USER: kogito
      POSTGRES_PASSWORD: kogito
      LANG: en_US.utf8
    volumes:
      - postgres_data:/var/lib/postgresql/data
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U kogito"]
      interval: 10s
      timeout: 5s
      retries: 5

  kogito-service:
    build:
      context: .
      dockerfile: Dockerfile
    environment:
      QUARKUS_PROFILE: compose
      POSTGRESQL_SERVICE: kogito-service-postgres
      QUARKUS_DATASOURCE_USERNAME: kogito
      QUARKUS_DATASOURCE_PASSWORD: kogito
      QUARKUS_DATASOURCE_DATABASE: kie
      QUARKUS_DATASOURCE_PORT: 5432
      QUARKUS_DATASOURCE_JDBC_URL: jdbc:postgresql://kogito-service-postgres:5432/kie
      KOGITO_SERVICE_URL: http://localhost:8080
      KOGITO_JOBS_SERVICE_URL: http://localhost:8080
      KOGITO_DATAINDEX_HTTP_URL: http://localhost:8080
    ports:
      - "8080:8080"
    depends_on:
      kogito-service-postgres:
        condition: service_healthy

  kogito-service-management-console:
    container_name: kogito-service-management-console
    image: apache/incubator-kie-kogito-management-console:latest
    ports:
      - 8280:8080
    environment:
      KOGITO_DATAINDEX_HTTP_URL: http://kogito-service:8080
      KOGITO_SERVICE_URL: http://kogito-service:8080
    depends_on:
      kogito-service:
        condition: service_started

  kogito-service-pgadmin:
    container_name: kogito-service-pgadmin
    image: dpage/pgadmin4:latest
    ports:
      - 8055:80
    depends_on:
      - kogito-service-postgres
    volumes:
      - ./docker-compose/pgadmin/servers.json:/pgadmin4/servers.json
      - ./docker-compose/pgadmin/pgpass:/pgadmin4/pgpass
    entrypoint: >
      /bin/sh -c "
      cp -f /pgadmin4/pgpass /var/lib/pgadmin/;
      chmod 600 /var/lib/pgadmin/pgpass;
      /entrypoint.sh
      "
    environment:
      PGADMIN_DEFAULT_EMAIL: [email protected]
      PGADMIN_DEFAULT_PASSWORD: pass
      PGADMIN_CONFIG_SERVER_MODE: "False"
      PGADMIN_CONFIG_MASTER_PASSWORD_REQUIRED: "False"
      GUNICORN_ACCESS_LOGFILE: "/dev/null"

volumes:
  postgres_data:

PostgreSQL Configuration¶

Database Setup¶

For PostgreSQL 16, we need to create a custom Dockerfile to ensure proper initialization. The DDLs required to build the PostgreSQL datasource are included with Aletyx Enterprise Build of Kogito and Drools and can be built with the image:

FROM --platform=linux/arm64 postgres:16

# Create the kogito database and user with appropriate permissions
ENV POSTGRES_USER=kogito
ENV POSTGRES_PASSWORD=kogito
ENV POSTGRES_DB=postgres

# Add SQL scripts to be executed during container initialization
COPY ./sql/*.sql /docker-entrypoint-initdb.d/

An example of the file structure is seen below that helps to build the Docker image for the PostgreSQL database. The docker-compose folder contains the DDLs required to build the databases.

├── Dockerfile
├── README.md
├── docker-compose
│   ├── pgadmin
│   │   ├── pgpass
│   │   └── servers.json
│   └── postgres
│       ├── Dockerfile
│       └── sql
│           ├── 01_init.sql
│           ├── data-audit.sql
│           ├── data-index.sql
│           ├── jobs-service.sql
│           ├── runtime-persistence.sql
│           └── user-tasks.sql
├── docker-compose.yaml
├── pom.xml
└── src
    └── main
        ├── java
        │   ├── listeners
        │   │   └── MinimalClaimListener.java
        │   └── model
        │       └── Policy.java
        └── resources
            ├── META-INF
            │   └── processSVG
            │       └── claim_initiation.svg
            ├── application.properties
            └── claim_initiation.bpmn

Connecting to the Management Console¶

The Management Console is a key component for monitoring and managing your Kogito processes. When connecting your Kogito service to the Management Console, ensure:

The Management Console can access your Kogito service endpoints
Data Index is properly configured to track process instances
Both containers are on the same Docker network

Management Console Configuration¶

In the Docker Compose file, the Management Console container is configured with:

kogito-service-management-console:
  container_name: kogito-service-management-console
  image: aletyx/kogito-management-console:10.0.0
  ports:
    - 8280:8080
  environment:
    KOGITO_DATAINDEX_HTTP_URL: http://kogito-service:8080
    KOGITO_SERVICE_URL: http://kogito-service:8080

The environment variables point to your Kogito service's endpoints, allowing the Management Console to retrieve process instance data.

Application Configuration for PostgreSQL¶

For your Kogito application to connect to PostgreSQL, add the following to your application.properties:

# Database configuration
quarkus.datasource.db-kind=postgresql
quarkus.datasource.username=${QUARKUS_DATASOURCE_USERNAME:kogito}
quarkus.datasource.password=${QUARKUS_DATASOURCE_PASSWORD:kogito}
quarkus.datasource.jdbc.url=${QUARKUS_DATASOURCE_JDBC_URL:jdbc:postgresql://localhost:5432/kie}

# Database initialization
quarkus.hibernate-orm.database.generation=update
quarkus.hibernate-orm.log.sql=false

# Kogito persistence settings
kogito.persistence.type=jdbc
kogito.persistence.proto.marshaller=true

Building and Running the Containers¶

Step 1: Build Your Kogito Application¶

First, build your Quarkus application:

mvn clean package

Step 2: Start the Containers¶

Start all services with Docker Compose:

docker-compose up -d

Step 3: Verify the Deployment¶

Check if all containers are running:
```
docker-compose ps
```
Verify the Kogito service at http://localhost:8080
Access the Management Console at http://localhost:8280
Connect to the database using pgAdmin at http://localhost:8055

Troubleshooting Common Issues¶

Database Connection Issues¶

If your Kogito service cannot connect to PostgreSQL:

Check if the PostgreSQL container is running and healthy:
```
docker-compose ps kogito-service-postgres
```

Verify network connectivity between containers:

docker-compose exec kogito-service ping kogito-service-postgres

Examine logs for connection errors:
```
docker-compose logs kogito-service
```

Management Console Not Displaying Process Instances¶

If the Management Console doesn't show process instances:

Verify the Data Index URL is correct in the Management Console environment
Check if your Kogito service has the required persistence configuration
Ensure process instances have been created and are being tracked

Performance Optimization¶

Container Resource Limits¶

Add resource constraints to optimize container performance:

kogito-service:
  # ...existing configuration...
  deploy:
    resources:
      limits:
        cpus: '1'
        memory: 1G
      reservations:
        cpus: '0.5'
        memory: 512M

JVM Tuning¶

Optimize JVM settings for containerized environments:

# Add to Dockerfile ENV section
ENV JAVA_OPTIONS="-Dquarkus.http.host=0.0.0.0 -Djava.util.logging.manager=org.jboss.logmanager.LogManager \
                  -XX:MaxRAMPercentage=80.0 -XX:+UseContainerSupport \
                  -XX:+ExitOnOutOfMemoryError -XX:+AlwaysPreTouch"

Security Considerations¶

Securing Database Credentials¶

For production deployments, avoid hardcoding credentials:

Use a secrets management solution such as Docker secrets
Consider environment-specific configurations
Implement proper access controls for database users

Container Hardening¶

Additional security measures for production:

# Add to Dockerfile
# Remove unnecessary packages
RUN apk --no-cache del curl unzip && \
    rm -rf /var/cache/apk/*

# Apply security updates
RUN apk --no-cache upgrade

# Set read-only filesystem where possible
VOLUME ["/tmp", "/deployments/data"]

# Add non-root user and proper permissions
RUN addgroup -S kogito && adduser -S kogito -G kogito \
    && chown -R kogito:kogito /deployments

Best Practices¶

Use Multi-stage Builds: For more complex applications, consider multi-stage builds to minimize image size
Implement Healthchecks: Add container health checks to ensure robust deployments
Version Your Images: Tag images with meaningful versions rather than using 'latest'
Centralize Configuration: Use environment variables or config maps for easier management
Log Management: Configure proper logging to facilitate troubleshooting

Next Steps¶

After successfully deploying your containerized Kogito services, consider:

CI/CD Integration: Automate your build and deployment process
Kubernetes Deployment: Scale to a full Kubernetes environment
Monitoring: Add Prometheus and Grafana for comprehensive monitoring
High Availability: Configure clustering and load balancing

For more advanced deployment options, see our Kubernetes Deployment Guide and OpenShift Deployment Guide.

Was this page helpful?