cartagodocker/zsh repository overview

⁠🐳 cartagodocker/zsh

Ubuntu 24.04 LTS with zsh as the default interactive shell — Oh My Zsh, Powerlevel10k, eza, bat, git, passwordless sudo.

Base for others (e.g. cartagodocker/nodebun⁠). Root, uid 1000 (ubuntu), and later useradd -m users share .zshrc / .p10k.zsh / Oh My Zsh via /usr/share/globally.

The nodebun README⁠ uses the same section order. This page is the shell-base contract; NodeBun only documents runtimes it adds.

Pin a version tag. No latest in production.

FROM cartagodocker/zsh:v2.0.0

⁠📦 What's in the image

No openssh-server, no ENTRYPOINT: docker run / Compose command: is the process.

Not in this image (shell base): gcc/g++, python3, neovim, git-lfs, rclone, locales, man-db, nmap, file, 7zip, xmllint, git-extras, gpg/gnupg, expect/Tcl, dig/nslookup (bind9-dnsutils / libicu), iperf3, rlwrap, no sshd, no Docker (dockerd / docker CLI). Those — or a Docker client / commit signing — go in a child or on the host.

Container IP: ip -4 addr. DNS: /etc/resolv.conf. Resolve: getent hosts github.com (same as curl/git). Daily CLI: Utilities⁠. Small extras (tcpdump, htpasswd) stay.

⁠🧰 Utilities

Extra CLIs we install (Ubuntu already has cp, mv, grep, awk, sed, find, top, …). Each table is name → docs. Image caveats: interactive zsh/bash/sh alias ls→eza and cat→bat (--paging=never; rcat is GNU cat); GNU ls/find stay; Debian names batcat/fdfind; jsontools uses jq (no node/python/ruby); Tab stays native (no fzf-tab / zsh-autocomplete); no vscode/fasd; no sshd; no gcc. In-container: dockerzsh --help.

⁠Shells

zsh is CMD. Interactive bash: eza/bat, zoxide, fzf keys, Tab, ble.sh, green/red ❯. Interactive sh: eza + zoxide (no fzf keys). sh -c stays POSIX. Plugins: interactive zsh only (dockerzsh --plugins).

⁠Listing / viewing

⁠Edit / data

⁠Archives / text

⁠Network

No dig. IP: ip -4 addr. DNS: /etc/resolv.conf. Resolve: getent hosts github.com. ping/tcpdump often need NET_RAW / NET_ADMIN.

⁠System / git / process

⁠Extras

fzf keys (Ctrl-R / Ctrl-T / Alt-C) in interactive zsh/bash only. Tab stays native. dash: no fzf keys. z is zoxide.

⁠Image helpers (ours)

Not Ubuntu packages. ssh/scp/sftp/git on PATH wrap these — type the normal commands.

⁠📏 Image size

v1.0.5 was zsh + eza/bat/git. v2.0.0 is a daily-driver kit without ICU/Python/gnupg/7zip. Ubuntu git still pulls Perl. Not shipped (child if needed): xmllint, git-extras, file, 7zip, gpg, expect/Tcl, dig/nslookup, iperf3, rlwrap. rsync stays (C; no Python / rrsync). docker images is uncompressed; Hub pull is gzip. Oh My Zsh + p10k are in both 1.0.5 and 2.0.0.

⁠▶️ How to run it

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

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

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

docker run --rm -it cartagodocker/zsh:v2.0.0
docker run --rm -it --user 1000:1000 -w /home/ubuntu cartagodocker/zsh:v2.0.0
docker exec -it <container> zsh

ls → eza. bat works. p10k is the same classic 2-line wizard as v1.0.5 (gitstatusd baked at build). Starting in / shows a lock (DIR_SHOW_WRITABLE) for uid 1000 — use -w /home/ubuntu or bind the project. Inside zsh: bash, sh, exit. Interactive bash/sh also alias ls→eza (zoxide; bash gets fzf keys) — no p10k. sh -c / Dockerfile RUN load no aliases.

⁠🧊 Keep-alive (Compose)

The container stays up without a shell. Typical:

services:
  app:
    image: cartagodocker/zsh:v2.0.0
    command: ["tail", "-f", "/dev/null"]
    user: "1000:1000"

That process is tail, not a shell, and not a TTY. No prompt, no eza aliases, no p10k. Attach:

docker compose exec app zsh     # prompt + eza + bat + p10k
docker compose exec app bash

docker run --rm image bash and docker run --rm image tail -f /dev/null work — no ENTRYPOINT swallows the command.

⁠🔐 sudo

Default NOPASSWD (ALL ALL=(ALL:ALL) NOPASSWD:ALL). Global files (/usr/share/globally/.zshrc) are 644 root:root — uid 1000 cannot overwrite them. Use sudo or add_text_to_zshrc (NOPASSWD). Password is not baked; turn it on at runtime.

docker run --rm -it --user 1000:1000 cartagodocker/zsh:v2.0.0
# inside:
sudo -n id                 # default: no password

sudo-password              # TTY prompt (hidden); afterwards sudo asks
sudo-password 'secret'     # from arg (visible in `ps`)
SUDO_PASSWORD=secret sudo-password   # from env

sudo-password 'new-secret' # change it (needs the *current* sudo password
                           # once one is already required)
sudo-nopasswd              # back to NOPASSWD (needs the current password)

At start (first interactive/login shell via apply-sudo-password-on-boot.sh):

docker run --rm -it -e SUDO_PASSWORD=secret cartagodocker/zsh:v2.0.0

As uid 1000: NOPASSWD (default) escalates with sudo -n. Once a password is on, the helper uses sudo — type the current password, then it sets the new one (or drops it).

sudo-password writes /etc/container-sudo-password, switches sudoers NOPASSWD:ALL → ALL, and chpasswds every login user. Changing it overwrites that file and re-runs chpasswd. sudo -k drops the ticket cache. Compose user: "1000:1000" drops extra groups, so the rule is ALL, not %sudo.

⁠🎨 Fonts and icons

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. No in-image fallback still looks like p10k.

⁠🧩 Scripts for child images

All write /usr/share/globally/... (every user). sudo if needed.

⁠add_text_to_zshrc

add_text_to_zshrc "alias hello='echo hi'"
add_text_to_zshrc "alias hello='echo hi'" --prepend
add_text_to_zshrc "$(printf '%s\n' \
    'alias hello="echo hi"' \
    'alias bye="echo bye"')"

FROM cartagodocker/zsh:v2.0.0
RUN add_text_to_zshrc "$(printf '%s\n' \
    'alias hello="echo hi"')"

⁠add_text_to_p10k

Same CLI, writes .p10k.zsh.

add_text_to_p10k "typeset -g POWERLEVEL9K_INSTANT_PROMPT=verbose"

⁠share_config_globally

Move a path from a user home (default /root) to /usr/share/<name> and symlink it for /root, /home/*, /etc/skel.

share_config_globally .local/share/fnm
share_config_globally .oh-my-zsh --to globally/.oh-my-zsh --permissions 755

--permissions default 755. Use 777 only when every uid must write the shared tree (package caches).

⁠🔑 SSH (client only — no sshd)

openssh-client is installed. Bind host ~/.ssh and type ssh / git. Root or any uid — one volume.

services:
  dev:
    image: cartagodocker/zsh:v2.0.0
    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/zsh:v2.0.0
# 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 → /cartago/.ssh), not ${USER}/.ssh (not $HOME in the container). The client finds any bind ending in .ssh and copies keys to a uid-owned 700 dir (OpenSSH rejects 644/777 and cannot write known_hosts on :ro). Root or any uid.

Git author is not the SSH key. git pull/push use the key; git commit needs user.name + user.email. Bind host ~/.gitconfig (or GIT_AUTHOR_NAME + GIT_AUTHOR_EMAIL). Any absolute path ending in .gitconfig works. Without it, git commit says identity is required and exits 1 — no invented ubuntu@<container>.

Missing keys: ssh/scp/sftp print keys are required (bind example; another directory is fine), then OpenSSH still runs.

known_hosts is optional. Binding ~/.ssh brings the host file if present.

Without a host known_hosts, GitHub / GitLab still work from the baked file. Other hosts are learned on first connect and stay in /tmp for this container.

Agent (key never enters the container) still works if you already use one:

docker run --rm -it \
  -v "$SSH_AUTH_SOCK":/ssh-agent \
  -e SSH_AUTH_SOCK=/ssh-agent \
  cartagodocker/zsh:v2.0.0

Not SSH-into-the-container. Attach: docker exec -it … zsh.

⁠📖 Catalogue CLI (dockerzsh)

In-container dockerzsh catalogues every tool and helper — not the host docker CLI.

docker run --rm cartagodocker/zsh:v2.0.0 dockerzsh --help
docker compose exec app dockerzsh --help

The full dump is long on purpose. Filter by section:

dockerzsh --sections | -s       # list ids
dockerzsh --shells              # one section
dockerzsh --plugins             # Oh My Zsh plugins (interactive zsh)
dockerzsh shells                # same (flag or bare id)
dockerzsh --section shells      # same
dockerzsh shells network        # several sections
dockerzsh --version | -v        # image identity (ZSH_IMAGE_VERSION)
dockerzsh --list | -l           # tool names
dockerzsh --list --version | -l -v   # probe every catalogue tool now
dockerzsh shells --version | shells -v
dockerzsh eza --version | eza -v

Unknown ids exit 2 (--sections). --shells and shells are the same id (listing also accepts --ls).

⁠🚀 Build and publish

docker build --build-arg VERSION=2.0.0 -t zsh-local:dev -f ./Dockerfile ./

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

See CHANGELOG.md⁠.