Skip to content

Install a deployment

This page takes you from nothing to a running Open Meridian deployment that people sign in to. It assumes you have never installed one. Budget half an hour.

You move between two places:

  • The platform, at https://open-meridian.com. You register deployments and issue one-time codes there.
  • The deployment, which you install into your own Kubernetes cluster. Your data lives here.

The two are separate on purpose. The platform never holds your positions, and it never holds a private key. See Projects and deployments for more.

Before you start

You need:

  • A Kubernetes cluster, with kubectl already pointing at it. A laptop cluster (k3s, Rancher Desktop, kind, Docker Desktop) is fine for trying Open Meridian.
  • helm 3.14 or newer, which meridian doctor checks: an upgrade needs it. The CLI drives your own helm and kubectl; you do not run them yourself.
  • An account on the platform, in a project where you are an Owner or Admin. Signing up and creating a project is free. In someone else's project, its owner can make you an admin.

You do not need to make a key or create a Kubernetes Secret. The deployment makes its own key, and the set-up wizard writes its own Secrets.

Install the CLI

On macOS (Apple silicon or Intel) or Linux (x86_64 or arm64):

curl -fsSL https://open-meridian.com/install | sh

That address redirects to the CLI repository's install.sh. The long form works the same: curl -fsSL https://raw.githubusercontent.com/open-meridian/meridian-cli/main/install.sh | sh.

It checks the download against its published checksum and puts meridian in ~/.local/bin. No sudo is needed. Check it:

meridian --version

Note

meridian never checks for a newer release by itself. Run meridian upgrade when you want the latest. See the command line reference for every command.

1. Check your machine and cluster

meridian doctor

It checks the cluster and your rights in it, Helm's version, a storage class for the deployment's key, that no node is short of disk, that the runtime image can be pulled, that the platform answers, and this machine's clock. It changes nothing. Each problem it finds comes with its fix.

The output looks something like this:

  ok       a cluster is reachable
  ok       helm 3.14 is recent enough
  ok       this account may create deployments in meridian
  ok       this account may create secrets in meridian
  ok       this account may create jobs in meridian
  ok       1 storage class(es) for the key's volume
  ok       node lima-rancher-desktop is not under disk pressure
  ok       the platform at https://open-meridian.com answers
  ok       this machine's clock is within 1s of the platform's
  …

doctor: nothing here would stop an install

If a line says stops, do what it says and run meridian doctor again.

Why the clock matters

The deployment proves who it is with signed, time-limited assertions. A skewed clock fails in a way that looks exactly like a bad key. doctor is the easy way to catch it.

2. Make three decisions

Each is easier to make now than after the install.

Where the database lives.

Choice Use it when What you agree to
One the deployment brings Trying Open Meridian, or developing against it It runs in your cluster and its roles and passwords are made for you. It survives meridian down. It is lost with the cluster, and nobody backs it up unless you turn on backups.
One you already run Anything you depend on Your own Postgres, in Docker or managed by your cloud. You make two roles first.

If you use your own Postgres, create two roles now. The migrating role may create tables; the serving role must not:

CREATE DATABASE meridian;
CREATE ROLE meridian_migrate LOGIN PASSWORD 'a-password-you-choose';
CREATE ROLE meridian_app LOGIN PASSWORD 'another-password-you-choose';
GRANT ALL ON DATABASE meridian TO meridian_migrate;

The wizard tests both roles and names the statement that fixes anything missing.

Each component then connects as a login of its own, so one component's slow query is refused on its own and never holds the database for the rest. Make them with the serving role's password, each a member of the serving role:

CREATE ROLE meridian_lake LOGIN PASSWORD 'the-serving-password' IN ROLE meridian_app;
ALTER ROLE meridian_lake SET statement_timeout = '5s';
-- and the same for meridian_bor, meridian_instrument, meridian_street,
-- meridian_conductor and meridian_dashboard

Until a component's login is made it connects as meridian_app, and each upgrade's check names any not made yet with the statement that makes it. A database the deployment brings is given them for you.

How people reach it.

Choice Use it when What you pass to meridian up
Your own name, through the cluster's ingress Your firm's cluster --host meridian.firm.example and a values file naming your certificates
meridian.localhost A laptop cluster with an ingress controller (Rancher Desktop, Docker Desktop, k3s) Nothing extra
A port-forward A cluster with no ingress controller Nothing extra. meridian up forwards a port when it finds no controller. --no-ingress asks for one anyway.

It must be a name, not an IP address. Each plugin's page is served on its own name below the dashboard's, <instance>.plugins.<host>, so one plugin's page can never act as you on another. For your own name you need DNS for the name and for the wildcard *.plugins.<host>, both pointing at your ingress controller. On a laptop, any name ending in .localhost needs neither.

How people sign in. Your OpenID Connect provider, your LDAP, or accounts the deployment holds itself. You answer this in the wizard, not at install. See Choose how people sign in before you get there.

3. Register the deployment

On the platform:

  1. Sign in and open your project.
  2. Open Deployments and choose Register deployment.
  3. Give it a name you will recognise in a year, such as production or uat, and choose Register.

The deployment now has an identifier that starts DEP-. Copy it with the Copy button beside it. Every step below needs it.

4. Issue an enrolment code

On the deployment you just registered, open its menu and choose Issue enrolment code.

The code is shown once and lasts a day. Copy it now.

This code is what the install carries instead of a key. The deployment makes its own keypair inside your cluster, registers the public half with this code, and the code is spent.

Note

Issuing a second code expires the first. A deployment that already has a key is not offered a code at all, and a retired deployment is refused one.

5. Install

Put the enrolment code in the environment, not on the command line, so your shell history does not keep it. Then run meridian up with your identifier exactly as the platform shows it, DEP- included.

export MERIDIAN_ENROLMENT_CODE=ENR-XXXX-XXXX-XXXX
meridian up --id DEP-XXXXXXXXXXXXXXXXXXXXXXXXXX

It is reached at https://meridian.localhost, and needs no DNS. It is HTTPS because an AI agent signs in to the deployment's MCP over nothing else. The certificate comes from this machine's own certificate authority, which meridian up makes the first time, able to sign names under .localhost and nothing else. Before asking anything it says what the authority is for; on macOS it then offers to add it to your login keychain, and macOS asks for your password itself. Elsewhere it prints the one command that trusts it. meridian authority says where it is, and meridian authority trust trusts it later.

Write a values file naming the Secrets that hold your certificates. Leave out pluginsSecretName if the first certificate covers both names.

ingress.yaml
ingress:
  tls:
    secretName: meridian-tls                 # for the name
    pluginsSecretName: meridian-plugins-tls  # for *.plugins.<the name>

export MERIDIAN_ENROLMENT_CODE=ENR-XXXX-XXXX-XXXX
meridian up --id DEP-XXXXXXXXXXXXXXXXXXXXXXXXXX --host meridian.firm.example -f ingress.yaml

export MERIDIAN_ENROLMENT_CODE=ENR-XXXX-XXXX-XXXX
meridian up --id DEP-XXXXXXXXXXXXXXXXXXXXXXXXXX --no-ingress

meridian up holds a port-forward on http://127.0.0.1:8443 until you press Ctrl-C. Use --port for another port.

meridian up runs meridian doctor first, then installs, waits for the dashboard, and prints the wizard's address. It prints the Helm command it ran, so you can see exactly what it did. The namespace is meridian; -n picks another.

Where older records go

meridian up asks one more question before it installs: where plugins at the edge move their older records, an archive on a directory of the cluster's node, such as a NAS export or a second disk, or none. Answer it with --archive <path> or --no-archive; pressing Enter is none. Naming one allows no plugin an archive by itself. See Keep older records in the archive.

Development deployments

Add --development to make a sandbox for writing plugins. It may then run plugin code as it is being written, which nobody has reviewed, and every page says so. It is set at install and nowhere else. Never use it on a deployment your firm depends on. See Development deployments.

What a correct install looks like

If you watch it come up with meridian status, which lists each component with how many of its pods are ready, how often they restarted and why, some sit in an error. That is expected at this point.

Pods Expect
broker, conductor, dashboard, first-run 1/1. These serve you the wizard.
key Completed. The deployment has made its own keypair.
street, instrument, migrate CreateContainerConfigError, and they stay there.

The last row is not a failure. Those three wait for a database, which the wizard sets up. They retry by themselves and come up a minute or two after you apply the wizard. Nothing needs restarting or deleting.

6. Check the deployment enrolled

On the platform, the deployment now shows Connected and lists a key with a fingerprint. Keep that page open. You compare the fingerprint in step 8.

7. Issue a first-run code

On the same deployment's menu, choose Issue first-run code. It is offered once the deployment shows Connected.

The code is single use and lasts a day. It opens the wizard.

8. Open the wizard

Open the address meridian up printed: https://<your name>/first-run, or https://meridian.localhost/first-run on a laptop.

  1. Compare the fingerprints. The page shows the deployment's identifier and its key's fingerprint. It must match what the platform shows. If it does not, someone else spent your enrolment code: stop, revoke that key on the platform, and start again at step 4.
  2. Enter the first-run code and choose Continue.

9. Answer the wizard

The wizard has five steps: Database, Signing in, Administrators, Address, and Review and apply. Nothing is written until you choose Apply.

  1. Database. Choose Start one inside this cluster, or Use a Postgres you already run and fill in the host, port, database, TLS mode and both roles.
  2. Signing in. Choose one of three and answer only that part. See Choose how people sign in.
  3. Administrators. With a directory, name the directory group whose members run this deployment. Spell it exactly: it is not checked. With no directory, the account you just made is the administrator.
  4. Address. The name your staff will use to reach the dashboard, such as https://meridian.firm.example. Not a 127.0.0.1 port-forward.
  5. Review and apply. Choose Test. It checks every answer the way Apply will, and names what to fix. Fix it and test again. When it is clean, choose Apply.

Applying takes a couple of minutes and restarts what changed.

10. Sign in

  1. If you used a port-forward, stop it with Ctrl-C.
  2. Open the dashboard at the address you gave it and sign in. The administrators you named hold deployment admin from their first sign-in, and admin on every plugin through All plugins (admin): configuring plugins, not reading their data. See Access.

  3. Sign the CLI in as yourself, so you can bring in plugins from a terminal:

    meridian connect https://meridian.firm.example

    On a laptop, just meridian connect: with no address it signs in to https://meridian.localhost, where meridian up puts a deployment. It opens the deployment's own sign-in in your browser and never takes a password. It then asks you to let the CLI on this computer act as you: choose Allow. That is a delegation of everything you hold, for 90 days unless you choose less, and the CLI keeps its access fresh by itself until then. See meridian connect.

That is the install finished.

Answering the wizard from a file

For a scripted install, meridian up --params first-run.yaml posts the same answers to the wizard, behind the same first-run code. The file holds no password: each one is read from a MERIDIAN_<FIELD> variable instead. See Choose how people sign in and the command line reference.

Next steps