cartagodocker/nodebun repository overview

⁠🟢 cartagodocker/nodebun

Node, npm, bun, and fnm on top of cartagodocker/zsh⁠ (Ubuntu 24.04 LTS + zsh + Oh My Zsh + Powerlevel10k).

Same layout as the zsh README⁠. This page only expands what NodeBun adds. Shell, sudo, SSH, fonts, and the daily CLI are inherited — details live there.

Tags are exact. There is no latest / stable. Pin the matrix you need.

FROM cartagodocker/nodebun:v2.0.2_n26.3.1_b1.4.2

⁠📦 What's in the image

No openssh-server, no ENTRYPOINT: docker run / Compose command: is the process (node --version works on zsh 2.0.0).

Not in this image (same as zsh): gcc/g++, python3, neovim, git-lfs, rclone, locales, man-db, nmap, no sshd, no Docker. NodeBun does not add a second CLI kit — only runtimes: fnm, one Node (matrix), npm, two bun binaries (AVX2 + baseline), libatomic1. Compilers / Docker client go in a further child. Drive this container with host docker.

sudo / dockerzsh / add_text_to_* come from cartagodocker/zsh:v2.0.0. Not reinstalled; no fallback for older zsh tags.

⁠🧰 Utilities

From zsh (not reinstalled): zsh README — Utilities⁠ (name → docs). Same aliases (ls→eza in interactive zsh/bash/sh). In-container: dockerzsh --help or dockernodebun --listing.

This image adds the tables below. Usage: Scripts for child images⁠. zsh helpers: zsh README — Scripts⁠ or dockernodebun --zsh-helpers.

⁠Runtimes (NodeBun)

On PATH (/usr/local/bin) for every uid and every shell. libatomic1 is for bun. /usr/local/bin/bun is a bash wrapper (AVX2 vs baseline from /proc/cpuinfo; chatter if BUN_WRAPPER_DEBUG=1). bunx is the same wrapper (bunx pkg → bun x pkg). fnm use is this shell only (FNM_DIR=/usr/share/fnm/store, 777).

⁠NodeBun helpers (ours)

⁠📏 Image size

docker images is uncompressed. Hub pull is gzip layers (smaller). On top of cartagodocker/zsh:v2.0.0.

Two bun builds on purpose: /usr/local/bin/bun is a bash wrapper (bun_wrapper.zsh — historical .zsh name, #!/bin/bash) that picks AVX2 vs baseline from /proc/cpuinfo. That doubles bun on disk. Silent unless BUN_WRAPPER_DEBUG=1. One Node is baked (fnm install of the matrix); extra fnm install at runtime grows FNM_DIR.

Disk ≈ zsh 2.0.0 + Node + two bun + fnm: local smoke ~695 MB uncompressed (Node 26). Hub NodeBun 2.0.0 on zsh 1.0.5 was ~642 MB.

⁠🏷️ Runtime matrices

Defined in .github/matrices.yml⁠:

v{X.Y.Z}_n{node MAJOR.MINOR.PATCH}_b{bun MAJOR.MINOR.PATCH}

Examples: v2.0.2_n22.21.1_b1.4.2, v2.0.2_n26.3.1_b1.4.2.

X.Y.Z counts repo corrections (Dockerfile, wrapper, docs) and is published on all active matrices in parallel. Full policy: VERSIONING.md⁠.

⁠▶️ How to run it

Two different jobs. Mix them up and it looks like “eza is broken”.

Node / bun / npm / fnm are baked at docker build. docker run does not download them. On PATH (/usr/local/bin) for any uid and any shell.

zsh extras (p10k) load from ~/.zshrc and need a TTY. Interactive bash/sh also get ls→eza. node / npm / bun do not need a TTY.

⁠🖥️ Interactive prompt (eza, bat, p10k)

Needs a TTY (-it or exec -it).

# Hub: IMG=cartagodocker/nodebun:v2.0.2_n26.3.1_b1.4.2
IMG=nodebun-local:dev
docker run --rm -it --user 1000:1000 -w /home/ubuntu \
  -v "$HOME/.ssh:/$USER/.ssh:ro" \
  -v "$HOME/.gitconfig:/$USER/.gitconfig:ro" \
  "$IMG"
docker run --rm -it "$IMG"   # root, no bind

ls→eza. bat works. p10k draws the prompt. node/npm/bun work in every shell. Inside zsh: bash, sh, exit. Interactive bash/sh alias ls→eza; no p10k.

⁠🧊 Keep-alive (Compose)

The container stays up without a shell. Typical:

services:
  app:
    image: cartagodocker/nodebun:v2.0.2_n26.3.1_b1.4.2
    command: ["tail", "-f", "/dev/null"]
    user: "1000:1000"
    working_dir: /work
    volumes:
      - .:/work

That process is tail, not zsh, and not a TTY. No prompt, no eza aliases, no p10k. Attach when you want the shell:

docker compose exec app zsh          # prompt + eza + bat + p10k
docker compose exec app bash         # bash; node/npm/bun still on PATH
docker compose exec app bun install

docker run --rm cartagodocker/nodebun:v2.0.2_n26.3.1_b1.4.2 node --version

docker run --rm image bash and docker run --rm image node --version work because there is no ENTRYPOINT swallowing the command (cartagodocker/zsh:v2.0.0).

⁠🔐 sudo

Inherited from zsh. Global files (/usr/share/globally/.zshrc) are 644 root:root — uid 1000 cannot overwrite them. Use sudo or add_text_to_zshrc (NOPASSWD). node/npm/bun do not need sudo.

docker run --rm -it --user 1000:1000 cartagodocker/nodebun:v2.0.2_n26.3.1_b1.4.2
# inside:
sudo -n id                 # default: no password
sudo-password              # prompt; afterwards sudo asks for it
sudo-password 'secret'     # from arg (visible in ps)
sudo-nopasswd              # back to NOPASSWD

Password at start (not baked into the image):

docker run --rm -it -e SUDO_PASSWORD=secret cartagodocker/nodebun:v2.0.2_n26.3.1_b1.4.2

Compose user: "1000:1000" drops extra groups, so the sudoers rule is ALL, not %sudo.

⁠🎨 Fonts and icons

Same contract as cartagodocker/zsh⁠. The container only emits Unicode. The host terminal draws glyphs.

VS Code:

"terminal.integrated.fontFamily": "'Cascadia Code NF', 'CaskaydiaCove Nerd Font', Consolas, monospace"

Without a Nerd Font you get boxes on powerline / ls icons — not an image bug.

⁠🧩 Scripts for child images

⁠From zsh (inherited)

add_text_to_zshrc, add_text_to_p10k, share_config_globally, sudo-password, sudo-nopasswd — same CLI as zsh⁠. Write /usr/share/globally/...; sudo if needed. Full text: dockerzsh --helpers or dockernodebun --zsh-helpers.

⁠NodeBun only

Most people never type these (bash pepe.sh is enough). Same Makefile on host and in-container. Detect /.dockerenv or IS_INTO_CONTAINER=true.

⁠in-bash

bash --login so /etc/profile.d/nodebun.sh loads (BUN_* / FNM_*). For snippets that are not zsh-safe (set -o pipefail, [[ ]], bash arrays). No args: interactive bash.

in-bash
in-bash -c 'set -o pipefail; npm test | tee log'
in-bash script.sh

⁠in-sh

POSIX sh -l (dash + login env). Same idea as in-bash for portable snippets.

in-sh
in-sh -c 'case $1 in *.sh) echo posix ;; esac'
in-sh script.sh

⁠only-in-container

Run CMD only inside this container. No args: exit 0 inside, 1 outside (predicate). Outside with a command: error, exit 1.

only-in-container                  # 0 inside, 1 on the host
only-in-container bun run test     # skip on the host

⁠skip-if-container

No-op inside (exit 0); run CMD on the host. For host-only tools (adb, docker, osascript). No args on the host: error.

skip-if-container adb start-server

Catalogue dump of these four: dockernodebun --helpers.

⁠🔑 SSH (client only — no sshd)

Inherited from zsh. Bind host ~/.ssh and type ssh / git. Root or any uid — one volume. Git author is not the SSH key: bind ~/.gitconfig (or GIT_AUTHOR_NAME + GIT_AUTHOR_EMAIL). Full contract: zsh README — SSH⁠.

services:
  app:
    image: cartagodocker/nodebun:v2.0.2_n26.3.1_b1.4.2
    volumes:
      - ~/.ssh:/${USER}/.ssh:ro
      - ~/.gitconfig:/${USER}/.gitconfig:ro

docker run --rm -it \
  -v "$HOME/.ssh:/$USER/.ssh:ro" \
  -v "$HOME/.gitconfig:/$USER/.gitconfig:ro" \
  cartagodocker/nodebun:v2.0.2_n26.3.1_b1.4.2
# inside: ssh [email protected]
#         git commit   # author = host user.name, not ubuntu@id

${USER} is the host name. Docker needs an absolute target (/${USER}/.ssh), not ${USER}/.ssh. Not SSH-into-the-container — attach with docker exec -it … zsh.

⁠🌍 Environment

Login shells (su -, bash -l) drop Docker ENV. /etc/profile.d/nodebun.sh re-exports NodeBun vars (also from /etc/zsh/zprofile — Ubuntu login zsh does not source /etc/profile). Same script on every matrix. This image’s Node / X.Y.Z live in /usr/share/nodebun/build.env (from ARG at build) and fill only when ENV is unset. Interactive zsh still runs fnm env from .zshrc.

FNM_DIR is 777 (same as bun): any uid can fnm install / fnm use. Homes and /etc/skel get ~/.local/share/fnm → that store, plus ~/.local/state (fnm multishells) owned by that user so fnm env works as uid 1000.

fnm install 20.19.0
fnm use 20.19.0    # this shell only; a new shell is back on the matrix

⁠📖 Catalogue CLI (dockernodebun)

Inside a running container dockernodebun is the zsh catalogue first (dockerzsh --help), then NodeBun extras. Not the host docker CLI.

docker run --rm cartagodocker/nodebun:v2.0.2_n26.3.1_b1.4.2 dockernodebun --help
docker compose exec app dockernodebun --help

The full dump is long on purpose. Filter by section. NodeBun ids stay here; zsh ids go to dockerzsh.

dockernodebun --sections | -s    # zsh ids + NodeBun ids
dockernodebun --runtimes         # node / npm / bun / fnm
dockernodebun --helpers          # in-bash, in-sh, only-in-container, skip-if-container
dockernodebun --zsh-helpers      # add_text_to_zshrc, add_text_to_p10k, share_config_globally, sudo-password, sudo-nopasswd, git-from-host (zsh)
dockernodebun --env              # NODE_DEFAULT_VERSION, FNM_DIR, BUN_*, IS_INTO_CONTAINER
dockernodebun --shells           # zsh section (forwards)
dockernodebun shells env         # mix zsh + NodeBun sections
dockernodebun --version | -v     # image identity (NODEBUN_IMAGE_VERSION)
dockernodebun --list | -l        # tool names (this image + zsh)
dockernodebun --list --version | -l -v
dockernodebun runtimes --version | runtimes -v
dockernodebun node --version | node -v

--helpers on this CLI is NodeBun. zsh helpers: dockernodebun --zsh-helpers or dockerzsh --helpers. Unknown ids exit 2.

⁠🧱 Child image

FROM cartagodocker/nodebun:v2.0.2_n26.3.1_b1.4.2
WORKDIR /app
COPY package.json bun.lock ./
RUN bun install

Keep SHELL ["/bin/sh", "-c"] if you override it (cartagodocker/zsh:v2.0.0 already sets it).

⁠🚀 Build and publish

docker build \
    --build-arg VERSION=2.0.2 \
    --build-arg NODE_DEFAULT_VERSION=26.3.1 \
    --build-arg BUN_VERSION=1.4.2 \
    --build-arg FNM_VERSION=1.39.0 \
    --build-arg NPM_VERSION=12.0.1 \
    -t cartagodocker/nodebun:v2.0.2_n26.3.1_b1.4.2 \
    -f ./Dockerfile ./

The GitHub workflow fills those from .github/matrices.yml.

GitHub Actions (secrets DOCKERHUB_USERNAME, DOCKERHUB_PASSWORD; variable DOCKERHUB_REPO):

git tag v2.0.1
git push origin main v2.0.1

See CHANGELOG.md⁠ and VERSIONING.md⁠.