Deploy Apps on the Platform

Applications deployed on top of BullSequana AI commonly support three development areas:

• AI applications that use models, RAG, voice, or agents
• Doc AI applications that convert, extract, classify, or retrieve from documents
• Pipelines that orchestrate repeatable data, ML, and document-processing work

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.

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 An Application Usually Needs

Most applications deployed on BullSequana AI need some combination of:

• BSQAI API access for model inference
• Keycloak-based identity and SSO
• configured S3-compatible storage, either in-cluster or external
• PostgreSQL for operational data
• Gateway API 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 automatic enrollment: the platform CLI renders Argo CD hook jobs that register the component as a Keycloak OIDC client before deployment and clean it up when the component is removed. This is controlled by the component's [sso] enabled value. 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 BSQAI API -- the recommended approach. The BSQAI 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, follow the same Jinja template pattern as existing components: render an SSO configuration 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 CLI-rendered, sealed 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 Gateway API routes, secrets, storage, and dependencies
6. sync and validate in the target environment

How This Fits The Current Platform

The bsqai-platform repository is 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 application, keep the contract with the platform explicit:

• use the BSQAI 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
• AI, Doc AI & Pipelines
• Deployment
• Keycloak SSO integration
• Access and Authentication