@esuyo/coding-container 1.0.2

package/Dockerfile

@@ -0,0 +1,126 @@
+# syntax=docker/dockerfile:1
+#
+# Coding container: Ubuntu + Node.js + opencode + pi + herdr + playwright + ssh
+#
+# Adjustable via build args (see config.yaml -> image.buildArgs):
+#   BASE_IMAGE          Ubuntu base image
+#   NODE_VERSION        Major Node.js version installed via NodeSource
+#   EXTRA_APT_PACKAGES  Space separated list of extra apt packages
+#   EXTRA_NPM_PACKAGES  Space separated list of extra global npm packages
+#   INSTALL_PLAYWRIGHT  "true" (default) or "false"
+
+ARG BASE_IMAGE=ubuntu:26.04
+FROM ${BASE_IMAGE}
+
+ARG NODE_VERSION=22
+ARG EXTRA_APT_PACKAGES=""
+ARG EXTRA_NPM_PACKAGES=""
+ARG INSTALL_PLAYWRIGHT=true
+
+ENV DEBIAN_FRONTEND=noninteractive \
+    PLAYWRIGHT_BROWSERS_PATH=/usr/lib/playwright-browsers
+
+# --- Base tooling -----------------------------------------------------------
+RUN apt-get update && apt-get install -y --no-install-recommends \
+        ca-certificates curl wget gnupg git \
+        openssh-server \
+        build-essential \
+        htop vim nano less tree unzip zip rsync \
+        jq fd-find ripgrep \
+        iputils-ping bind9-dnsutils \
+        ${EXTRA_APT_PACKAGES} \
+    && ( [ -x /usr/bin/fd-find ] && ln -sf /usr/bin/fd-find /usr/local/bin/fd \
+         || ln -sf /usr/bin/fdfind /usr/local/bin/fd ) \
+    && rm -rf /var/lib/apt/lists/*
+
+# --- Node.js (NodeSource) ---------------------------------------------------
+RUN curl -fsSL https://deb.nodesource.com/setup_${NODE_VERSION}.x | bash - \
+    && apt-get install -y --no-install-recommends nodejs \
+    && rm -rf /var/lib/apt/lists/*
+
+# --- Package managers -------------------------------------------------------
+# corepack exposes pnpm/yarn (and npm) shims that honor each repo's
+# packageManager pin (e.g. "pnpm@11.6.0"); a repo pin not matching the
+# pre-fetched versions is still downloaded on first use. Pre-fetch the
+# current pnpm/yarn (incl. pnpm's native binary, pulled on first run) at
+# build time so first use inside a pod is offline-fast.
+RUN corepack enable \
+    && corepack prepare pnpm@latest --activate \
+    && corepack prepare yarn@latest --activate \
+    && pnpm --version >/dev/null \
+    && yarn --version >/dev/null
+
+# --- Native module build headers ---------------------------------------------
+# Headers for node-gyp / prebuild-install so native npm packages (sharp,
+# bcrypt, sqlite3, ...) compile at npm install time instead of failing.
+RUN apt-get update && apt-get install -y --no-install-recommends \
+        pkg-config \
+        zlib1g-dev libssl-dev libpq-dev libsqlite3-dev libffi-dev \
+        libxml2-dev libxslt1-dev libpng-dev libbz2-dev liblzma-dev \
+        uuid-dev libkrb5-dev libcairo2-dev \
+    && rm -rf /var/lib/apt/lists/*
+
+# --- Coding agents / CLIs ---------------------------------------------------
+# opencode (installer adds PATH for interactive shells only; ENV + profile.d
+# cover non-interactive shells and login shells)
+RUN curl -fsSL https://opencode.ai/install | bash
+ENV PATH="/root/.opencode/bin:${PATH}"
+RUN printf 'export PATH="/root/.opencode/bin:$PATH"\n' > /etc/profile.d/opencode.sh
+# pi (pi.dev)
+RUN npm install -g --ignore-scripts @earendil-works/pi-coding-agent
+# herdr (https://herdr.dev) - terminal multiplexer/runtime for coding agents.
+# Install to /usr/local/bin so it's on PATH for all shells incl. sshd sessions.
+RUN curl -fsSL https://herdr.dev/install.sh | HERDR_INSTALL_DIR=/usr/local/bin sh \
+    && herdr --version
+# turbo (monorepo runner)
+RUN npm install -g turbo
+# extra global npm packages
+RUN if [ -n "${EXTRA_NPM_PACKAGES}" ]; then npm install -g ${EXTRA_NPM_PACKAGES}; fi
+
+# --- Playwright -------------------------------------------------------------
+RUN if [ "${INSTALL_PLAYWRIGHT}" = "true" ]; then \
+        npm install -g playwright \
+        && npx playwright install --with-deps chrome; \
+    fi
+
+# --- Database clients -------------------------------------------------------
+RUN apt-get update && apt-get install -y --no-install-recommends \
+        postgresql-client \
+    && rm -rf /var/lib/apt/lists/*
+
+# --- SSH server -------------------------------------------------------------
+RUN mkdir -p /root/.ssh && \
+    chmod 700 /root/.ssh && \
+    touch /root/.ssh/authorized_keys && \
+    chmod 600 /root/.ssh/authorized_keys && \
+    sed -ri 's/^#?PermitRootLogin.*/PermitRootLogin yes/' /etc/ssh/sshd_config && \
+    sed -ri 's/^#?PasswordAuthentication.*/PasswordAuthentication no/' /etc/ssh/sshd_config && \
+    sed -ri 's/^#?PubkeyAuthentication.*/PubkeyAuthentication yes/' /etc/ssh/sshd_config && \
+    ssh-keygen -A
+# /run may be a fresh tmpfs at start, so recreate the privsep dir at boot.
+# sshd builds each session's environment from scratch (USER/HOME/PATH/SHELL +
+# PAM), so the container's env (image ENV + pod spec) is not visible in SSH
+# sessions; the entrypoint republishes it for login shells.
+RUN cat > /entrypoint.sh <<'ENTRYPOINT' && chmod +x /entrypoint.sh
+#!/bin/bash
+mkdir -p /run/sshd
+: > /etc/profile.d/99-container-env.sh
+while IFS= read -r -d '' kv; do
+    name=${kv%%=*}
+    value=${kv#*=}
+    escaped=${value//"'"/"'\\''"}
+    printf "export %s='%s'\n" "$name" "$escaped"
+done < /proc/self/environ >> /etc/profile.d/99-container-env.sh
+exec /usr/sbin/sshd -D "$@"
+ENTRYPOINT
+
+# --- Workspace --------------------------------------------------------------
+RUN mkdir -p /workspace
+WORKDIR /workspace
+# Land in /workspace on every interactive login
+RUN printf '\ncd /workspace 2>/dev/null || cd ~\n' >> /root/.bashrc \
+    && printf '\ncd /workspace 2>/dev/null || cd ~\n' >> /root/.profile
+
+EXPOSE 22
+
+ENTRYPOINT ["/entrypoint.sh"]

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Esuyo
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,95 @@
+# Esuyo coding-container
+
+> Spin up a ready-to-code SSH container on your k3s cluster in one command.
+
+`coding-container` gives every project its own consistent coding environment. One command deploys a container with Ubuntu 26.04, Node.js 22, [opencode](https://opencode.ai), [pi](https://pi.dev), [herdr](https://herdr.dev), turbo, Playwright, and common dev tools (plus pnpm/yarn via corepack and a Postgres client) to your k3s cluster. You SSH in and land in `/workspace` — a folder backed by your NAS, so your work survives restarts and stays separate per project.
+
+## Features
+
+- One command to deploy a ready-to-code container (`create`), SSH in (`ssh`), and tear down (`delete`)
+- Persistent per-project workspace on your NAS — files survive restarts
+- Generates a dedicated SSH key; VS Code Remote-SSH ready
+- Optional browser access to dev servers and sidecars for databases and queues
+- Shared team image with versioning, or a custom image per project
+
+## Prerequisites
+
+- Node.js >= 18, Docker, `kubectl` pointed at your k3s cluster
+- `docker login` to your container registry
+- OpenSSH (`ssh`, `ssh-keygen`)
+- Your NAS reachable from the cluster nodes
+
+## Installation
+
+```sh
+npm install -g @esuyo/coding-container
+coding-container --help
+```
+
+Or run from source:
+
+```sh
+npm install
+npm link
+coding-container --help
+```
+
+`npm link` puts `coding-container` on your PATH. Prefer not to link globally? Run it with `node src/index.js ...` instead.
+
+One-time setup (creates your global config and SSH key, never overwrites):
+
+```sh
+coding-container setup
+```
+
+## Configuration
+
+Two small YAML files drive everything: a global config for your environment (`~/.config/coding-container/config.yaml`) and a per-project `config.yaml` for what differs per project.
+
+```yaml
+project: my-project
+k8s:
+  nodePort: 30022
+```
+
+See [Configuration](./docs/configuration.md) for layering, multiple projects, and NAS folders.
+
+## Quick Start
+
+```sh
+coding-container create   # deploy this project
+coding-container ssh      # connect — you land in /workspace
+coding-container delete   # remove cluster resources (files stay safe on the NAS)
+```
+
+Working in another folder? `cd` there and run `create` — a minimal `config.yaml` is scaffolded automatically. Each project gets its own container and workspace.
+
+For everything else — web URLs, databases, image versions, all commands and flags — see [CLI reference](./docs/cli-reference.md) and the guides below.
+
+## Troubleshooting
+
+- **Missing registry or NAS settings?** Run `coding-container setup`.
+- **Push auth error?** Run `docker login <your-registry>` first.
+- **Pod stuck?** Usually NFS or image pull — see [Troubleshooting](./docs/troubleshooting.md).
+
+## License
+
+MIT — see [LICENSE](./LICENSE).
+
+## Developer Documentation
+
+- [Configuration](./docs/configuration.md) — Config layering, multiple projects, NAS volumes
+- [Shared global image](./docs/global-image.md) — Team image versions, publishing, rollback, cleanup
+- [Web access](./docs/web-access.md) — Browser access to dev servers via Traefik
+- [Sidecars](./docs/sidecars.md) — Databases, queues, and other pod companions
+- [CLI reference](./docs/cli-reference.md) — All commands and flags
+- [SSH and VS Code](./docs/ssh-and-vscode.md) — Key rotation and Remote-SSH setup
+- [Troubleshooting](./docs/troubleshooting.md) — Common failures and fixes
+- [Architecture](./docs/architecture.md) — Tech stack and system design
+- [Project Structure](./docs/project-structure.md) — Folder layout
+- [Development Guide](./docs/development.md) — Local setup for contributors
+- [App config & setup files](./docs/config-files.md) — Persisting tool configs via /workspace
+- [Plan: Additional NFS volumes](./docs/build/additional-volumes.md) — Design history for extra volumes
+- [Plan: Public prebuilt images](./docs/build/public-images.md) — Design history for public images
+
+---

package/config.yaml

@@ -0,0 +1,27 @@
+# Project-specific configuration for this repo's own container.
+#
+# Shared settings (registry, image build, k8s, nfs, ssh) come from the
+# global config at ~/.config/coding-container/config.yaml; CLI flags override
+# everything. Add keys here only for values that differ per project.
+
+project: my-project
+
+k8s:
+  nodePort: 30022
+
+# Expose container ports to the browser through Traefik: one Ingress host per
+# port, each routing to that port on this project's service. The hosts must
+# resolve (DNS) to your Traefik LoadBalancer IP. An optional nodePort
+# (30000-32767) additionally reaches the port on every cluster node at
+# http://<node-ip>:<nodePort>/ (unique across ssh, web.ports, sidecars).
+# web:
+#   ports:
+#     - { port: 3000, host: my-web.example.com, nodePort: 30080 }
+#     - { port: 8080, host: my-api.example.com, name: api }
+
+# Extra NAS folders mounted into the container alongside /workspace. Each
+# subPath is a subfolder of nfs.basePath (created on first mount if missing);
+# readOnly: true makes the mount read-only for the container.
+# nfs:
+#   volumes:
+#     - { subPath: shared-datasets, mountPath: /data, readOnly: true }

package/package.json

@@ -0,0 +1,39 @@
+{
+  "name": "@esuyo/coding-container",
+  "version": "1.0.2",
+  "description": "CLI to build, publish and deploy SSH-accessible coding containers on k3s",
+  "type": "module",
+  "bin": {
+    "coding-container": "src/index.js"
+  },
+  "main": "src/index.js",
+  "scripts": {
+    "start": "node src/index.js",
+    "dev": "node src/index.js",
+    "test": "node --test"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "keywords": [
+    "docker",
+    "kubernetes",
+    "k3s",
+    "ssh",
+    "coding-container",
+    "devcontainer"
+  ],
+  "license": "MIT",
+  "publishConfig": {
+    "access": "public"
+  },
+  "files": [
+    "src/",
+    "Dockerfile",
+    "config.yaml"
+  ],
+  "dependencies": {
+    "commander": "^12.1.0",
+    "js-yaml": "^4.1.0"
+  }
+}

package/src/commands/build.js

@@ -0,0 +1,35 @@
+import { dockerExec, run } from "../utils/exec.js";
+import { imageRef } from "../config.js";
+
+/**
+ * The raw docker build of cfg's image (cfg.image.tag must be set). Used by
+ * custom-mode projects and by `system create` (the only writer of the
+ * global image).
+ */
+export async function buildImage(cfg) {
+  const ref = imageRef(cfg);
+  const args = ["build", "-t", ref, "-f", cfg.image.dockerfilePath];
+  for (const [key, value] of Object.entries(cfg.image.buildArgs || {})) {
+    args.push("--build-arg", `${key}=${value}`);
+  }
+  args.push(cfg.image.contextPath);
+  console.log(`Building image ${ref} ...`);
+  const { cmd, opts } = dockerExec();
+  await run(cmd, args, opts);
+  console.log(`Built ${ref}`);
+}
+
+export async function build(cfg) {
+  if (cfg.imageMode === "global") {
+    throw new Error(
+      "this project uses the shared global image — building here would tag the global repo. " +
+        "Publish a new global version with: coding-container system create --tag vX.Y.Z"
+    );
+  }
+  if (!cfg.image.tag) {
+    throw new Error(
+      "custom image mode requires a tag: set image.tag in the project config or pass --tag"
+    );
+  }
+  await buildImage(cfg);
+}

package/src/commands/create.js

@@ -0,0 +1,38 @@
+import { build } from "./build.js";
+import { push } from "./push.js";
+import { deploy } from "./deploy.js";
+
+/**
+ * Global mode: nothing is built or pushed here — the shared image is
+ * managed by `system create`, and deploy floats on the cluster ConfigMap.
+ * Custom mode: build + push the project's own image (coding-<project>),
+ * then deploy.
+ */
+export async function create(cfg, { skipBuild = false, skipPush = false } = {}) {
+  if (cfg.imageMode === "global") {
+    if (skipBuild || skipPush) {
+      console.log(
+        "Global image mode: no build/push happens here — the shared image is managed by " +
+          "'coding-container system create'."
+      );
+    }
+    await deploy(cfg);
+  } else {
+    if (skipBuild) {
+      console.log("Skipping build");
+    } else {
+      await build(cfg);
+    }
+    if (skipPush) {
+      console.log("Skipping push");
+    } else {
+      await push(cfg);
+    }
+    await deploy(cfg);
+  }
+
+  console.log(`
+Done. Connect with:
+  coding-container ssh
+`);
+}

package/src/commands/delete.js

@@ -0,0 +1,24 @@
+import { run } from "../utils/exec.js";
+import { removeHostEntry, sshAlias, sshConfigPath } from "../utils/ssh-config.js";
+
+export async function deleteProject(cfg, { keepSecrets = false } = {}) {
+  const ns = cfg.k8s.namespace;
+  await run("kubectl", ["delete", "deployment", cfg.project, "-n", ns, "--ignore-not-found"]);
+  await run("kubectl", ["delete", "service", cfg.project, "-n", ns, "--ignore-not-found"]);
+  await run("kubectl", ["delete", "ingress", cfg.project, "-n", ns, "--ignore-not-found"]);
+  if (!keepSecrets) {
+    await run("kubectl", ["delete", "configmap", `${cfg.project}-ssh`, "-n", ns, "--ignore-not-found"]);
+    await run("kubectl", ["delete", "secret", `${cfg.project}-env`, "-n", ns, "--ignore-not-found"]);
+  }
+  console.log(`Deleted ${cfg.project} from namespace ${ns}`);
+
+  // Drop the SSH alias for the container.
+  try {
+    const alias = sshAlias(cfg.project);
+    if (removeHostEntry(alias)) {
+      console.log(`Removed SSH alias "${alias}" from ${sshConfigPath()}`);
+    }
+  } catch (err) {
+    console.warn(`Warning: could not update SSH config: ${err.message}`);
+  }
+}

package/src/commands/deploy.js

@@ -0,0 +1,138 @@
+import path from "node:path";
+import { exec, run, runWithInput } from "../utils/exec.js";
+import { ensureKeyPair, readPublicKey } from "../utils/keys.js";
+import { ensurePullSecret } from "../utils/registry.js";
+import { fullManifest, webPorts, sidecarNodePorts as sidecarNodePortsList } from "../utils/manifest.js";
+import { imageRef } from "../config.js";
+import { addHostEntry, sshAlias, sshConfigPath } from "../utils/ssh-config.js";
+import { findNodePortOwner } from "../utils/project.js";
+import { kubectlExec, resolveDeployTag, SYSTEM_CM_NAME } from "../utils/system-config.js";
+
+export async function ensureNamespace(ns) {
+  const { cmd, args, opts } = kubectlExec();
+  try {
+    exec(cmd, [...args, "get", "namespace", ns], opts);
+  } catch {
+    console.log(`Creating namespace ${ns} ...`);
+    await run(cmd, [...args, "create", "namespace", ns], opts);
+  }
+}
+
+export async function deploy(cfg, { wait = true } = {}) {
+  // Tag resolution (the float): custom mode uses the project pin; global
+  // mode uses the project pin/--tag when set, else the ConfigMap's current.
+  const hadExplicitTag = Boolean(cfg.image.tag);
+  cfg.image.tag = resolveDeployTag(cfg);
+  if (cfg.imageMode === "global" && !hadExplicitTag) {
+    console.log(
+      `Global image mode: deploying version ${cfg.image.tag} from the ${SYSTEM_CM_NAME} ConfigMap ` +
+        `('system get' to inspect, 'system rollback' to repoint, 'system create --tag vX.Y.Z' to publish new).`
+    );
+  }
+
+  const { public: publicPath } = ensureKeyPair(cfg.ssh.keyDirPath, cfg.ssh.keyName);
+  const publicKey = readPublicKey(publicPath);
+
+  const ns = cfg.k8s.namespace;
+  await ensureNamespace(ns);
+
+  // Fail fast on a taken NodePort: applying anyway leaves a partial state
+  // (deployment + ingress created, service invalid).
+  if (cfg.k8s.serviceType === "NodePort") {
+    const wanted = [
+      [cfg.k8s.nodePort, "k8s.nodePort (SSH)"],
+      ...webPorts(cfg)
+        .filter((p) => p.nodePort !== undefined)
+        .map((p) => [p.nodePort, `web port "${p.name}"`]),
+      ...sidecarNodePortsList(cfg).map((p) => [p.nodePort, `sidecar port "${p.name}"`]),
+    ];
+    for (const [port, what] of wanted) {
+      const owner = findNodePortOwner(port);
+      // Our own service (redeploy with an unchanged port) is not a conflict.
+      if (owner && !(owner.namespace === ns && owner.name === cfg.project)) {
+        throw new Error(
+          `nodePort ${port} (${what}) is already allocated to service "${owner.name}" ` +
+            `in namespace "${owner.namespace}"; pick another port (30000-32767) in config.yaml`
+        );
+      }
+    }
+  }
+
+  const pullSecret = await ensurePullSecret(cfg);
+
+  const manifest = fullManifest(cfg, publicKey, pullSecret);
+  const { cmd: kubectl, args: kargs, opts: kopts } = kubectlExec();
+  console.log(`Deploying ${imageRef(cfg)} to namespace ${cfg.k8s.namespace} ...`);
+  await runWithInput(kubectl, [...kargs, "apply", "-f", "-"], manifest, kopts);
+
+  if (wait) {
+    console.log("Waiting for rollout to complete ...");
+    await run(kubectl, [
+      ...kargs,
+      "rollout",
+      "status",
+      `deployment/${cfg.project}`,
+      "-n",
+      cfg.k8s.namespace,
+      "--timeout=300s",
+    ], kopts);
+  }
+  console.log(`Deployed ${cfg.project} in ${cfg.k8s.namespace}`);
+
+  // Node IP for the NodePort hints below and the SSH alias.
+  let nodeIp;
+  try {
+    nodeIp = exec(kubectl, [
+      ...kargs,
+      "get",
+      "nodes",
+      "-o",
+      "jsonpath={.items[0].status.addresses[?(@.type==\"InternalIP\")].address}",
+    ], kopts);
+  } catch {
+    /* handled below */
+  }
+
+  const web = webPorts(cfg);
+  if (web.length) {
+    console.log("Web (Traefik Ingress):");
+    for (const p of web) {
+      console.log(`  http://${p.host}/  (container port ${p.port})`);
+    }
+    const webNodePorts = web.filter((p) => p.nodePort !== undefined);
+    if (webNodePorts.length) {
+      console.log("Web NodePorts (reachable on any cluster node):");
+      for (const p of webNodePorts) {
+        console.log(`  http://${nodeIp ?? "<node-ip>"}:${p.nodePort}/  (container port ${p.port})`);
+      }
+    }
+  }
+
+  const sidecarNodePorts = sidecarNodePortsList(cfg);
+  if (sidecarNodePorts.length) {
+    console.log("Sidecar NodePorts (reachable on any cluster node):");
+    for (const p of sidecarNodePorts) {
+      console.log(`  ${p.name}: ${nodeIp ?? "<node-ip>"}:${p.nodePort}  (container port ${p.port})`);
+    }
+  }
+
+  // Register an SSH alias for the container (VS Code Remote-SSH / ssh).
+  if (nodeIp) {
+    try {
+      const alias = sshAlias(cfg.project);
+      addHostEntry({
+        alias,
+        hostName: nodeIp,
+        port: cfg.k8s.nodePort,
+        user: cfg.ssh.user,
+        identityFile: path.join(cfg.ssh.keyDirPath, cfg.ssh.keyName),
+        knownHostsFile: path.join(cfg.ssh.keyDirPath, `${cfg.project}-known_hosts`),
+      });
+      console.log(`SSH alias "${alias}" written to ${sshConfigPath()} (connect: ssh ${alias})`);
+    } catch (err) {
+      console.warn(`Warning: could not update SSH config: ${err.message}`);
+    }
+  } else {
+    console.warn("Warning: could not resolve a node IP; skipped the SSH alias in ~/.ssh/config");
+  }
+}