Deploy Meko on AWS
Before you start, you have the IAM keys, the OpenAI key, the OIDC client, and a prepared cluster.
Get the install command
Register an environment of kind meko in the Meko console. The console shows an install command for it with the chart version and image tags of the current release already filled in. It also shows the reconcile agent's API key, once. Copy it into AGENT_API_KEY straight away. The console can revoke the key but can't show it again.
Your Meko contact gives you the console address and your license file. Apply the license to the cluster, in the namespace named by NS in the command's header, before you run the command.
The command is a block of shell. It starts with a header of values, and the rest is pasted as it is.
Edit the database definition
The database is a YugabyteDB universe that an operator creates from a definition file, the Foundation. The file ships in the Meko chart, in a proof-of-concept size and a production size. Pull the chart at the version in the install command (CHART_VERSION), using the Quay credentials from your license, and copy the file for your SIZE:
NS='<namespace>' # the NS value in the install command
export HELM_REGISTRY_CONFIG="$(mktemp -d)/registry.json" # keeps the token out of your own helm config
kubectl -n "$NS" get secret quay-registry-creds \
-o go-template='{{index .data ".dockerconfigjson" | base64decode}}' >"$HELM_REGISTRY_CONFIG"
helm pull oci://quay.io/yugabyte/charts/meko --version <CHART_VERSION> --untar -d meko-chart
rm -r "$(dirname "$HELM_REGISTRY_CONFIG")"; unset HELM_REGISTRY_CONFIG
cp meko-chart/meko/foundation/meko-foundation-cr.yaml foundation-cr.yaml # poc
cp meko-chart/meko/foundation/meko-foundation-cr-prod.yaml foundation-cr.yaml # prod
The file is set up for Google Cloud, so change every value marked REPLACE:
| Field | Set it to |
|---|---|
spec.yba.values.yugaware.defaultUser |
A username, email, and a new password for the database's management account. Don't keep Password#123. |
spec.yba.values.yugaware.storageClass |
Your storage class, for example meko-gp3 |
YBProvider cloudInfo.kubernetesProvider |
eks |
YBProvider regions |
Your Region code and its zone codes, for example us-east-1 with us-east-1a, us-east-1b, us-east-1c |
YBProvider zone kubernetesStorageClass |
Your storage class, in every zone |
YBUniverse placementInfo |
The same Region and zones. They must match the provider. Put one node in each of three zones, or all three in one zone. |
spec.yba.values.image.repository |
The repository Meko support names for the YugabyteDB Anywhere image. The robot in your license needs pull access to it. |
YBProvider kubernetesImageRegistry |
The repository Meko support names for the database image. ybSoftwareVersion must be a tag in it. |
YBUniverse kubernetesOverrides.nodeSelector |
Optional, recommended for production: uncomment it and set the label of your database node group, for example eks.amazonaws.com/nodegroup: meko-db. A label that matches no node leaves the database pending. |
Leave the pull secret quay-registry-creds and the database version as they are. The license supplies the credentials for that pull secret.
Keep this file. Every rerun of the install applies it again, and an upgrade starts from it: you copy your edits into the new release's file.
Fill in the header
Set NS to the namespace you applied your license in, SIZE to poc or prod, FOUNDATION_CR to the path of your edited file, and the values you collected:
NS='<namespace>' # filled in by the console; the namespace your license is applied in
SIZE='poc'
FOUNDATION_CR='./foundation-cr.yaml'
BEDROCK_KEY='<aws access key id>'
BEDROCK_SECRET='<aws secret access key>'
BEDROCK_REGION=us-east-1
KB_S3_BUCKET='meko-kb-store'
LANGFUSE_S3_BUCKET='meko-traces-store'
LANGFUSE_S3_REGION='us-east-2'
LANGFUSE_S3_KEY='<aws access key id>'
LANGFUSE_S3_SECRET='<aws secret access key>'
LANGFUSE_OWNER_EMAIL='you@example.com'
OPENAI_KEY='<openai api key>'
OIDC_ISSUER_URL='https://idp.example.com/realms/meko'
OIDC_CLIENT_ID='<client id>'
OIDC_CLIENT_SECRET=''
PUBLIC_URL='' # production: https://meko.example.com
ACM_CERT_ARN='' # production: the certificate's ARN
AGENT_API_KEY='<shown once by the console>'
Leave the tags and CHART_VERSION as the console filled them. Leave PUBLIC_URL and ACM_CERT_ARN empty for a proof of concept. For production, set both. The install checks the header and stops before it creates anything if a required value is empty, or if the values contradict each other.
Run it
Paste the whole command into a bash or zsh terminal that has kubectl pointed at the cluster, and aws signed in. The install runs in steps. It stops at the first one that fails, and it is safe to run again.
The steps are numbered as in the install's own messages, so an error such as step 3: the database is not Ready names the step below.
-
Before step 1. The install checks the header and that your license's three Secrets are in
NS. It stops if anything is missing, before it creates anything. -
Step 1, secrets. Creates the Secret that holds the reconcile agent's key.
-
Step 2, load balancer. Creates the internal ALB and waits for its address, which takes a few minutes. It then prints Meko's address and the two URIs to register:
Register these on your OIDC client before the first sign-in: redirect URI: <address>/api/v1/auth/oidc/callback post-logout redirect URI: <address>Register them in your identity provider now if you haven't. In production, create the DNS record for your host name too.
-
Step 2b, bucket CORS. Part of step 2. Adds the rule that lets the UI upload to the knowledge-base bucket, using your AWS credentials. If it can't, it prints the rule for you to add.
-
Step 3, database. Installs the database operator and applies your definition. YugabyteDB takes 20 to 40 minutes to come up. The install waits up to an hour.
-
Step 4, Meko stack and reconcile agent. Installs Meko with the values you set.
When it finishes, it prints Installed SIZE=… into <namespace>.
To change a value later, change the header and run the install command again. Don't run helm upgrade on the Meko release by itself. See Upgrade.
Give the agent its token
The environment shows as degraded in the console until the reconcile agent has an API key of its own, because the API server authenticates every call.
-
Sign in to Meko at the address as the user you kept for the agent, not as yourself.
-
Open Settings → API Keys and create a key.
-
Store it for the agent and restart the agent.
<namespace>is the namespace the install used, which it printed at the end:kubectl -n <namespace> create secret generic meko-reconcile-agent-token \ --from-literal=meko-api-token=<key> kubectl -n <namespace> rollout restart deploy/meko-reconcile-agent
The datapacks the agent creates belong to its account. People see them when you share them from it. Invite emails are off, so a shared datapack appears under the recipient's incoming shares and nobody is emailed.
Check the install
kubectl -n <namespace> rollout status deploy/meko-api-server
kubectl -n <namespace> get pods
kubectl -n <namespace> logs deploy/meko-reconcile-agent
From a network that can reach the ALB:
curl -sI <address> | head -1
A 200 or a redirect to your identity provider means the load balancer and the UI are up. Then sign in, and check that the environment shows as healthy in the console.
To connect an agent over MCP, use <address>/mcp with a key from Settings → API Keys.
If something fails
| Symptom | Cause | Fix |
|---|---|---|
| Stops at the start with "The Meko license is not applied" | One of the license's Secrets is missing from NS, or lacks its key. The message names it. |
Apply the license in NS as in Apply your Meko license, then rerun. |
| Stops at the start with "no alb IngressClass" | The AWS Load Balancer Controller isn't installed. | Install it, then rerun. |
| Stops at step 2 with "The ALB has no address yet" | The private subnets lack the kubernetes.io/role/internal-elb=1 tag, or the load balancer controller isn't healthy. kubectl -n <namespace> describe ingress meko-ui-ingress shows why. |
Tag the subnets or repair the controller, then rerun. |
| Uploads from the UI fail, but uploads through MCP work | The bucket's CORS rule is missing. | Add the rule the install printed, as in CORS on the knowledge-base bucket. |
The database pods stay Pending |
The nodes are too small, the nodeSelector label matches no node, or the storage class can't provision. kubectl -n <namespace> describe foundation foundation shows the operator's reason. |
Add or enlarge nodes to the size you chose, correct the label or the storage class in your definition file, then rerun. |
| Sign-in fails with a redirect error | The redirect URI at your identity provider doesn't match <address>/api/v1/auth/oidc/callback exactly. |
Register the URI the install printed, exactly, in your identity provider. |
| Memory features return nothing | OPENAI_KEY is invalid, or the project can't use gpt-5-mini. |
Fix the key or the project's model access (Get an OpenAI key), put the key in OPENAI_KEY, then rerun. |
| Knowledge-base uploads are never indexed | BEDROCK_KEY lacks a permission, or Titan embeddings aren't available in BEDROCK_REGION. |
Check the keys, enable the model in that Region, and rerun if you changed a key. |