Deploy Apps on the Platform

Applications deployed on top of BullSequana AI are typically treated as use cases.

Examples include:

• service desk assistants
• phone support copilots
• text-to-speech services
• document AI pipelines
• retrieval and agent applications

Recommended Background

This page is mainly for developers, AI engineers, and platform engineers who need to package and operate applications on top of BullSequana AI.

Helpful experience includes:

• general software engineering and service delivery
• Docker and local development environments
• Dockerfiles and container image build flows
• Kubernetes basics
• Helm packaging
• GitOps concepts, especially if using Argo CD

Preferred Deployment Path

The preferred production deployment method is Argo CD.

Why:

• it matches the platform’s GitOps operating model
• it keeps application state declarative and reviewable
• it fits the way the platform already manages component delivery
• it gives better control over sync order, dependencies, and drift correction

Supported Deployment Methods

1. Argo CD

This is the recommended method for platform-integrated applications and use cases.

Use it when:

• the application should be operated as part of the platform
• multiple environments need the same deployment pattern
• secrets, sync waves, or dependency ordering matter
• the deployment should be reviewable through Git

2. Helm

Helm is a good packaging format for an application, but in production it is usually best consumed through Argo CD rather than run manually.

Use it when:

• the application already exists as a Helm chart
• you want a clean values-based deployment contract
• Argo CD will reconcile the chart afterward

3. Raw Kubernetes manifests

This is acceptable for simpler workloads, operators, or very specific resources.

Use it when:

• the application is small
• there is no benefit in introducing a chart
• you need direct control over Kubernetes resources

Recommended Rule

Use this hierarchy:

1. Argo CD for production deployment
2. Helm as a packaging mechanism
3. kubectl or raw manifests for simple or low-level cases

What A Use Case Usually Needs

Most applications deployed on BullSequana AI need some combination of:

• CoreAI API access for model inference
• Keycloak-based identity and SSO
• storage in MinIO
• PostgreSQL or ClickHouse depending on the workload
• ingress and DNS exposure
• observability hooks
• optional workflows through Argo Workflows or Temporal

Integrating With Keycloak SSO

If your application needs user authentication, the platform provides a standard path for SSO integration through Keycloak.

For platform-managed components

Built-in platform components use an automatic enrollment model: Terraform generates Argo CD hook jobs that register the component as a Keycloak OIDC client before deployment and clean up when the component is removed. This is controlled by the sso_enable flag in the component's configuration. See the Keycloak component page for the full mechanism.

For custom applications

Custom applications deployed on the platform can integrate with Keycloak in two ways:

1. Use the CoreAI API -- the recommended approach. The CoreAI API already handles authentication, so your application can delegate identity to it without managing a Keycloak client directly.

2. Register a Keycloak client -- if the application needs its own login flow (for example, a standalone web UI), it can register as an OIDC client in the dataplatform realm. This requires:

   • a client ID and secret
   • correct redirect URIs for the application's endpoints
   • the appropriate scopes (typically openid, profile, email)
   • protocol mappers for any claims the application needs (groups, roles, preferred_username)

   For platform-managed deployments, this is best done by following the same Terraform template pattern used by existing components: generate an SSO config secret and setup/cleanup jobs as Argo CD hooks.

What the platform provides

When using Keycloak SSO, the platform provides:

• a configured realm (dataplatform) with identity federation support
• protocol mappers for groups, email, and preferred_username already included in the standard client template
• group-based access control patterns that can be reused across applications
• automatic credential management through Terraform-generated secrets

Typical Delivery Flow

1. build the application container image
2. publish the image to the platform registry path
3. define Helm values or Kubernetes manifests
4. create or register the Argo CD application
5. configure ingress, secrets, storage, and dependencies
6. sync and validate in the target environment

How This Fits The Current Platform

The coreai-platform repository is already structured around generated Argo CD manifests and modular component delivery.

In practice that means:

• the platform uses Git as the desired state source
• Argo CD is the reconciliation engine
• Helm values and manifest templates are normal building blocks
• sync waves and hooks are used when deployment order matters

This is the main reason Argo CD should be the default recommendation for new platform extensions.

Design Guidance For New Apps

When introducing a new use case, keep the contract with the platform explicit:

• use the CoreAI API for AI access
• avoid coupling application code to internal platform components such as LiteLLM
• declare dependencies on storage, databases, and identity clearly
• make deployment artifacts GitOps-friendly from the start

Decision Table

Related Pages

• Use local models via API
• Use cases
• Deployment
• Keycloak SSO integration
• Access and Authentication