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
.sha256file and every file against the bundle'sSHA256SUMS, 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_TAGis not set (in the environment or in/etc/platform/.envfrom an earlier provision), provision sets it to the bundle's tag (the release version, such as1.4.0); when it is set to another tag, orPLATFORM_IMAGE_REGISTRYis 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
Related
- Installation — local Docker vs server install
- Bootstrap walkthrough
- MCP — agent tokens and guarded commands