Installation guide

This guide installs AlchemiStudio on a Rancher Prime–managed RKE2 cluster (SUSE AI). It matches the validated end-to-end deployment.

1. Prerequisites

A running RKE2 cluster managed by Rancher Prime (see Requirements).
Longhorn storage class available.
A DNS name pointed at the cluster ingress, and a TLS strategy (BYO cert, ACME, or self-signed).
Image-pull credentials for the publisher registry (or a mirror for air-gapped installs).

2. Create the namespace and pull secret


kubectl create namespace alchemi
kubectl -n alchemi create secret docker-registry alchemi-registry \
  --docker-server=<REGISTRY> \
  --docker-username=<USER> \
  --docker-password=<TOKEN>

3. Install the chart

Rancher UI: Apps › Charts › AlchemiStudio Platform › Install → complete the guided form (domain, TLS mode, storage class longhorn, component toggles) → install into alchemi.

Helm CLI:


helm install alchemistudio-platform \
  oci://<PUBLIC_HELM_REPO>/alchemistudio-platform --version 1.0.23 \
  --namespace alchemi \
  --set global.domain=ai.example.com \
  -f values-suse.yaml

The install deploys, in order: the data tier (PostgreSQL/pgvector, Redis, APISIX + etcd, OpenObserve), Keycloak (realm + clients), then the app tier, running database migration and seed jobs automatically.

4. Verify


# All pods should reach Running / Completed
kubectl -n alchemi get pods
 
# Gateway has an address
kubectl -n alchemi get svc -l app.kubernetes.io/name=apisix
 
# Migration & seed jobs succeeded
kubectl -n alchemi get jobs

Then browse to https://<your-domain> and sign in through Keycloak. A successful login exercises the full path: load balancer → TLS → APISIX → Keycloak → web → database.

5. TLS options

Mode	Use for
BYO (default)	Provide your own certificate/secret
ACME	Automatic Let’s Encrypt via HTTP-01 (validated live)
Self-signed	Lab only — browser trust prompts; not for login-critical use

6. Post-install

Configure model serving — see Model serving.
Wire observability & security — see Observability, security & storage.
Provide provider secrets (LLM API keys, SMTP) via values, or via OpenBao + External Secrets Operator.

Troubleshooting

Symptom	Cause / fix
Pods `ImagePullBackOff`	Pull secret missing/expired — recreate `alchemi-registry` (step 2)
APISIX service `<pending>`	No LoadBalancer provisioned — configure your L4/L7 front end, or use `rke2-ingress-nginx` (hostPort 80/443) for a quick test
Login fails / redirect loop	`global.domain` must match the DNS name and TLS cert; the form derives Keycloak hostnames and redirect URIs from it
Shared-file features fail (EACCES)	Ensure the RWX (Longhorn share-manager) mount is present