platformctl CLI

platformctl installs and manages Cairn on an Ubuntu server. This page lists every command and the main options.

Run it as root or with sudo. It uses pre-built images, so nothing is compiled on the server.

Install

Run this on the server:

curl -fsSL https://github.com/Mpratyush54/SERVER-automation/releases/latest/download/install.sh | bash
sudo platformctl provision

Non-interactive (CI / automation). A fresh install needs an off-site backup target (BACKUP_S3_BUCKET, with BACKUP_S3_ACCESS_KEY and BACKUP_S3_SECRET_KEY from the environment) or an explicit --local-backups:

sudo DOMAIN=platform.example.com [email protected] platformctl provision --auto --local-backups

To use a bucket instead, see Install without questions.

install.sh puts the platformctl binary on PATH. Config lives in /etc/platform/.env (override with --config).

Requirements: Ubuntu 22.04+, sudo, at least 4 GB RAM and 40 GB free disk (8 GB and 80 GB recommended), ports 80 and 443 open. See Install.

Commands

Command What it does
platformctl provision Full bootstrap: k3s, databases, ArgoCD, monitoring, Cairn API + portal
platformctl install <component> Install or re-run one component (see list below)
platformctl status Health check of cluster components (HA: nodes, roles, etcd health and quorum)
platformctl seed Seed the admin user from /etc/platform/.env
platformctl update Pull newest GHCR images and roll Cairn deployments; on ha servers also refresh the local kube-vip manifest (joined servers: only that)
platformctl recover Backup host files, persist passwords to disk, then restore API/Postgres login after a broken rotate
platformctl repair Fix HTTPS certificates and single sign-on for the bundled tools; safe to run any time
platformctl upgrade Upgrade to a newer release with a backup, health checks and rollback (Upgrade)
platformctl backup Copy /etc/platform/.env and database secrets to /var/lib/platform/backups/<timestamp>/ (not encrypted)
platformctl backup init|list|schedule|restore-test Encrypted off-site backups (Backups and restore); backup --all takes one
platformctl backup target set|show|test Change, show or test the off-site backup target (Backups and restore)
platformctl restore Restore an encrypted backup; reads the private key from standard input
platformctl harden Apply or re-apply the host security baseline (Host hardening)
platformctl mfa disable --user <email> Remove a user's two-factor sign-in when no admin can (Recover)
platformctl join Join this node to an HA cluster as a server or agent (High availability)
platformctl token create|rotate|install Create, rotate and install cluster join tokens (HA)
platformctl postgres replication [set sync|async] Show or switch synchronous/asynchronous database replication on ha (Database replication)
platformctl version Print CLI version and default image tag
platformctl --help List commands

Global flags:

Flag Meaning
--config <path> Env file (default /etc/platform/.env)
--auto Non-interactive; skip prompts

Run as root (or with sudo) so the CLI can talk to k3s (KUBECONFIG=/etc/rancher/k3s/k3s.yaml).

install components

sudo platformctl install platform
Name Installs
ingress-nginx Kubernetes Ingress Controller
cert-manager Let's Encrypt certificates
postgresql PostgreSQL
mongodb MongoDB
redis Redis
minio S3-compatible object storage
argocd Argo CD GitOps
monitoring Grafana + Prometheus + Loki
oauth2-proxy OAuth2 proxy
portainer Portainer UI with Platform SSO
platform Cairn API + portal
routing Ingress routes
auto-update GHCR image updater + CronJob

Provision is idempotent via /etc/platform/.bootstrap_state. To retry one step:

sudo sed -i '/^platform=/d' /etc/platform/.bootstrap_state
sudo platformctl install platform

Install speed, logs and timings

provision installs cluster components in parallel, respecting dependencies (databases before the Cairn API, ingress before routing):

sudo platformctl provision --auto              # default: 4 steps at a time
sudo platformctl provision --auto --parallel 2 # gentler on small servers
sudo platformctl provision --auto --parallel 1 # serial, live output (old behaviour)
  • Per-step logs: /var/log/platformctl/<step>.log (the last lines are printed if a step fails)
  • Background image pre-pull log: /var/log/platformctl/prepull.log
  • Timing summary: printed at the end and saved to /var/log/platformctl/timings.txt

Docker is not installed on the server; k3s uses its own containerd. For private GHCR images set GITHUB_TOKEN before provisioning; it is written to /etc/rancher/k3s/registries.yaml.

Install profiles

Set PLATFORM_PROFILE (or pass --profile) to minimal, standard (default) full or ha:

  • minimal: core only; no monitoring, Portainer or ArgoCD.

  • standard: the existing Grafana/Prometheus/Loki stack, Portainer and ArgoCD.

  • full: standard services plus Alloy, S3-backed Loki, Tempo, Pyroscope and blackbox-exporter. See Turn on full monitoring for memory estimates, token/CORS integration and the required legacy Loki migration.

  • ha: the full feature set on a multi-node cluster: embedded etcd, ingress HA (kube-vip VIP or external load balancer) and Longhorn replicated storage as the default StorageClass. See High availability.

Saved explicit profiles remain in effect. Existing loki-stack installations must follow the telemetry migration procedure before selecting full.

Browser synthetic checks (headless Chromium CronJobs) are an extra opt-in on the full profile: SYNTHETICS_BROWSER=true. See Synthetic monitoring.

Explicit INSTALL_* variables override the profile. The profile is saved as PLATFORM_PROFILE in /etc/platform/.env; choosing a new profile explicitly ignores the INSTALL_* values saved by an earlier run.

The ha profile installs everything in full on a multi-node cluster: the first server starts k3s with embedded etcd (cluster-init) and further nodes join with platformctl join. Set PLATFORM_CLUSTER_NODES (all node IPs or a CIDR) so the host firewall admits the other nodes. See High availability. It also asks for the PostgreSQL replication mode (--postgres-replication sync|async, saved as POSTGRES_REPLICATION); change it later with sudo platformctl postgres replication set sync|async. See Synchronous or asynchronous database replication.

The profile also sets the Cairn API replica count: 1 on minimal, 2 otherwise (rolling updates with maxUnavailable: 0 and a PodDisruptionBudget). Override it with API_REPLICAS=<1-10>; see Scaling.

Ingress per-IP limits

These limits cover all ingress traffic, including customer applications, per client IP and controller replica. Defaults accommodate office and carrier NAT:

Environment variable Default Allowed values
INGRESS_IP_RATE_LIMIT 1000 requests/second 0 or 1-1000000
INGRESS_IP_BURST 2000 requests 0 or 1-1000000
INGRESS_IP_CONNECTIONS 2000 concurrent connections 0 or 1-65535

Invalid values warn and use defaults. Zero rate or connections disables that limiter and omits its directives. Zero burst removes the burst allowance while keeping the request rate limit active; burst is ignored when rate is zero.

sudo INGRESS_IP_RATE_LIMIT=5000 INGRESS_IP_BURST=10000 INGRESS_IP_CONNECTIONS=4000 platformctl install ingress-nginx

Values are saved in /etc/platform/.env and re-applied by subsequent platformctl install ingress-nginx runs. You can also edit the saved file; process environment variables take precedence. See Host hardening.

Offline bundle

Releases include platform-bundle-<version>-<arch>.tar.zst and a .sha256 file. The bundle holds the pinned k3s binary, its installer and airgap images, the Helm binary, all pinned Helm charts (platformctl charts --json), the third-party container images, the release's own Cairn images (API, portal, profile ingest and synthetics runner), and the Ubuntu 22.04 and 24.04 packages provision and join install (prerequisites, Longhorn prerequisites and host hardening packages, with their dependencies). The bundle is larger than GitHub's 2 GiB per-asset limit, so a release carries it as .tar.zst.part00, .part01, …; --bundle auto downloads and reassembles the parts and checks the result against the .sha256. To fetch it manually, download every part and the .sha256, then cat platform-bundle-<version>-<arch>.tar.zst.part* > platform-bundle-<version>-<arch>.tar.zst and sha256sum -c before --bundle <path>.

sudo platformctl provision --bundle /root/platform-bundle-<version>-amd64.tar.zst

With --bundle <path>, provision downloads none of the components the bundle carries:

  • it checks the bundle against its .sha256 file and every file against the bundle's SHA256SUMS, and stops on a mismatch
  • it places the images in /var/lib/rancher/k3s/agent/images/ and the charts in /var/lib/platform/charts/ before k3s starts; k3s imports the images at startup
  • it installs the prerequisites from the bundle with apt, using only the bundle as a package source, as join does; it stops when the OS is not Ubuntu 22.04 or 24.04 or when a dependency is not in the bundle
  • it installs Helm and k3s from the bundle, with no download fallback for k3s
  • it uses the bundle's Cairn images: when PLATFORM_IMAGE_TAG is not set (in the environment or in /etc/platform/.env from an earlier provision), provision sets it to the bundle's tag (the release version, such as 1.4.0); when it is set to another tag, or PLATFORM_IMAGE_REGISTRY is not the registry the bundle's images come from, provision prints a warning and those images are pulled from the registry
  • after k3s starts, it adds the digest names of images pinned by digest (the ingress-nginx controller and its admission webhook job, and the Cairn images, whose digests the bundle's manifest records), so they start without a registry

Your applications' images need a registry the server can reach. A bundle from an older release that lacks Helm, k3s, the packages or the Cairn images still works; provision downloads the missing parts and prints a warning. --bundle auto downloads the bundle itself, so it needs internet access. Without --bundle, provision works as before: packages from the apt mirrors, Helm from get.helm.sh, and the platform stack.

To build a bundle locally (needs curl, jq, helm 3, docker, zstd):

scripts/build-bundle.sh v1.0.0 amd64   # writes dist/platform-bundle-v1.0.0-amd64.tar.zst

The Cairn images are taken from PLATFORM_IMAGE_REGISTRY (default ghcr.io/mpratyush54) with the tag PLATFORM_IMAGES_TAG (default: the version without its v); they must exist for that architecture. The platform stack carries none of them, nor the packages or Helm.

Day-2 operations

Update images after a release:

sudo platformctl update

Secret rotate / wrong password: run backup first, then recover. Recover writes passwords to /etc/platform/.env and /etc/platform/credentials/ before any ALTER USER. Details: DB WRONGPASS after rotate.

sudo platformctl backup
sudo platformctl recover
sudo platformctl update

Health:

sudo platformctl status
sudo platformctl version