Deploy Rocket.Chat AI Pipeline Server and Mongo Connector

This guide walks you through deploying Rocket.Chat AI pipeline and the Mongo Connector on a k3s Kubernetes cluster using the S3 deployment bundle provided by Rocket.Chat. The deployment bundle contains everything required to install Rocket.Chat AI, including the deployment repository, Helm charts, container images, configuration templates, and the Mongo Connector deployment assets.

Rocket.Chat AI supports multiple deployment options, including Docker, other Kubernetes distributions (such as kind and Minikube), and private container registries like Amazon ECR and GitHub Container Registry (GHCR). This guide focuses on deploying Rocket.Chat AI on a k3s cluster using the S3 deployment bundle.

Part 1 : Deploy Foundation4AI

The first step in setting up your Rocket.Chat AI pipeline is the deploying the Foundation4AI server.

Step 1: Prepare a namespace

1. Create the target namespace:

   kubectl create namespace foundation4ai

2. Create a .env file in the deployment directory for just:

   cat > .env <<'EOF'
   CLUSTER=
   NAMESPACE=foundation4ai
   EOF

   Leave CLUSTER empty if your current kube context already targets the right cluster.

Step 2: Get your deployment assets

1. Download and verify the bundle:

   curl -L "<signed-s3-url>" -o foundation4ai-customer-bundle.zip
   shasum -a 256 foundation4ai-customer-bundle.zip

   Verify that the printed checksum matches the value provided by Rocket.Chat support before proceeding.  

2. Extract the bundle and verify the included deployment assets.

   unzip foundation4ai-customer-bundle.zip
   cd foundation4ai-customer-bundle-*
   shasum -a 256 -c checksums.txt 
   # or, if shasum isn't available:
   # sha256sum -c checksums.txt

3. Prepare the deployment files:

   unzip deployment/foundation4ai-deployment.zip \
       -d foundation4ai-deployment
   cd foundation4ai-deployment
   cp ../examples/foundation4ai.values.example.yaml \
      foundation4ai.values.yaml

   Do not start from an older values file. The image names and tags in foundation4ai.values.yaml must match the images you loaded or pushed.

The above steps may differ if your image source is different.

Step 3: Load the container images

The deployment bundle includes all required container images as compressed image archives (.tar files). Before deploying, import these images into the container runtime used by your k3s cluster.

This guide assumes your k3s cluster uses the default containerd runtime. If you're using a different container runtime, refer to its documentation for importing container images.

1. From the root directory of the extracted deployment bundle, import each image into k3s:

   # Load the platform and core model images
   for image in ../images/*.tar; do
     sudo k3s ctr -n k8s.io images import "$image"
   done
   
   # Load the Mongo Connector images
   for image in ../connector/images/*.tar; do
     sudo k3s ctr -n k8s.io images import "$image"
   done

2. After the import completes, verify that the images are available in the k3s container runtime.

   sudo k3s ctr images ls

Step 4: Configure Foundation4AI

Because images are loaded directly onto the k3s host container runtime, you must configure the charts to look for local images rather than attempting to pull them from the public internet.  

Navigate to foundation4ai-deploymentdirectory and open the foundation4ai.values.yaml :

1. Set the pullPolicy:Never for every image reference.

2. Update the repository for all images to match the imported image names from the bundle.

3. Enable PostgreSQL:

   postgres:
     enabled: true

4. Set the storageClass:

   nats:
     config:
       jetstream:
         fileStore:
           pvc:
             storageClassName: <your-storage-class>

   A missing or unbound StorageClass is the most common reason NATS pods stay pending.

Step 5: Configure the secrets file

1. Copy the secrets template included in the foundation4ai-deploymentdirectory:

   cp foundation4ai.secrets.env.template foundation4ai.secrets.env

2. For the first deployment, set FOUNDATION4AI_APP_LICENSE to a temporary placeholder such as placeholder-license. You'll replace this value with your production license after retrieving your system ID later in this guide.

3. Generate the following application secrets required for the deployment with the commands below:

   1. FOUNDATION4AI_APP_MASTER_KEY: This is the master key UUID, used as the API login username.

      python3 -c "import uuid; print(uuid.uuid4())"

   2. FOUNDATION4AI_APP_SECRET: The Fernet key used for internal encryption.

      python3 -c "from cryptography.fernet import Fernet; print(Fernet.generate_key().decode())"

   3. FOUNDATION4AI_APP_MASTER_SECRET: A strong master secret, used as the API login password.

      python3 -c "import secrets; print(secrets.token_urlsafe(48))"

Step 6: Configure PostgreSQL and Redis

1. Foundation4AI requires a PostgreSQL database.

   1. If you're using the bundled PostgreSQL deployment, configure the database credentials in foundation4ai.secrets.env:

      POSTGRES_DATABASE=foundation4ai
      POSTGRES_USER=foundation4ai
      POSTGRES_PASSWORD=<strong-password>
      POSTGRES_SUPERUSER_PASSWORD=<strong-password>

   2. If you're using an external PostgreSQL instance, update the PostgreSQL connection string instead:

      POSTGRES_URL=postgresql://<user>:<password>@<host>:5432/<database>

2. Set a password for the bundled Redis:

   REDIS_PASSWORD=<strong-password>

Step 7: Create the Kubernetes secret

After updating foundation4ai.secrets.env, create the Kubernetes secret:

just create-secrets

Step 9: Deploy Foundation4AI

1. From the foundation4ai-deploymentdirectory, run:

   just deploy-core

   The deployment may take several minutes to complete depending on your cluster and network.

2. Confirm that all Foundation4AI Core resources have been deployed successfully:

   kubectl get pods -n foundation4ai
   kubectl get pvc -n foundation4ai

3. After Foundation4AI Core is running, retrieve the unique System ID for your deployment.

   just system-id

   If you loaded images from an S3 bundle , use this instead:

   kubectl -n foundation4ai delete job get-system-id --ignore-not-found
   
   kubectl -n foundation4ai apply -f - <<'EOF'
   apiVersion: batch/v1
   kind: Job
   metadata:
     name: get-system-id
   spec:
     template:
       spec:
         restartPolicy: Never
         containers:
           - name: get-system-id
             image: <your-api-image>:<tag>
             imagePullPolicy: Never
             env:
               - name: FOUNDATION4AI_DATABASE_URL
                 valueFrom:
                   secretKeyRef:
                     name: foundation4ai-secrets
                     key: FOUNDATION4AI_DATABASE_URL
             command: [sh, -c]
             args:
               - |
                 for bin in ./foundation4ai /app/foundation4ai_v1 /app/foundation4ai; do
                   [ -x "$bin" ] && { "$bin" database migrate && "$bin" license system-id; exit $?; }
                 done
                 echo "Binary not found" && exit 1
   EOF
   
   kubectl -n foundation4ai wait --for=condition=complete job/get-system-id --timeout=120s
   kubectl -n foundation4ai logs job/get-system-id | grep -v '^Migrated'
   kubectl -n foundation4ai delete job get-system-id

4. Send your System ID to your Rocket.Chat representative or support team to obtain a Rocket.Chat AI license. You'll receive a license string that is tied to your deployment.

5. Once you have the license, open foundation4ai.secrets.env and update the license:

   FOUNDATION4AI_APP_LICENSE=<your-license>

6. Once you've updated foundation4ai.secrets.env, create the Kubernetes secret:

   just create-secrets

   Verify that the secret was created succesfully:

   kubectl get secret foundation4ai-secrets -n foundation4ai

7. Reapply the secrets and deploy:

   just create-secrets
   just deploy-core
   just deploy

8. Verify the application pods:

   kubectl get pods -n foundation4ai
   kubectl get deploy -n foundation4ai
   kubectl get jobs -n foundation4ai

   You should see:

   1. API server pods running

   2. worker pods running

   3. dashboard pod running

   4. migration, license, and admin-key jobs completed

Access Foundation4AI

After the deployment completes, access the Foundation4AI API and dashboard using one of the following methods:

kubectl -n foundation4ai port-forward svc/foundation4ai-api-server 8000:80
kubectl -n foundation4ai port-forward svc/foundation4ai-dashboard 3000:80

Log in to the Foundation4AI dashboard

Open the Foundation4AI dashboard in your browser:

• If you're using port forwarding, navigate to http://localhost:3000.

• If you configured an ingress or Gateway API, use the hostname you configured for the dashboard.

Log in using the Master API Key and Master Secret generated during Step 5. After signing in, you should see the Foundation4AI dashboard.

Part 2 : Deploy Rocket.Chat Mongo Connector

Rocket.Chat AI pipeline is now deployed and ready to process documents. The next steps configure the Rocket.Chat Mongo Connector to ingest conversations into Foundation4AI.

If you received the S3 customer bundle, use the bundled connector chart and images. This avoids separate GHCR chart/image access and gives you a single handoff artifact. The S3 bundle contains:

• connector/charts/rocketchat-ai-mongo-connector-0.1.1-0504c58.tgz

• connector/images/rocketchat-ai-mongo-connector-api_sha-0504c58.tar

• connector/images/rocketchat-ai-mongo-connector-web_sha-0504c58.tar

• connector/examples/rocketchat-ai-mongo-connector.values.s3-local-demo.yaml

• connector/examples/rocketchat-ai-mongo-connector.values.registry-import.yaml

• connector/examples/rai-mongo-connector.secret.example.yaml

Step 1: Import the connector images

for image in connector/images/*.tar; do
  sudo k3s ctr -n k8s.io images import "$image"
done

Step 2: Write the connector values file

This path uses SQLite for the connector's control-plane database (matches the single-node setup) and one replica each for the API and web services .SQLite doesn't support multiple API pods writing to it at once.

Create connector-values.yaml:

fullnameOverride: rai-mongo-connector

api:
  replicaCount: 1                    # don't scale past 1 — SQLite can't take concurrent writers
  image:
    repository: ghcr.io/rocketchat/rocketchat-ai-mongo-connector-api
    tag: sha-0504c58
    pullPolicy: Never                
  env:
    databaseBackend: sqlite
    dbPath: /data/control_plane.db
    logLevel: INFO
  secretEnv:
    create: true
    values:
      RAI_MONGO_CONNECTOR_API_KEY: <enter-your key>                  # required
      RAI_MONGO_CONNECTOR_DATA_ENCRYPTION_KEY: <enter-your key>  # protects stored Mongo/pipeline credentials
  persistence:
    enabled: true                    # backs the SQLite file
    size: 20Gi
    mountPath: /data

web:
  replicaCount: 1
  image:
    repository: ghcr.io/rocketchat/rocketchat-ai-mongo-connector-web
    tag: sha-0504c58
    pullPolicy: Never
  api:
    url: /api                        # same-origin browser path, proxied internally to the API service

ingress:
  enabled: false                     

Enter RAI_MONGO_CONNECTOR_API_KEY and  RAI_MONGO_CONNECTOR_DATA_ENCRYPTION_KEY .

Step 3: Install the chart

helm install rai-mongo-connector \
  connector/charts/rocketchat-ai-mongo-connector-0.1.1-0504c58.tgz \
  -n foundation4ai \
  --create-namespace \
  -f connector-values.yaml

Step 4: Verify the connector pods

kubectl get pods -n foundation4ai -l app.kubernetes.io/instance=rai-mongo-connector

You should see one API pod and one web pod running.

Step 5: Access the Mongo connector

Expose the connector using port forwarding.

kubectl port-forward svc/mongo-connector-web 8081:80 -n foundation4ai

Open your browser and navigate to: http://localhost:8081. The Mongo Connector setup page should appear.