Add zsh support and docs

Author: coretl

Dockerfile

@@ -6,11 +6,16 @@ FROM ubuntu:noble-20250714
 RUN apt-get update && apt-get install -y --no-install-recommends \
     build-essential \
     busybox \
+    ca-certificates \
     curl \
     gdb \
     git \
     man-db \
-    ssh-client
+    ssh-client \
+    zsh
+
+# Add oh my zsh
+RUN sh -c "$(curl -fsSL https://raw.githubusercontent.com/ohmyzsh/ohmyzsh/master/tools/install.sh)"
 
 # Use busybox to provide any missing commands
 # This is useful for commands like `telnet` that are not available in the base image
@@ -25,8 +30,8 @@ ENV USER_TERMINAL_CONFIG=/user-terminal-config
 # This can be overridden by the user mounting a different folder over the top
 RUN /root/terminal-config/ensure-user-terminal-config.sh && \
     ln -fs $USER_TERMINAL_CONFIG/inputrc /root/.inputrc && \
-    echo 'source ${USER_TERMINAL_CONFIG}/bashrc' >> /root/.bashrc && \
-    echo 'source ${USER_TERMINAL_CONFIG}/zshrc' >> /root/.zshrc
+    ln -fs $USER_TERMINAL_CONFIG/bashrc /root/.bash_aliases && \
+    echo 'source ${USER_TERMINAL_CONFIG}/zshrc' > /root/.zshrc
 
 # Install uv using the official image
 # See https://docs.astral.sh/uv/guides/integration/docker/#installing-uv

README.md

@@ -1,2 +1,76 @@
 # ubuntu-devcontainer
-Opinionated Ubuntu based devcontainer for python and EPICS development
+
+Opinionated Ubuntu based devcontainer for python and EPICS development, tagged in step with upstream ubuntu for runtime.
+
+Features:
+- User customisable bash/zsh environment
+- Cross container persistent shell history
+- git, curl make and other build-essentials
+- uv for python environment management
+- ssh, gdb and busybox for runtime debugging
+
+## How to use from the commandline
+
+To try it out without persistent shell history:
+
+```bash
+podman run -it ghcr.io/diamondlightsource/ubuntu-devcontainer
+```
+
+To keep the history and allow shell customisation:
+
+```bash
+mkdir -p $HOME/.config/terminal-config
+podman run --mount type=bind,src=$HOME/.config/terminal-config,target=/user-terminal-config -it ghcr.io/diamondlightsource/ubuntu-devcontainer 
+```
+
+To do the above but with zsh:
+
+```bash
+mkdir -p $HOME/.config/terminal-config
+podman run --mount type=bind,src=$HOME/.config/terminal-config,target=/user-terminal-config -it ghcr.io/diamondlightsource/ubuntu-devcontainer zsh
+```
+
+## How to customize your shell
+
+When mounting in `$HOME/.config/terminal-config`, the container will create the following files in the directory:
+- `bashrc`: loading some bash defaults
+- `zshrc`: loading some zsh defaults
+- `inputrc`: to customize the behaviour of up arrow etc in both shells
+
+You are free to edit any of these files, adding overrides before or after the loading of the defaults, or even removing the loading of the defaults altogether.
+
+History is also stored in this directory, in `.bash_eternal_history` and `.zsh_eternal_history` respectively.
+
+## How to use as a devcontainer
+
+See [this repo's `.devcontainer.json`](./.devcontainer.json) for an example on how to use as a devcontainer. Or clone this repo, open in vscode and click "reopen in container"
+
+## How to use in the build stage of a Dockerfile
+
+If you are using this during the build stage of a Dockerfile, then you should select the upstream `ubuntu` container for the runtime.
+
+For instance:
+
+```Dockerfile
+# The developer stage is used as a devcontainer including dev versions
+# of the build dependencies
+FROM ghcr.io/diamondlightsource/ubuntu-devcontainer:noble AS developer
+RUN apt-get update -y && apt-get install -y --no-install-recommends \
+    libevent-dev \
+    libreadline-dev
+
+# The build stage makes some assets using the developer tools
+FROM developer AS build
+RUN my-build-script.sh /assets
+
+# The runtime stage installs runtime deps then copies in built assets
+# This time we remove the apt lists to save disk space
+FROM ubuntu:noble as runtime 
+RUN apt-get update -y && apt-get install -y --no-install-recommends \
+    libevent \
+    libreadline \
+    && rm -rf /var/lib/apt/lists/*
+COPY --from=build /assets /
+```
+

terminal-config/bashrc-default

@@ -1,30 +1,20 @@
 #!/bin/bash
 
-# default opinioned bash configuration to be sourced from user's bashrc
-
-# enable enternal shared history
-export HISTCONTROL=ignoreboth:erasedups
-export HISTSIZE=-1
-export HISTFILESIZE=-1
-export SAVEHIST=-1
-export HISTFILE=$USER_TERMINAL_CONFIG/.bash_eternal_history
-export PROMPT_COMMAND="history -a; $PROMPT_COMMAND"
-
-# bash theme - partly inspired by https://github.com/ohmyzsh/ohmyzsh/blob/master/themes/dst.zsh-theme
+# bash theme - partly inspired by https://github.com/ohmyzsh/ohmyzsh/blob/master/themes/robbyrussell.zsh-theme
 # from https://github.com/devcontainers/features/blob/main/src/common-utils/scripts/bash_theme_snippet.sh
 __bash_prompt() {
     local userpart='`export XIT=$? \
         && echo -n "\u " \
         && [ "$XIT" -ne "0" ] && echo -n "\[\033[1;31m\]➜" || echo -n "\[\033[0m\]➜"`'
     local gitbranch='`\
-            export BRANCH="$(git --no-optional-locks symbolic-ref --short HEAD 2>/dev/null || git --no-optional-locks rev-parse --short HEAD 2>/dev/null)"; \
-            if [ "${BRANCH:-}" != "" ]; then \
-                echo -n "\[\033[0;36m\](\[\033[1;32m\]${BRANCH:-}" \
-                && if git --no-optional-locks ls-files --error-unmatch -m --directory --no-empty-directory -o --exclude-standard ":/*" > /dev/null 2>&1; then \
-                        echo -n " \[\033[1;33m\]✗"; \
-                fi \
-                && echo -n "\[\033[0;36m\]) "; \
-            fi`'
+        export BRANCH="$(git --no-optional-locks symbolic-ref --short HEAD 2>/dev/null || git --no-optional-locks rev-parse --short HEAD 2>/dev/null)"; \
+        if [ "${BRANCH:-}" != "" ]; then \
+            echo -n "\[\033[0;36m\](\[\033[1;32m\]${BRANCH:-}" \
+            && if git --no-optional-locks ls-files --error-unmatch -m --directory --no-empty-directory -o --exclude-standard ":/*" > /dev/null 2>&1; then \
+                    echo -n " \[\033[1;33m\]✗"; \
+            fi \
+            && echo -n "\[\033[0;36m\]) "; \
+        fi`'
     local removecolor='\[\033[0m\]'
     local lightblue='\[\033[1;34m\]'
     local cyan='\[\033[0;36m\]'
@@ -34,23 +24,16 @@ __bash_prompt() {
 __bash_prompt
 export PROMPT_DIRTRIM=4
 
-# Set the default git editor if not already set
-# from https://github.com/devcontainers/features/blob/f8e7e275b7ba2808e14a035afd753b83be68e2d9/src/common-utils/scripts/rc_snippet.sh
-if [ -z "$(git config --get core.editor)" ] && [ -z "${GIT_EDITOR}" ]; then
-    if  [ "${TERM_PROGRAM}" = "vscode" ]; then
-        if [[ -n $(command -v code-insiders) &&  -z $(command -v code) ]]; then
-            export GIT_EDITOR="code-insiders --wait"
-        else
-            export GIT_EDITOR="code --wait"
-        fi
-    fi
-fi
-
-# colorize ls output
-export LS_OPTIONS='--color=auto'
-eval "$(dircolors)"
-alias ls='ls $LS_OPTIONS'
-alias ll='ls $LS_OPTIONS -l'
+# enable enternal shared history
+export HISTCONTROL=ignoreboth:erasedups
+export HISTSIZE=-1
+export HISTFILESIZE=-1
+export SAVEHIST=-1
+export HISTFILE=$USER_TERMINAL_CONFIG/.bash_eternal_history
+export PROMPT_COMMAND="history -a; $PROMPT_COMMAND"
 
 # enable bash completion for git
 source /usr/share/bash-completion/completions/git
+
+# Setup some common defaults like vscode for the git editor
+source "$HOME/terminal-config/common-defaults"

terminal-config/bashrc-template

@@ -1,12 +1,14 @@
 #!/bin/bash
 
-# This bashrc will be source from /root/.bashrc upon launch of every terminal
-# in a devcontainer that uses the bash-config feature from
-# https://github.com/DiamondLightSource/devcontainer-features
+# This bashrc will be sourced from /root/.bashrc upon launch of every terminal
+# in a devcontainer that uses the ubuntu-devcontainer as a base
+# https://github.com/DiamondLightSource/ubuntu-devcontainer
 
-# This file is initialized by bash-config, but you are then free to edit it
+# This file is initialized by the devcontainer, but you are then free to edit it
 
-# execute default, opinionated settings - delete this line to remove defaults
+# Execute default, opinionated settings:
+# https://github.com/DiamondLightSource/ubuntu-devcontainer/blob/main/terminal-config/bashrc-default
+# delete this line to remove defaults
 source ~/terminal-config/bashrc-default
 
 if [ ! -f ~/one-time ]; then

terminal-config/common-defaults

@@ -0,0 +1,11 @@
+# Set the default git editor if not already set
+# from https://github.com/devcontainers/features/blob/f8e7e275b7ba2808e14a035afd753b83be68e2d9/src/common-utils/scripts/rc_snippet.sh
+if [ -z "$(git config --get core.editor)" ] && [ -z "${GIT_EDITOR}" ]; then
+    if  [ "${TERM_PROGRAM}" = "vscode" ]; then
+        if [[ -n $(command -v code-insiders) &&  -z $(command -v code) ]]; then
+            export GIT_EDITOR="code-insiders --wait"
+        else
+            export GIT_EDITOR="code --wait"
+        fi
+    fi
+fi

terminal-config/zshrc-default

@@ -1,17 +1,16 @@
 #!/bin/zsh
 
-# This zshrc will be source from /root/.zshrc upon launch of every terminal
-# in a devcontainer that uses the bash-config feature from
-# https://github.com/DiamondLightSource/devcontainer-features
+# Set the prompt theme to robbyrussell if not already set
+ZSH_THEME=${ZSH_THEME:-robbyrussell}
 
-# This file is initialized by vscode feature bash-config,
-# but you are then free to edit it
+# Source oh my zsh, theme and plugins must be set before this
+source "$HOME/.oh-my-zsh/oh-my-zsh.sh"
 
-# set up eternal history for zsh
+# Set up eternal history for zsh
 HISTCONTROL=ignoreboth:erasedups
 HISTSIZE=10000000
 SAVEHIST=$HISTSIZE
-HISTFILE=$CONFIG_FOLDER/.zsh_eternal_history
+HISTFILE=$USER_TERMINAL_CONFIG/.zsh_eternal_history
 setopt BANG_HIST                 # Treat the '!' character specially during expansion.
 setopt EXTENDED_HISTORY          # Write the history file in the ":start:elapsed;command" format.
 setopt INC_APPEND_HISTORY        # Write to the history file immediately, not when the shell exits.
@@ -24,7 +23,6 @@ setopt HIST_IGNORE_SPACE         # Don't record an entry starting with a space.
 setopt HIST_SAVE_NO_DUPS         # Don't write duplicate entries in the history file.
 setopt HIST_REDUCE_BLANKS        # Remove superfluous blanks before recording entry.
 setopt HIST_VERIFY               # Don't execute immediately upon history expansion.
-#setopt HIST_BEEP                # Beep when accessing nonexistent history.
 
-# set a theme compatible with vscode terminals
-ZSH_THEME="dst"
+# Setup some common defaults like vscode for the git editor
+source "$HOME/terminal-config/common-defaults"

terminal-config/zshrc-template

@@ -1,12 +1,14 @@
 #!/bin/zsh
 
-# This zshrc will be source from /root/.zshrc upon launch of every terminal
-# in a devcontainer that uses the bash-config feature from
-# https://github.com/DiamondLightSource/devcontainer-features
+# This zshrc will be sourced from /root/.zshrc upon launch of every terminal
+# in a devcontainer that uses the ubuntu-devcontainer as a base
+# https://github.com/DiamondLightSource/ubuntu-devcontainer
 
-# This file is initialized by bash-config, but you are then free to edit it
+# This file is initialized by the devcontainer, but you are then free to edit it
 
-# execute default, opinionated settings - delete this line to remove defaults
+# Execute default, opinionated settings:
+# https://github.com/DiamondLightSource/ubuntu-devcontainer/blob/main/terminal-config/zshrc-default
+# delete this line to remove defaults
 source ~/terminal-config/zshrc-default
 
 if [ ! -f ~/one-time ]; then