@localctl/cli 0.5.0-beta.1 → 0.5.0-beta.3

package/README.md

@@ -113,8 +113,9 @@ CA trust.
 
 ### Linux (experimental)
 
-Linux support is **experimental**: it hasn't been through a full test cycle (CI only runs the
-smoke tests there), and `setup`/`doctor` print a warning. It's published on the `beta` dist-tag:
+Linux support is **experimental**: the end-to-end suite passes on the distributions below, but
+only in containers on arm64 (amd64 and bare-metal installs are untested), and `setup`/`doctor`
+print a warning. It's published on the `beta` dist-tag:
 
 ```sh
 npm install -g @localctl/cli@beta
@@ -125,10 +126,15 @@ Targeted distributions, all with systemd and a mkcert-supported trust store:
 | Family | Distributions | Docker Engine install |
 |---|---|---|
 | Debian | Ubuntu, Debian, Linux Mint, Pop!_OS | `localctl setup --install-docker` (Docker's official script) |
-| Red Hat | Fedora, RHEL, Rocky, AlmaLinux, CentOS Stream | `localctl setup --install-docker` (Docker's official script) |
+| Red Hat | Fedora, RHEL, Rocky, AlmaLinux, CentOS Stream | `localctl setup --install-docker` (Docker's official script on Fedora, Docker's CentOS repository elsewhere) |
 | Arch | Arch, Manjaro, EndeavourOS | `localctl setup --install-docker` (`pacman`) |
 | SUSE | openSUSE Leap/Tumbleweed | `localctl setup --install-docker` (`zypper`) |
 
+Verified end to end (`npm run test:e2e:distros`, see [Contributing](docs/contributing.md)): Ubuntu
+22.04 and 24.04, Debian 12, Fedora 41, Rocky 9, openSUSE Leap 15.6 and Arch Linux ARM. Derivatives
+resolve through `ID_LIKE` in `/etc/os-release` (or `/usr/lib/os-release`) but were not run
+themselves.
+
 Other distributions (Alpine, Void, Gentoo, NixOS, immutable/atomic desktops) may work if you
 bring Docker (or Podman) and Node.js yourself, but aren't targeted. WSL needs the Windows hosts
 file edited too.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@localctl/cli",
-  "version": "0.5.0-beta.1",
+  "version": "0.5.0-beta.3",
   "description": "localctl - local Kubernetes dev platform CLI",
   "keywords": [
     "kubernetes",
@@ -36,7 +36,9 @@
     "sync-assets": "node scripts/sync-assets.js",
     "prepack": "node scripts/sync-assets.js",
     "test": "node scripts/smoke-test.js",
-    "test:pack": "node scripts/pack-test.js"
+    "test:pack": "node scripts/pack-test.js",
+    "test:e2e": "node scripts/e2e/run.js",
+    "test:e2e:distros": "node scripts/e2e/distros.js"
   },
   "dependencies": {
     "chalk": "^4.1.2",

package/src/commands/uninstall.js

@@ -1,4 +1,3 @@
-const os = require('os');
 const fs = require('fs');
 const path = require('path');
 const { isRunning } = require('../lib/exec');
@@ -8,7 +7,7 @@ const { teardownInsecureRegistry } = require('../lib/podman');
 const { clearHosts } = require('../lib/hostsFile');
 const { listProfiles } = require('../lib/profileStore');
 const { confirm } = require('../lib/prompt');
-const { RUN_DIR, PROFILES_PATH } = require('../lib/paths');
+const { RUN_DIR, PROFILES_PATH, CERTS_DIR, APPS_REGISTRY_PATH } = require('../lib/paths');
 const logger = require('../lib/logger');
 
 // Every Main (cluster-isolation) project this machine knows about - each one owns a real,
@@ -80,8 +79,8 @@ async function uninstall(opts) {
     fs.rmSync(RUN_DIR, { recursive: true, force: true });
   }
 
-  const certsDir = path.join(os.homedir(), '.localctl', 'certs');
-  const appsRegistry = path.join(os.homedir(), '.localctl', 'apps.json');
+  const certsDir = CERTS_DIR;
+  const appsRegistry = APPS_REGISTRY_PATH;
   if (fs.existsSync(certsDir)) fs.rmSync(certsDir, { recursive: true, force: true });
   if (fs.existsSync(appsRegistry)) fs.rmSync(appsRegistry, { force: true });
   if (fs.existsSync(PROFILES_PATH)) fs.rmSync(PROFILES_PATH, { force: true });

package/src/lib/addonDirs.js

@@ -1,6 +1,7 @@
 const fs = require('fs');
 const os = require('os');
 const path = require('path');
+const { HOME_STATE_DIR } = require('./paths');
 
 // Addons are searched in two places, in precedence order:
 //   1. USER_DIR   - yours, never touched by a `localctl` update/reinstall. Defaults to
@@ -11,7 +12,7 @@ const path = require('path');
 // This is what lets someone install this tool without inheriting its author's addon set, and
 // without forking the tool to add their own - see docs/adding-tools.md.
 const BUILTIN_DIR = path.join(__dirname, 'addons');
-const USER_DIR = process.env.LOCALCTL_ADDONS_DIR || path.join(os.homedir(), '.localctl', 'addons');
+const USER_DIR = process.env.LOCALCTL_ADDONS_DIR || path.join(HOME_STATE_DIR, 'addons');
 
 function roots(...segments) {
   return [path.join(USER_DIR, ...segments), path.join(BUILTIN_DIR, ...segments)];

package/src/lib/clusterProvision.js

@@ -8,6 +8,7 @@ const { installIfMissing, installTiltWindows, nssInstallHint } = require('./tool
 const { ensureInsecureRegistry, ensurePodmanSocket, blockedPrivilegedPorts } = require('./podman');
 const { DOMAIN } = require('./constants');
 const logger = require('./logger');
+const { CERTS_DIR } = require('./paths');
 const { detectDistro, dockerInstallSteps } = require('./linuxDistro');
 
 // Cluster-level manifests: bundled under cli/assets/ in the npm package (copied there by
@@ -43,6 +44,12 @@ function clusterExists(clusterName) {
 // which also repairs clusters created before this fix.
 function useClusterContext(clusterName) {
   const context = `k3d-${clusterName}`;
+  // The cluster can exist while this kubeconfig knows nothing about it (a deleted or replaced
+  // ~/.kube/config, a different KUBECONFIG): ask k3d to write it back instead of failing.
+  const known = capture('kubectl', ['config', 'get-contexts', '-o', 'name']).stdout.split('\n');
+  if (!known.includes(context)) {
+    run('k3d', ['kubeconfig', 'merge', clusterName, '--kubeconfig-merge-default'], { stdio: 'ignore', allowFail: true });
+  }
   run('kubectl', ['config', 'use-context', context], { stdio: 'ignore' });
   const server = capture('kubectl', [
     'config', 'view', '--minify', '-o', 'jsonpath={.clusters[0].cluster.server}',
@@ -84,6 +91,80 @@ function buildK3dConfig({ clusterName, httpPort, httpsPort, registryName }) {
   };
 }
 
+// Right after a (re)start the load balancer can accept connections before the API server is
+// answering (EOF / connection refused), so wait for it before the first real kubectl call.
+// Also after an engine restart the server container can get a new IP while the load balancer
+// (nginx, resolves upstreams only at startup) keeps the old one, so the API never answers;
+// restarting the load balancer once re-resolves it. Returns true once the API is ready.
+function waitForClusterApi(engineBin, clusterName, { attempts = 60, quiet = false } = {}) {
+  if (!quiet) logger.step('Waiting for the Kubernetes API...');
+  let lbRestarted = false;
+  for (let i = 0; i < attempts; i += 1) {
+    if (capture('kubectl', ['get', '--raw', '/readyz']).status === 0) return true;
+    if (i === 5 && !lbRestarted) {
+      lbRestarted = true;
+      run(engineBin, ['restart', `k3d-${clusterName}-serverlb`], { stdio: 'ignore', allowFail: true });
+    }
+    sleepSync(2000);
+  }
+  return false;
+}
+
+// k3d's --wait only waits for node readiness, not for Traefik's helm-install job to finish
+// registering its CRDs, so applying TLSStore any earlier races and fails intermittently. On a slow
+// machine (first image pulls, a nested engine) that takes minutes, so poll for the CRD to be
+// *Established* instead of giving up after one fixed wait, and say why if it never is.
+function waitForTraefikCrds(attempts = 150) {
+  logger.step('Waiting for Traefik CRDs...');
+  let last = 'not found yet';
+  for (let i = 0; i < attempts; i += 1) {
+    const r = capture('kubectl', [
+      'get', 'crd', 'tlsstores.traefik.io',
+      '-o', 'jsonpath={.status.conditions[?(@.type=="Established")].status}',
+    ]);
+    if (r.status === 0 && r.stdout === 'True') return;
+    last = r.status === 0 ? `Established=${r.stdout || 'unknown'}` : (r.stderr.split('\n')[0] || 'not found yet');
+    sleepSync(2000);
+  }
+  throw new Error(
+    `Traefik's CRDs (tlsstores.traefik.io) were not ready after ${Math.round((attempts * 2) / 60)} minutes (${last}). ` +
+    'Check "kubectl -n kube-system get pods" - the traefik helm-install jobs are probably still pulling images.',
+  );
+}
+
+// The CRDs existing does not mean Traefik is serving: on a slow machine its pod can still be
+// starting minutes later, and an app deployed in that window answers with a dropped connection.
+// Waiting here makes "cluster ready" mean the ingress actually accepts traffic.
+function waitForTraefik(attempts = 150) {
+  logger.step('Waiting for Traefik to accept traffic...');
+  for (let i = 0; i < attempts; i += 1) {
+    if (capture('kubectl', ['get', 'deployment', 'traefik', '-n', 'kube-system']).status === 0) break;
+    sleepSync(2000);
+  }
+  const res = capture('kubectl', ['rollout', 'status', 'deployment/traefik', '-n', 'kube-system', '--timeout=300s']);
+  if (res.status !== 0) {
+    throw new Error(
+      `Traefik did not become ready in 5 minutes (${(res.stderr || res.stdout).split('\n')[0]}). ` +
+      'Check "kubectl -n kube-system get pods".',
+    );
+  }
+}
+
+// A CRD can be Established a moment before the API server's discovery serves it, which surfaces as
+// "no matches for kind". Retrying the apply covers that window.
+function applyWithRetry(file, attempts = 15) {
+  let res;
+  for (let i = 0; i < attempts; i += 1) {
+    res = capture('kubectl', ['apply', '-f', file]);
+    if (res.status === 0) {
+      if (res.stdout) console.log(res.stdout);
+      return;
+    }
+    sleepSync(2000);
+  }
+  throw new Error(`kubectl apply -f ${path.basename(file)} failed after ${attempts} attempts: ${res.stderr}`);
+}
+
 // Brings up (idempotently) one Main project's cluster: container engine + tool checks, the k3d
 // cluster itself (own ports, since two clusters can't both bind host :80/:443), its own local
 // registry container, and the shared *.local.test TLS cert wired into its Traefik. Used by both
@@ -99,13 +180,18 @@ function provisionCluster({ clusterName, httpPort, httpsPort, registryPort }) {
   if (!detected) {
     let linuxHint = '';
     if (process.platform === 'linux') {
-      const steps = dockerInstallSteps(detectDistro().family);
-      linuxHint = '\nOn Linux: if Docker is installed, make sure the service runs and your user can reach it' +
-        ' (member of the "docker" group, then log out and in).';
-      if (steps) {
-        linuxHint += `\nTo install Docker Engine, run "localctl setup --install-docker", or by hand:\n  ${steps.join('\n  ')}`;
+      if (commandExists('docker') || commandExists('podman')) {
+        // Installed but not usable: reinstalling won't help, the daemon or permissions are the issue.
+        linuxHint = '\nA container engine is installed but not responding. Start the service' +
+          ' (`sudo systemctl enable --now docker`, or `systemctl --user enable --now podman.socket` for Podman;' +
+          ' without systemd, start `dockerd` yourself) and make sure your user can reach it' +
+          ' (member of the "docker" group, then log out and in).';
       } else {
-        linuxHint += '\nInstall Docker Engine for your distro: https://docs.docker.com/engine/install/';
+        const { family, id } = detectDistro();
+        const steps = dockerInstallSteps(family, id);
+        linuxHint = steps
+          ? `\nTo install Docker Engine, run "localctl setup --install-docker", or by hand:\n  ${steps.join('\n  ')}`
+          : '\nInstall Docker Engine for your distro: https://docs.docker.com/engine/install/';
       }
     }
     throw new Error(`No running container engine found. Start Docker Desktop, Podman, or Rancher Desktop and re-run.${linuxHint}`);
@@ -171,20 +257,15 @@ function provisionCluster({ clusterName, httpPort, httpsPort, registryPort }) {
   }
   useClusterContext(clusterName);
 
-  // Right after a (re)start the load balancer can accept connections before the API server is
-  // answering (EOF / connection refused), so wait for it before the first real kubectl call.
-  logger.step('Waiting for the Kubernetes API...');
-  // After an engine restart the server container can get a new IP while the load balancer
-  // (nginx, resolves upstreams only at startup) keeps the old one, so the API never answers.
-  // Restarting the load balancer once re-resolves it.
-  let lbRestarted = false;
-  for (let i = 0; i < 60; i += 1) {
-    if (capture('kubectl', ['get', '--raw', '/readyz']).status === 0) break;
-    if (i === 5 && !lbRestarted) {
-      lbRestarted = true;
-      run(engineBin, ['restart', `k3d-${clusterName}-serverlb`], { stdio: 'ignore', allowFail: true });
-    }
-    sleepSync(2000);
+  // Up to ~5 minutes: k3s can exit once during start-up (a known race between its cloud controller
+  // and RBAC bootstrap) and is restarted by the engine, which a 2-minute wait would not outlast on
+  // a slow machine. If it never answers, stop here with the reason instead of failing later on an
+  // unrelated "EOF" from kubectl apply.
+  if (!waitForClusterApi(engineBin, clusterName, { attempts: 150 })) {
+    throw new Error(
+      `The Kubernetes API of cluster '${clusterName}' did not become ready in 5 minutes. ` +
+      `See why with: ${engineBin} logs --tail 50 k3d-${clusterName}-server-0`,
+    );
   }
 
   const registryNetwork = `k3d-${clusterName}`;
@@ -209,7 +290,7 @@ function provisionCluster({ clusterName, httpPort, httpsPort, registryPort }) {
   // domain everywhere; only the namespace/subdomain prefix or the cluster differs).
   logger.step(`Setting up local TLS for *.${DOMAIN}...`);
   run('mkcert', ['-install']);
-  const certDir = path.join(os.homedir(), '.localctl', 'certs');
+  const certDir = CERTS_DIR;
   fs.mkdirSync(certDir, { recursive: true });
   const certFile = path.join(certDir, 'local-dev.pem');
   const keyFile = path.join(certDir, 'local-dev-key.pem');
@@ -226,15 +307,10 @@ function provisionCluster({ clusterName, httpPort, httpsPort, registryPort }) {
 
   // k3d's --wait only waits for node readiness, not for Traefik's helm-install job to finish
   // registering its CRDs, so applying TLSStore any earlier races and fails intermittently.
-  logger.step('Waiting for Traefik CRDs...');
-  for (let i = 0; i < 60; i += 1) {
-    if (capture('kubectl', ['get', 'crd', 'tlsstores.traefik.io']).status === 0) break;
-    sleepSync(2000);
-  }
-  run('kubectl', ['wait', '--for=condition=Established', 'crd/tlsstores.traefik.io', '--timeout=60s'], { stdio: 'ignore' });
-
-  run('kubectl', ['apply', '-f', path.join(MANIFESTS_DIR, 'tls-store.yaml')]);
-  run('kubectl', ['apply', '-f', path.join(MANIFESTS_DIR, 'namespace-addons.yaml')]);
+  waitForTraefikCrds();
+  applyWithRetry(path.join(MANIFESTS_DIR, 'tls-store.yaml'));
+  applyWithRetry(path.join(MANIFESTS_DIR, 'namespace-addons.yaml'));
+  waitForTraefik();
   logger.success('TLS configured, default cert wired into Traefik');
 }
 
@@ -267,4 +343,4 @@ function ensureClusterUp(clusterName, profileName) {
   useClusterContext(clusterName);
 }
 
-module.exports = { buildK3dConfig, provisionCluster, teardownCluster, clusterExists, registryNameFor, ensureClusterUp };
+module.exports = { buildK3dConfig, useClusterContext, waitForClusterApi, provisionCluster, teardownCluster, clusterExists, registryNameFor, ensureClusterUp };

package/src/lib/exec.js

@@ -21,9 +21,12 @@ function capture(cmd, args, opts = {}) {
 }
 
 function commandExists(cmd) {
-  const probe = process.platform === 'win32' ? 'where' : 'which';
-  const res = spawnSync(probe, [cmd], { stdio: 'ignore' });
-  return res.status === 0;
+  if (process.platform === 'win32') {
+    return spawnSync('where', [cmd], { stdio: 'ignore' }).status === 0;
+  }
+  // `command -v` is a POSIX shell builtin; `which` is a separate program that minimal installs
+  // (Fedora/openSUSE server images, containers) don't ship.
+  return spawnSync('sh', ['-c', 'command -v "$0"', cmd], { stdio: 'ignore' }).status === 0;
 }
 
 // Blocking sleep with no native dependency - used for poll loops (e.g. waiting on a CRD to

package/src/lib/hostsFile.js

@@ -8,8 +8,10 @@ const { DOMAIN } = require('./constants');
 
 const MARK_START = '# >>> localctl managed block >>>';
 const MARK_END = '# <<< localctl managed block <<<';
-const HOSTS_PATH =
-  process.platform === 'win32' ? 'C:\\Windows\\System32\\drivers\\etc\\hosts' : '/etc/hosts';
+// $LOCALCTL_HOSTS_FILE points it at another file - used by the e2e suite so tests never touch
+// (or need sudo for) the real hosts file.
+const HOSTS_PATH = process.env.LOCALCTL_HOSTS_FILE ||
+  (process.platform === 'win32' ? 'C:\\Windows\\System32\\drivers\\etc\\hosts' : '/etc/hosts');
 
 function registerApp(subdomain) {
   ensureHomeState();

package/src/lib/linuxDistro.js

@@ -17,12 +17,17 @@ const FAMILY_BY_ID = [
 // Reads ID and ID_LIKE from os-release, so derivatives resolve to their parent (Mint, Pop!_OS ->
 // debian; Rocky, Alma -> rhel; Manjaro -> arch).
 function detectDistro() {
-  let release = '';
-  try {
-    release = fs.readFileSync('/etc/os-release', 'utf8');
-  } catch (e) {
-    return { id: 'unknown', family: 'unknown' };
+  let release = null;
+  // /usr/lib/os-release is the documented fallback when /etc/os-release is missing.
+  for (const file of ['/etc/os-release', '/usr/lib/os-release']) {
+    try {
+      release = fs.readFileSync(file, 'utf8');
+      break;
+    } catch (e) {
+      // try the next location
+    }
   }
+  if (release === null) return { id: 'unknown', family: 'unknown' };
   const value = (key) => {
     const m = release.match(new RegExp(`^${key}=(.*)$`, 'm'));
     return m ? m[1].replace(/"/g, '').trim() : '';
@@ -43,11 +48,21 @@ function isRoot() {
 
 // What `localctl setup --install-docker` would do, as printable steps. Shown in the "no engine"
 // error too, so the user can run them by hand. Returns null for families without a known recipe.
-function dockerInstallSteps(family) {
+function dockerInstallSteps(family, id) {
   const sudo = isRoot() ? '' : 'sudo ';
   const user = os.userInfo().username;
   let install;
-  if (family === 'debian' || family === 'rhel') {
+  if (family === 'rhel' && id !== 'fedora') {
+    // Docker's convenience script derives the repo path from the distro ID, and publishes
+    // .../linux/centos and .../linux/rhel but not .../linux/rocky or .../linux/almalinux: it adds
+    // a repo whose packages don't exist ("Unable to find a match: docker-ce"). The CentOS repo is
+    // what Docker documents for the RHEL rebuilds.
+    install = [
+      `${sudo}dnf -y install dnf-plugins-core`,
+      `${sudo}dnf config-manager --add-repo https://download.docker.com/linux/centos/docker-ce.repo`,
+      `${sudo}dnf -y install docker-ce docker-ce-cli containerd.io`,
+    ];
+  } else if (family === 'debian' || family === 'rhel') {
     install = [`curl -fsSL https://get.docker.com -o get-docker.sh && ${sudo}sh get-docker.sh`];
   } else if (family === 'arch') {
     install = [`${sudo}pacman -S --noconfirm docker`];
@@ -67,17 +82,18 @@ function dockerInstallSteps(family) {
 // ever runs on an explicit `--install-docker`.
 function installDocker() {
   const { family, id } = detectDistro();
-  if (!dockerInstallSteps(family)) {
+  if (!dockerInstallSteps(family, id)) {
     throw new Error(`No automatic Docker install for "${id}". Install Docker Engine for your distro (https://docs.docker.com/engine/install/) and re-run.`);
   }
-  if (!commandExists('curl') && (family === 'debian' || family === 'rhel')) {
+  const viaScript = family === 'debian' || (family === 'rhel' && id === 'fedora');
+  if (!commandExists('curl') && viaScript) {
     throw new Error('curl is needed to download the Docker install script. Install it and re-run.');
   }
   logger.step(`Installing Docker Engine (${id}). This needs sudo and will prompt for your password...`);
   const sudo = isRoot() ? [] : ['sudo'];
   const exec = (cmd, args) => run(sudo.length ? sudo[0] : cmd, sudo.length ? [cmd, ...args] : args);
 
-  if (family === 'debian' || family === 'rhel') {
+  if (viaScript) {
     const script = path.join(os.tmpdir(), 'localctl-get-docker.sh');
     run('curl', ['-fsSL', 'https://get.docker.com', '-o', script]);
     try {
@@ -85,6 +101,10 @@ function installDocker() {
     } finally {
       fs.rmSync(script, { force: true });
     }
+  } else if (family === 'rhel') {
+    exec('dnf', ['-y', 'install', 'dnf-plugins-core']);
+    exec('dnf', ['config-manager', '--add-repo', 'https://download.docker.com/linux/centos/docker-ce.repo']);
+    exec('dnf', ['-y', 'install', 'docker-ce', 'docker-ce-cli', 'containerd.io']);
   } else if (family === 'arch') {
     exec('pacman', ['-S', '--noconfirm', 'docker']);
   } else if (family === 'suse') {

package/src/lib/paths.js

@@ -5,7 +5,10 @@ const fs = require('fs');
 const APP_DIR = process.cwd();
 const LOCAL_DIR = path.join(APP_DIR, '.local');
 const CONFIG_PATH = path.join(LOCAL_DIR, 'config.json');
-const HOME_STATE_DIR = path.join(os.homedir(), '.localctl');
+// $LOCALCTL_HOME relocates all machine-level state (profiles, apps, certs, run files). The e2e
+// suite uses it to run against a throwaway directory instead of your real ~/.localctl.
+const HOME_STATE_DIR = process.env.LOCALCTL_HOME || path.join(os.homedir(), '.localctl');
+const CERTS_DIR = path.join(HOME_STATE_DIR, 'certs');
 const APPS_REGISTRY_PATH = path.join(HOME_STATE_DIR, 'apps.json');
 const PROFILES_PATH = path.join(HOME_STATE_DIR, 'profiles.json');
 const RUN_DIR = path.join(HOME_STATE_DIR, 'run');
@@ -33,6 +36,7 @@ module.exports = {
   LOCAL_DIR,
   CONFIG_PATH,
   HOME_STATE_DIR,
+  CERTS_DIR,
   APPS_REGISTRY_PATH,
   PROFILES_PATH,
   RUN_DIR,