Deploy the appliance on vCenter

By the end of this page, one virtual machine in your vCenter is serving Celum at https://app.<your-domain>. You can sign in to it as an administrator. Everything Celum needs runs on the same VM:

Harbor, a container registry that already holds every image and chart the onboarding wizard installs;
Authentik, the identity provider for Celum, Harbor and Omni;
OpenBao, a Vault-compatible secret store for cluster secrets;
PowerDNS and CoreDNS, which serve the appliance’s own names, and zones your clusters publish into;
Omni, Talos fleet management (on by default, licensed separately);
the start page at https://home.<your-domain>, which shows the appliance’s health and installs Celum updates.

The appliance needs one thing from your site: a way for clients to resolve its names.

Not what you are looking for? Want to run Celum’s containers on a host you already manage, against your own identity provider? Go to Quickstart. Already have the appliance running and want to add your first cluster? Go to Register a supervisor. Deploying from automation rather than the wizard? Every field below is also a key in Appliance configuration.

What this changes in your environment

The wizard creates one VM. The appliance changes nothing else in vCenter. It contacts none of your clusters until you register one. There is one exception. In the acme-dns01 certificate mode, the appliance uses the DNS provider credentials you supply to create TXT records in your zone. That is how it proves to Let’s Encrypt that you own the domain.

Before you start

vCenter with ESXi 7.0 or later. The appliance uses virtual hardware version 17 and EFI firmware.
Capacity for 8 vCPU, 16 GB RAM and a 120 GB thin disk. These are not padding. Harbor alone asks for 8 GB, and the VM also runs Authentik, PostgreSQL, OpenBao, PowerDNS, Omni and Celum. You can enlarge the disk in vSphere before the first power-on, and the appliance grows its filesystem to fill it.
A port group the VM can join, with a free static address. DHCP works for a trial, but Omni requires a fixed address.
A DNS domain for the appliance, such as celum.example.com. The appliance serves several names under it. See step 3.
An SSH public key. The appliance accepts only key logins over SSH, and it reads the wizard’s answers only on the first boot. Without a key you cannot open a shell to troubleshoot or change the configuration.
A certificate decision. See the next section.

Choose a certificate mode

The mode decides what else you need, so pick it now.

mode	you need	trade-off
`selfsigned` (default)	nothing; optionally your own signing CA	Works immediately. The appliance mints a new CA on every deployment unless you give it a signing CA: browsers, tenant clusters and Talos nodes must trust that CA. Your own CA (a dedicated intermediate, ideally name-constrained to the domain) survives redeploys.
`byo`	a certificate and key covering every appliance name. A wildcard `*.<domain>` is simplest.	The appliance checks coverage before it starts anything.
`acme-dns01`	a DNS provider with API access, plus its credentials	Needs outbound access to Let’s Encrypt, to your DNS provider’s API, and to public DNS resolvers on port 53. Omni is switched off in this mode: ACME certificates stay inside the appliance’s web proxy, and Omni serves its own TLS.

Fields that carry a file take its base64. The wizard’s fields are one line, so a certificate or key pasted as it is loses its line breaks. The appliance refuses a raw PEM at first boot. Encode the file first:

Linux: base64 -w0 chain.pem
macOS: base64 -i chain.pem
PowerShell: [Convert]::ToBase64String([IO.File]::ReadAllBytes((Resolve-Path chain.pem)))

Network access

direction	port	what for
inbound	`443/tcp`	the web UI, the API, the start page, Harbor, Authentik, the secret store and Omni. Browsers need it, and so do your clusters, which pull images from Harbor.
inbound	`80/tcp`	redirects to 443
inbound	`22/tcp`	SSH for administrators. Restrict who can reach it.
inbound, DNS on	`53/udp`, `53/tcp`	the appliance’s own names and the zones it serves
inbound, Omni on	`8090/tcp`, `8100/tcp`, `50180/udp`	Omni’s API, its Kubernetes proxy and the SideroLink WireGuard endpoint
outbound	your clusters’ API servers (usually `6443/tcp`)	Celum managing the supervisors you register

The shape of it

Import → answer → resolve → power on → sign in → activate. Step 2 is the only one with decisions in it.

Step 1 — Import the OVA

Content Library
vSphere Client
govc

Use a Content Library to deploy the same release more than once, or from several vCenters.

In Content Libraries, open or create a library and choose Import item. Select the celum-appliance-<version>.ova file or URL.
Once the import finishes, right-click the item and choose New VM from This Template.
Name the VM and pick a folder, then a compute resource.
Accept the details page. If vCenter warns about advanced configuration options, that is expected: the OVA sets EFI firmware and time sync with the host.
Storage: choose a datastore. Thin Provision is fine.
Networks: map the source network VM Network to your port group.
You arrive at Customize template. Continue with step 2.

Right-click the datacenter, cluster or host where the appliance should run, and choose Deploy OVF Template.
Choose Local file and select the celum-appliance-<version>.ova you received, or paste its URL.
Continue from step 3 of the Content Library tab: name, compute resource, storage, network, Customize template.

With govc, export the deployment spec, fill in the properties, and import without powering on:

govc import.spec celum-appliance-<version>.ova > spec.json
# Edit spec.json:
#   NetworkMapping[0].Network = your port group
#   PropertyMapping: set a Value for each celum.* key you need (see step 2)
govc import.ova -options spec.json -name celum celum-appliance-<version>.ova

Every field in step 2 is a celum.* key. Appliance configuration lists them, and describes the other ways to configure the appliance from automation.

Result: vCenter shows Customize template with six sections: Identity, Networking, TLS, Components, Updates and Advanced.

The Customize template step of the vCenter wizard, listing the six sections Identity, Networking, TLS, Components, Updates and Advanced, and the message All properties have valid values — Customize template, with the two required fields filled in

Step 2 — Answer the deploy wizard

Two fields are required, and both are marked *. Every other field is optional and has a default that works.

1. Identity

field	what to enter
DNS domain *	The domain the appliance serves under, such as `celum.example.com`. Every name is derived from it (step 3).
Administrator email *	Becomes the first administrator in Authentik and Harbor, and Omni’s initial user. You sign in to Celum with it.
Administrator password	Leave blank to have one generated. Either way, it is shown on the console at the end of the first boot and saved on the appliance.
SSH public keys	One or more `ssh-ed25519` or `ssh-rsa` keys, separated by commas. They are authorised for `root`. The same keys seal the escrow bundle, the encrypted copy of the secrets a restore needs.
SSH root password	Leave blank. Setting it turns on password logins over SSH. Use it only if you cannot use a key, and restrict access to port 22 if you do.
Start page user name	`admin` by default. The account for `https://home.<domain>`. It is the page’s own account, not an Authentik user, so the page still works when Authentik does not.
Start page password	At least 12 characters. Leave blank to have one generated and shown with the other credentials.

The top of the Identity section: DNS domain set to celum.example.com and Administrator email set to admin@example.com, both marked with an asterisk — Identity: only the domain and the administrator email are required

2. Networking

Leave the address and the gateway blank to use DHCP. For a static address, fill in:

field	example
IP address	`10.20.30.40`, without a prefix
Prefix length	`24` (the list goes from 8 to 32)
Default gateway	`10.20.30.1`. Required when you set an address.
DNS servers	`10.20.30.2,10.20.30.3`. The upstream resolvers.
DNS search domains	optional

The Networking section with IP address 10.20.30.40, prefix length 24, default gateway 10.20.30.1 and DNS servers 10.20.30.2,10.20.30.3 — Networking with a static address

Use a static address for anything longer-lived than a trial. Your DNS records point at this address, and a DHCP lease that moves breaks every name at once. Omni requires a static address, because Talos nodes dial a SideroLink endpoint that cannot follow a lease.

3. TLS

field	when
Certificate mode	`selfsigned`, `byo` or `acme-dns01`. See Choose a certificate mode.
Certificate (base64)	`byo`. The full chain, leaf first, as base64.
Private key (base64)	`byo`, as base64.
Signing CA certificate (base64)	`selfsigned`, optional. A CA that signs every application’s certificate instead of a CA the appliance generates. Put the signing CA first, then any chain above it.
Signing CA private key (base64)	with the signing CA certificate. Unencrypted PKCS#8, PKCS#1 or EC. The key is stored on the appliance, so use a dedicated intermediate.
ACME account email	`acme-dns01`
ACME DNS provider	`acme-dns01`. A provider code such as `cloudflare`, `route53` or `godaddy`.
ACME provider credentials	`acme-dns01`. The provider’s own variables, comma-separated, such as `CF_DNS_API_TOKEN=...` or `GODADDY_API_KEY=...,GODADDY_API_SECRET=...`

4. Components

field	default	notes
Harbor	on	Also becomes Celum’s default registry for charts and images.
Omni	on	Talos fleet management. See the warning below.
Secret store (OpenBao)	on	Where Celum stores secrets for your clusters, read by External Secrets Operator in each tenant cluster. It unseals itself on every start from a key kept on the appliance.
DNS (PowerDNS + CoreDNS)	on	Serves the appliance’s domain, with a record for every name, plus any extra zones (Advanced). Tenant clusters’ external-dns can write into it. Everything else is forwarded to the DNS servers from Networking.
Enforce IAM	on	You sign in with full rights: the administrator is a member of the administrator group (Advanced), which Celum maps to its Administrators. Anybody else is refused what no policy allows. Off starts Celum in audit-only mode: every signed-in user may do everything, and each decision is only logged.
Air-gap mode	`off`	`off`: an image the appliance’s Harbor cannot serve is fetched from the internet. `strict`: that pull fails, and the node shows an `ImagePullBackOff` naming the image, so the OVA must carry every image your clusters run. Set it once for the whole deployment.

Omni is licensed separately, and it is on by default. Sidero Labs publishes Omni under the Business Source License: it is free for non-production use, and production use needs a contract with Sidero Labs. Leaving Omni on asserts that you are entitled to run it; untick it otherwise. Omni needs a static address, and Talos nodes must trust its certificate: under selfsigned, give them the appliance CA; under byo, a publicly trusted chain needs nothing. Under acme-dns01, the appliance switches Omni off and says why.

5. Updates

field	notes
Registry address	`registry.celum.io`. Leave it unless you were given another.
Registry robot account	Optional. The pull-only account you received with your licence, such as `robot$celum+acme`. With it, the start page lists newer Celum releases and installs one on request. You can also enter it later, on the start page’s Updates tab. Left blank, Celum stays at the version this OVA carries.
Robot account secret	With the account above.

6. Advanced

Change these only when you have a reason to.

field	default	use it when
Image library: S3 endpoint, bucket, access key, secret key	none	Celum’s Image Library should import guest OS images from your bucket. Fill in all four or none. Your clusters’ nodes download from the endpoint directly, so they must reach it and trust its certificate. A read-only key is enough.
Backups: S3 endpoint, bucket, key prefix, access key, secret key	none	The daily OpenBao snapshot should be copied off the appliance. The bucket must exist. The key needs `PutObject`, plus `ListBucket` and `DeleteObject` to keep the newest 30. The snapshot restores only together with the unseal key, which is not copied there.
Backups: escrow recipients	the SSH keys	age (`age1…`) or SSH public keys of the people who can restore this appliance. The secrets a restore cannot do without are encrypted to them whenever they change. Their private keys never touch the appliance.
Harbor project	`celum`	you want mirrored charts and images under another project name: lower-case letters and digits, separated by `.`, `_` or `-`.
Administrator group name	`celum-admins`	your naming convention needs another name. The appliance creates the group in Authentik and maps it to Celum’s Administrators. It cannot be Authentik’s own `authentik Admins`.
Extra DNS zones	none	the appliance should also serve zones such as `apps.example.com` for external-dns to fill
Omni account UUID	generated	you are restoring an existing Omni
Omni initial user	the administrator email
SideroLink endpoint	`<appliance-ip>:50180`	Talos nodes reach the appliance through NAT
Accept the Omni EULA as	blank	you want to accept Sidero Labs’ Omni EULA now. Typing your full name accepts it at first start, recorded with the Omni initial user’s email. Left blank, you accept it in the Omni UI at first login; until then Omni refuses every API call, Celum’s included.
Experimental: PoC nodes and cluster	off	you were asked to. It adds a PoC tab to the start page that creates Talos node VMs on a vCenter and a cluster on them through this appliance’s Omni. Needs Omni.
Full configuration (base64 YAML)	none	you deploy from automation. If you fill it in, the appliance ignores every other field. See Appliance configuration.

Result: you can finish the wizard. Do not power the VM on yet.

Step 3 — Make the names resolve

The appliance serves these names, each on its own address:

name	serves	present when
`app.<domain>`	the Celum UI	always
`api.<domain>`	the Celum API	always
`home.<domain>`	the start page: health, credentials, updates	always
`auth.<domain>`	Authentik sign-in	always
`harbor.<domain>`	the registry	Harbor is on
`vault.<domain>`	the secret store	OpenBao is on
`omni.<domain>`	Omni	Omni is on
`pdns-api.<domain>`, `pdns.<domain>`	the PowerDNS API and its admin UI	DNS is on

Pick one way to make them resolve:

Delegate the domain to the appliance (DNS on). Add an NS record for <domain> in the parent zone, pointing at a name for the appliance, with a glue A record for its address. The appliance answers for every name in the table.
Point clients at the appliance (DNS on). A client whose resolver is the appliance’s address resolves every name with no other DNS.
Create the records yourself. A single wildcard record, *.<domain>, pointing at the appliance covers all of them.

Why now: signing in sends your browser from app. to auth. and back through api.. If any one of those names does not resolve, the sign-in fails partway through.

Using DHCP, so you do not know the address yet? Power on (step 4), read the address from the VM’s Summary tab in vCenter, and create the records then. For a quick trial you can put the names in your workstation’s hosts file instead.

Result: from your workstation, every name in the table that applies to you resolves to the appliance’s address.

Step 4 — Power on and watch the first boot

Power on the VM and open its console. vCenter delivers your wizard answers to the VM at power-on. The appliance writes them to /etc/celum-appliance/appliance.yaml, then configures and starts each component in order, logging its progress to the console. The first boot takes a while: the appliance loads every bundled image and chart into Harbor. When it finishes, the console prints a summary like this:

ADDRESSES
  app        https://app.celum.example.com
  api        https://api.celum.example.com
  home       https://home.celum.example.com
  auth       https://auth.celum.example.com
  harbor     https://harbor.celum.example.com
  ...

CREDENTIALS
  ...

BACK THIS UP
  /etc/celum-appliance/secrets
  ...

The same summary is saved on the appliance at /root/celum-appliance-credentials.txt, readable only by root. The start page at https://home.<domain> shows the same health and addresses once you sign in to it. To follow the progress over SSH instead of the console:

ssh root@<appliance-ip> journalctl -u celum-appliance-bootstrap -f
ssh root@<appliance-ip> celum-appliance status

Result: celum-appliance status lists every stage as done, and the console shows the summary.

Back up /etc/celum-appliance/secrets now, unless the escrow covers it. It holds the secret store’s unseal key and root token, the CA key, Authentik’s secret key and, if Omni is on, the key that encrypts Omni’s data. None of them can be regenerated. With escrow recipients (or SSH keys) set, the appliance keeps an encrypted copy of them and copies it to the backup bucket; the summary says which secrets are escrowed.

Open https://app.<domain>.
You are redirected to https://auth.<domain>. Sign in with the administrator email and the Authentik password from the summary.
You land back in Celum.

If you chose selfsigned without your own signing CA, your browser warns on each name. To stop the warnings, copy /etc/celum-appliance/tls/ca.crt from the appliance and add it to your workstation’s trusted roots. A redeploy mints a new CA. Result: Celum opens on Welcome to Celum, because you have not registered a cluster yet.

Welcome to Celum: no supervisor selected, a choice between Upload a kubeconfig and Set up access first, and an Add your first supervisor drop zone — The first page of a new installation

Open My Profile at https://app.<domain>/iam/me. Your identity-provider groups include celum-admins (or the group name you chose), and it is matched to the IAM group Administrators.

My Profile: celum-admins from the token, matched to Administrators

Step 6 — Activate Celum

Celum is fully usable for 30 days from its first start. A banner counts them down. After that, Celum needs a licence to make changes. Without one it is read-only:

you can still see everything;
every change answers 402 “Celum is not activated”;
the appliance keeps running its bootstrap, backups and certificate renewals.

A licence is bound to this appliance’s installation ID, which Celum makes at its first start. That is why the deploy wizard has no licence field. Activate within the 30 days:

Send the installation ID to Nuvira. Under Settings → Licence, copy the Installation ID. Or choose Download activation request and send that file: it names the installation ID, the Celum version and the appliance’s clock.
Nuvira sends you back a licence, a .celum-license file.
Under Settings → Licence, choose Upload licence file or Paste licence. Celum checks the licence against this installation before it stores it.

The Licence tab showing the installation ID with a copy button, the installed licence and its end date, and the buttons Upload licence file, Paste licence and Download activation request — Settings → Licence: the installation ID to send, and the three actions

UI
Console
API
MCP

Settings → Licence shows the installation ID, the licence and when it ends. It also has Upload licence file, Paste licence and Download activation request.

Over SSH on the appliance:

celum-appliance license request         # the activation request (JSON) to send to Nuvira
celum-appliance license install FILE    # install the licence you received, or pipe it to stdin
celum-appliance license status          # the installation ID and the licence's state

GET /api/license                       state, days left, installation ID
GET /api/license/activation-request    the activation request (JSON)
PUT /api/license                       {"token": "<the content of the .celum-license file>"}

get_license_status, get_license_activation_request, install_license.

Installing a licence and downloading the activation request need license:Update on krn:celum:license:global, which the Administrators group holds. Result: Settings → Licence shows your licence and its end date, and the countdown banner is gone. What happens next:

Nothing phones home. Celum checks the licence on the appliance, against keys built into it, so an air-gapped appliance activates the same way.
Before the licence ends, a banner warns you, 30 days ahead. After a paid licence ends, Celum keeps working for 14 days of grace. A trial licence has no grace. Then Celum is read-only until you install a new licence.
Setting the clock back does not help. Celum judges the licence at the latest time it has already seen.
Restoring Celum’s database needs no licence. Settings → Database Backup → Import stays open while Celum is read-only. A replacement appliance restored from its predecessor’s backup gets the predecessor’s installation ID and licence back, so it needs no new licence.

Verify

https://app.<domain> signs you in through Authentik, without a certificate warning (or with one you expected under selfsigned).
https://home.<domain> signs you in with the start page account and shows every application as running.
https://harbor.<domain> shows the celum project already filled with images and charts. That content came from inside the OVA, so this proves the bundled images loaded.
In Celum, Registries lists appliance-harbor as the default registry for charts and images.
Settings → Licence shows your licence and when it ends.

If you need to undo it

Power off and delete the VM. That is all of it: the appliance created nothing outside itself, apart from DNS records you added and, under acme-dns01, TXT records that exist only while a certificate is being issued. Once you register clusters and onboard them, they pull images from this appliance’s Harbor. Deleting the appliance after that point leaves them unable to pull. Move them to another registry first.

What commonly goes wrong

symptom	cause
The console says there is no configuration and the OVF properties are blank	The VM was deployed without the wizard’s answers. For example, it was cloned from another VM or created without Customize template. Redeploy from the OVA.
The first boot stops with `give the file's base64`	A certificate, key or the full configuration was pasted as it is. Redeploy with the file’s base64, or fix `/etc/celum-appliance/appliance.yaml` over SSH and run `celum-appliance bootstrap`.
The first boot stops with `domain: ... is not a valid DNS domain` or `admin.email: required`	The two required fields. Fix them in `/etc/celum-appliance/appliance.yaml` over SSH and run `celum-appliance bootstrap`. It picks up where it stopped.
The first boot stops with `tls.cert: does not cover ...`	Your `byo` certificate is missing some names. The message lists them. A wildcard `*.<domain>` covers them all.
Omni is missing, and `celum-appliance config` says it was switched off	The certificate mode is `acme-dns01`, which cannot serve Omni. Use `selfsigned` or `byo` if you need Omni.
Sign-in fails partway, on `auth.` or `api.`	One of the names from step 3 does not resolve from your workstation.
Sign-in loops back to the sign-in page	You are using `http://`. Celum’s session cookie is HTTPS-only, and the appliance redirects port 80 to 443, so use the `https://` address.
`403` everywhere	You are not in the administrator group, or the group was renamed after the first boot. Check My Profile (`/iam/me`).
Every change fails with `402` “Celum is not activated”	The 30 days from the first start have passed without a licence. Install one (step 6). Viewing still works.
Every change fails with `402` “The licence has ended”	The licence and its grace period have run out. Install a new licence under Settings → Licence.
Installing a licence fails with `issued for another installation`	The licence was issued for another appliance’s installation ID. Send Nuvira the ID shown under Settings → Licence on this appliance.
Installing a licence fails with `signature does not match`	The token was broken onto several lines, for example by an email client. Upload the `.celum-license` file instead of pasting it.
You cannot SSH in	No key was supplied in the wizard. The wizard’s answers are read only on the first boot, so adding a key in vCenter afterwards does nothing. The appliance has no password login unless you set one, so redeploy with a key.
The VM reports no IP address in vCenter	The port group offers no DHCP. Redeploy with a static address in the Networking section.

To see the configuration the appliance is actually using, and any warnings about it, run celum-appliance config over SSH.

Register a supervisor — give Celum the kubeconfig of a cluster you run. That page starts where this one ends: a Celum you can sign in to as an administrator. When you then onboard that cluster, it pulls every image from the appliance’s own Harbor, so it needs no route to the public registries.

Get Started

Concepts

Clusters

GitOps & Apps

Virtual machines

Networking

Security

Platform Health

Storage

Reference

Administration

Deploy the appliance on vCenter

What this changes in your environment

Before you start

Choose a certificate mode

Network access

The shape of it

Step 1 — Import the OVA

Step 2 — Answer the deploy wizard

1. Identity

2. Networking

3. TLS

4. Components

5. Updates

6. Advanced

Step 3 — Make the names resolve

Step 4 — Power on and watch the first boot

Step 6 — Activate Celum

Verify

If you need to undo it

What commonly goes wrong

Next

​What this changes in your environment

​Before you start

​Choose a certificate mode

​Network access

​The shape of it

​Step 1 — Import the OVA

​Step 2 — Answer the deploy wizard

​1. Identity

​2. Networking

​3. TLS

​4. Components

​5. Updates

​6. Advanced

​Step 3 — Make the names resolve

​Step 4 — Power on and watch the first boot

​Step 5 — Sign in

​Step 6 — Activate Celum

​Verify

​If you need to undo it

​What commonly goes wrong

​Next

What this changes in your environment

Before you start

Choose a certificate mode

Network access

The shape of it

Step 1 — Import the OVA

Step 2 — Answer the deploy wizard

1. Identity

2. Networking

3. TLS

4. Components

5. Updates

6. Advanced

Step 3 — Make the names resolve

Step 4 — Power on and watch the first boot

Step 5 — Sign in

Step 6 — Activate Celum

Verify

If you need to undo it

What commonly goes wrong

Next