create-minc

Scaffolds a local MicroShift-in-Container (minc) dev cluster — a lightweight OpenShift/OKD-based Kubernetes cluster running as a single container via Docker or Podman — with optional:

• Web Console (OpenShift/OKD console UI, standalone container) - HTTPS
• Postgres (CloudNativePG operator + a sample Cluster resource, port-forwarded to localhost:5432)
• Argo CD - HTTPS, no login required (anonymous admin access, for local dev convenience)
• Pomerium (identity-aware ingress proxy) - HTTPS

Console and Argo CD always get HTTPS, signed by a local self-signed root CA that create-minc generates and (best-effort) trusts in your OS, regardless of whether you pick Pomerium or not.

It auto-detects your OS (Windows/macOS/Linux), your container engine (Docker/Podman), downloads the right minc binary, creates the cluster, fixes the OpenShift SecurityContextConstraint issues that trip up Docker Desktop / non-RHEL hosts, and installs a minc start / minc stop wrapper script on your PATH so you can suspend/resume the whole stack easily.

Requirements

• Node.js >= 18
• Docker Desktop (Windows/macOS) or Docker/Podman (Linux)
• kubectl or oc on your PATH

Optional: pre-fill Pomerium OIDC values via .env

If you select Pomerium, you'll be prompted for an OIDC issuer URL, client ID, and client secret. To avoid retyping these every time, copy .env.example to .env (in this folder) and fill in your values:

POMERIUM_OIDC_ISSUER_URL=https://your-keycloak/realms/yourrealm
POMERIUM_OIDC_CLIENT_ID=pomerium
POMERIUM_OIDC_CLIENT_SECRET=your-secret

When present, these become the defaults in the prompts - just press Enter to accept them. .env is gitignored so your secret never gets committed.

Optional: let create-minc configure Keycloak for you

If your issuer URL is a Keycloak realm, add master-realm admin credentials to .env as well:

KEYCLOAK_ADMIN_USERNAME=admin
KEYCLOAK_ADMIN_PASSWORD=your-admin-password

With those set, the installer offers to finish the Keycloak side over its admin API:

• Adds the callback to the client's Valid Redirect URIs. Getting this wrong is the single most common failure, and it doesn't look like a redirect problem — Keycloak renders a generic "We are sorry, an error occurred" page before Pomerium ever sees the request. The required value is https://localhost:9444/oauth2/callback, added without disturbing any existing entries.
• Makes sure a user exists that you can log in as, defaulting to pomerium-dev, with a generated password printed in the final summary. The user is created with a verified email, because Pomerium requests the email scope and evaluates policy on that claim — an account without one authenticates and is then rejected, which is far more confusing to debug.

An existing account is never re-passworded silently; that takes an explicit confirmation, since a realm user may be shared with other applications.

The master realm is not your Pomerium realm

This trips people up constantly. KEYCLOAK_ADMIN_USERNAME lives in the master realm. The users Pomerium authenticates live in the realm named in POMERIUM_OIDC_ISSUER_URL. These are separate credential stores: a username present in both is two unrelated accounts with two unrelated passwords.

Typing your .env admin password at the Pomerium login therefore fails with "Invalid username or password" — which reads like Pomerium is broken when nothing is wrong with it at all. That is why the installer defaults the login account to pomerium-dev rather than reusing the admin username.

What you actually get at localhost:9444

Pomerium redirects you to Keycloak to sign in, then drops you at /.pomerium/ — a session dashboard showing your identity, claims, groups and token expiry. It is not an admin UI; the product called Pomerium Console is a separate Enterprise offering. The dashboard exists to confirm SSO works and to show what your IdP hands over.

Until you create an Ingress with ingressClassName: pomerium, that dashboard is all there is — Pomerium is authenticating correctly but has no application behind it to protect.

Usage

npm create minc@latest

Always include @latest. Without it, npm can keep re-running an old copy from its npx cache after a new version is published.

Env file

Optionally pass a .env file (see .env.example) with your Pomerium/Keycloak/Argo CD settings:

npm create minc@latest ./my.env

• With a path: that file is used and copied to ~/.minc/.env.
• Without one: ./.env in the current folder is used, otherwise an existing ~/.minc/.env from a previous install.
• If none is found (or the given path does not exist), ~/.minc/.env is created from the answers you give during the install.

From a local checkout

npx . [path-to-env-file]

What it does, step by step

1. Detects platform/arch and container engine (prefers Docker if present, else Podman).
2. Prompts you for which optional components to install (Console / Postgres / Argo CD).
3. Downloads the minc binary for your platform into ~/.minc/bin.
4. Adds ~/.minc/bin to your PATH persistently (registry on Windows, shell profile on macOS/Linux).
5. Writes a minc wrapper (macOS/Linux) or minc.cmd + helper script (Windows) that adds start / stop / stack-status subcommands on top of the real minc binary (renamed to minc-bin/minc-bin.exe to avoid a Windows PATHEXT resolution conflict).
6. Runs minc create (with the Docker-overlay-storage workaround applied automatically when using Docker, since Docker Desktop's storage driver conflicts with MicroShift's internal overlay-fs otherwise).
7. Installs the Rancher local-path-provisioner so PVCs can bind (needed for Postgres, generally useful).
8. For each selected component, installs it and patches the anyuid SecurityContextConstraint for any ServiceAccounts that need a fixed non-root UID or custom seccomp profile (a common friction point on MicroShift/OKD when not running on RHEL).

After installation

The scaffolder writes a real minc command directly to ~/.minc/bin (minc.cmd + helper on Windows, a single minc script on macOS/Linux) and adds that directory to your PATH persistently. This happens automatically as a side effect of running the scaffolder — no separate npm install -g is needed.

Open a new terminal window (PATH changes don't apply retroactively to already-open shells), then:

minc start          # start the cluster + any installed components
minc stop           # stop everything
minc stack-status   # show status
minc ports          # interactive checkbox menu (space to toggle, enter to confirm) for Console/Argo CD/Postgres/Pomerium
minc remove         # completely uninstall - containers, CA trust, PATH entry, all files
minc <anything else># passthrough to the real minc CLI (create/delete/status/config/...)

Port-forwards are self-healing: each one runs under a small Node supervisor process (~/.minc/bin/supervisor.mjs) that automatically restarts it if it ever dies (network blips, pod restarts, etc.), instead of silently staying down.

After minc remove, you'll need to run the scaffolder again (npm create minc@latest) to reinstall.

Known limitations

• macOS builds of minc are only published for arm64 upstream at the time of writing; Intel Macs are not currently supported by the minc project itself.
• The web console runs with authentication disabled (dev-only mode) and uses a self-signed/HTTP setup by default — fine for local development, not for anything exposed beyond your machine.
• Postgres and Argo CD are installed with plain manifests, not via OLM/ OperatorHub, to keep this quick and dependency-free.
• No TLS/cert-manager/reverse-proxy setup is included here (out of scope for this tool).