feat(devcontainer): overhaul dev environment for chatwoot-br fork (#12)

## Summary

Complete overhaul of the devcontainer configuration for the chatwoot-br
fork, introducing a three-layer Docker build chain (base → devx → app),
multi-architecture support (amd64 + arm64), rich developer tooling, and
automated CI/CD for image publishing.

- **Three-layer Docker build**: `Dockerfile.base` (Ruby, Node, Overmind,
GH CLI) → `Dockerfile.devx` (Fish, Neovim, lazygit, delta, yazi,
Playwright, Claude Code, Codex) → `Dockerfile` (thin app layer with deps
+ source)
- **Multi-arch support**: All binary downloads handle `TARGETARCH` for
both amd64 and arm64 (Mac M-series)
- **Security hardening**: API key handling uses file-based storage with
`chmod 600`, shell injection fix in key helper script
- **Persistent mounts**: Claude config, Neovim config, shell history,
and shared code volume survive container rebuilds
- **CI/CD pipeline**: GitHub Actions workflow builds and pushes both
base and devx images to GHCR on `.devcontainer/` changes
- **CLAUDE.md architecture docs**: Added high-level architecture
overview for faster onboarding

## How to test

1. Clone the repo and open in VS Code with Dev Containers extension
2. Verify container builds and starts successfully
3. Confirm Fish shell, Neovim, lazygit, and other devx tools are
available
4. Run `overmind start -f Procfile.dev` to verify Rails + Vite start
correctly
5. On Mac M-series: verify the container runs natively on ARM64

Author: milesibastos

.devcontainer/Dockerfile

@@ -1,18 +1,19 @@
 # The below image is created out of the Dockerfile.base
 # It has the dependencies already installed so that codespace will boot up fast
-FROM ghcr.io/chatwoot/chatwoot_codespace:latest
+ARG DEVX_IMAGE=ghcr.io/chatwoot-br/chatwoot_codespace_devx:latest
+FROM ${DEVX_IMAGE}
 
 # Do the set up required for chatwoot app
-WORKDIR /workspace
+WORKDIR /workspace/chatwoot
 
 # Copy dependency files first for better caching
-COPY package.json pnpm-lock.yaml ./
-COPY Gemfile Gemfile.lock ./
+COPY --chown=vscode:vscode package.json pnpm-lock.yaml ./
+COPY --chown=vscode:vscode Gemfile Gemfile.lock ./
 
 # Install dependencies (will be cached if files don't change)
 RUN pnpm install --frozen-lockfile && \
     gem install bundler && \
     bundle install --jobs=$(nproc)
 
 # Copy source code after dependencies are installed
-COPY . /workspace
+COPY --chown=vscode:vscode . /workspace/chatwoot

.devcontainer/Dockerfile.base

@@ -4,12 +4,13 @@ FROM mcr.microsoft.com/vscode/devcontainers/base:0-${VARIANT}
 
 ENV DEBIAN_FRONTEND=noninteractive
 
-ARG NODE_VERSION
-ARG RUBY_VERSION
-ARG USER_UID
-ARG USER_GID
+ARG NODE_VERSION="24.14.1"
+ARG RUBY_VERSION="3.4.4"
+ARG USER_UID="1000"
+ARG USER_GID="1000"
+ARG TARGETARCH
 ARG PNPM_VERSION="10.2.0"
-ENV PNPM_VERSION ${PNPM_VERSION}
+ENV PNPM_VERSION=${PNPM_VERSION}
 ENV RUBY_CONFIGURE_OPTS=--disable-install-doc
 
 # Update args in docker-compose.yaml to set the UID/GID of the "vscode" user.
@@ -38,14 +39,15 @@ RUN NODE_MAJOR=$(echo $NODE_VERSION | cut -d. -f1) \
         ca-certificates \
         tmux \
         nodejs \
+        unzip \
     && apt-get clean \
     && rm -rf /var/lib/apt/lists/* /tmp/* /var/tmp/*
 
 # Install rbenv and ruby for root user first
 RUN git clone --depth 1 https://github.com/rbenv/rbenv.git ~/.rbenv \
     &&  echo 'export PATH="$HOME/.rbenv/bin:$PATH"' >> ~/.bashrc \
     &&  echo 'eval "$(rbenv init -)"' >> ~/.bashrc
-ENV PATH "/root/.rbenv/bin/:/root/.rbenv/shims/:$PATH"
+ENV PATH="/root/.rbenv/bin/:/root/.rbenv/shims/:$PATH"
 RUN git clone --depth 1 https://github.com/rbenv/ruby-build.git && \
     PREFIX=/usr/local ./ruby-build/install.sh
 
@@ -60,25 +62,26 @@ RUN su - vscode -c "git clone --depth 1 https://github.com/rbenv/rbenv.git ~/.rb
     && su - vscode -c "PATH=\"/home/vscode/.rbenv/bin:\$PATH\" rbenv install $RUBY_VERSION" \
     && su - vscode -c "PATH=\"/home/vscode/.rbenv/bin:\$PATH\" rbenv global $RUBY_VERSION"
 
-# Install overmind and gh in single layer
-RUN curl -L https://github.com/DarthSim/overmind/releases/download/v2.1.0/overmind-v2.1.0-linux-amd64.gz > overmind.gz \
+# Overmind (process manager)
+ARG OVERMIND_VERSION=2.5.1
+RUN OVERMIND_ARCH=$([ "$TARGETARCH" = "arm64" ] && echo "arm64" || echo "amd64") && \
+    curl -L "https://github.com/DarthSim/overmind/releases/download/v${OVERMIND_VERSION}/overmind-v${OVERMIND_VERSION}-linux-${OVERMIND_ARCH}.gz" > overmind.gz \
   && gunzip overmind.gz \
   && mv overmind /usr/local/bin \
-  && chmod +x /usr/local/bin/overmind \
-  && curl -fsSL https://cli.github.com/packages/githubcli-archive-keyring.gpg | dd of=/usr/share/keyrings/githubcli-archive-keyring.gpg \
-  && echo "deb [arch=$(dpkg --print-architecture) signed-by=/usr/share/keyrings/githubcli-archive-keyring.gpg] https://cli.github.com/packages stable main" | tee /etc/apt/sources.list.d/github-cli.list > /dev/null \
-  && apt-get update \
-  && apt-get install -y --no-install-recommends gh \
-  && apt-get clean \
-  && rm -rf /var/lib/apt/lists/* /tmp/* /var/tmp/*
+  && chmod +x /usr/local/bin/overmind
 
+# GitHub CLI
+ARG GH_VERSION=2.88.1
+RUN GH_ARCH=$([ "$TARGETARCH" = "arm64" ] && echo "arm64" || echo "amd64") && \
+    curl -fsSL "https://github.com/cli/cli/releases/download/v${GH_VERSION}/gh_${GH_VERSION}_linux_${GH_ARCH}.tar.gz" \
+    | tar xz --strip-components=2 -C /usr/local/bin "gh_${GH_VERSION}_linux_${GH_ARCH}/bin/gh"
 
-# Do the set up required for chatwoot app
-WORKDIR /workspace
-RUN chown vscode:vscode /workspace
+# --- App setup ---
+WORKDIR /workspace/chatwoot
+RUN chown vscode:vscode /workspace/chatwoot
 
-# set up node js, pnpm and claude code in single layer
-RUN npm install -g pnpm@${PNPM_VERSION} @anthropic-ai/claude-code \
+# set up pnpm
+RUN npm install -g pnpm@${PNPM_VERSION} \
     && npm cache clean --force
 
 # Switch to vscode user
@@ -95,4 +98,4 @@ RUN eval "$(rbenv init -)" \
     && pnpm install --frozen-lockfile
 
 # Copy source code after dependencies are installed
-COPY --chown=vscode:vscode . /workspace
+COPY --chown=vscode:vscode . /workspace/chatwoot

.devcontainer/Dockerfile.devx

@@ -0,0 +1,140 @@
+# DevX tooling layer — sits between Dockerfile.base and Dockerfile
+# Build: docker-compose -f .devcontainer/docker-compose.base.yml build devx
+ARG BASE_IMAGE=ghcr.io/chatwoot-br/chatwoot_codespace:latest
+FROM ${BASE_IMAGE}
+
+USER root
+
+ARG TARGETARCH
+ARG USERNAME=vscode
+
+# DevX system dependencies (not needed by Rails itself)
+RUN apt-get update && apt-get install -y --no-install-recommends \
+    fzf \
+    ripgrep \
+    jq \
+    socat \
+    file \
+    poppler-utils \
+    man-db \
+    bubblewrap \
+    && apt-get clean \
+    && rm -rf /var/lib/apt/lists/*
+
+# Fish shell
+ARG FISH_VERSION=4.6.0
+RUN FISH_ARCH=$([ "$TARGETARCH" = "arm64" ] && echo "aarch64" || echo "x86_64") && \
+    curl -fsSL "https://github.com/fish-shell/fish-shell/releases/download/${FISH_VERSION}/fish-${FISH_VERSION}-linux-${FISH_ARCH}.tar.xz" \
+    | tar xJ -C /usr/local/bin && \
+    echo /usr/local/bin/fish >> /etc/shells
+
+# Neovim (LazyVim requires >= 0.11.2)
+ARG NVIM_VERSION=0.12.0
+RUN NVIM_ARCH=$([ "$TARGETARCH" = "arm64" ] && echo "arm64" || echo "x86_64") && \
+    curl -fsSL "https://github.com/neovim/neovim/releases/download/v${NVIM_VERSION}/nvim-linux-${NVIM_ARCH}.tar.gz" \
+    | tar xz --strip-components=1 -C /usr/local && \
+    ln -s /usr/local/bin/nvim /usr/local/bin/vim
+
+# Configure vscode user: set shell to fish
+RUN usermod -s /usr/local/bin/fish $USERNAME
+
+# lazygit
+ARG LAZYGIT_VERSION=0.60.0
+RUN LAZYGIT_ARCH=$([ "$TARGETARCH" = "arm64" ] && echo "arm64" || echo "x86_64") && \
+    curl -fsSL "https://github.com/jesseduffield/lazygit/releases/download/v${LAZYGIT_VERSION}/lazygit_${LAZYGIT_VERSION}_Linux_${LAZYGIT_ARCH}.tar.gz" \
+    | tar xz -C /usr/local/bin lazygit
+
+# git-delta
+ARG DELTA_VERSION=0.19.1
+RUN DELTA_ARCH=$([ "$TARGETARCH" = "arm64" ] && echo "aarch64" || echo "x86_64") && \
+    curl -fsSL "https://github.com/dandavison/delta/releases/download/${DELTA_VERSION}/delta-${DELTA_VERSION}-${DELTA_ARCH}-unknown-linux-gnu.tar.gz" \
+    | tar xz --strip-components=1 -C /usr/local/bin "delta-${DELTA_VERSION}-${DELTA_ARCH}-unknown-linux-gnu/delta"
+
+# yazi + ya companion (terminal file manager)
+ARG YAZI_VERSION=26.1.22
+RUN YAZI_ARCH=$([ "$TARGETARCH" = "arm64" ] && echo "aarch64" || echo "x86_64") && \
+    curl -fsSL "https://github.com/sxyazi/yazi/releases/download/v${YAZI_VERSION}/yazi-${YAZI_ARCH}-unknown-linux-musl.zip" -o /tmp/yazi.zip && \
+    unzip /tmp/yazi.zip -d /tmp/yazi && \
+    mv /tmp/yazi/yazi-${YAZI_ARCH}-unknown-linux-musl/yazi /usr/local/bin/ && \
+    mv /tmp/yazi/yazi-${YAZI_ARCH}-unknown-linux-musl/ya /usr/local/bin/ && \
+    rm -rf /tmp/yazi.zip /tmp/yazi
+
+# glow (markdown renderer)
+ARG GLOW_VERSION=2.1.1
+RUN GLOW_ARCH=$([ "$TARGETARCH" = "arm64" ] && echo "arm64" || echo "x86_64") && \
+    curl -fsSL "https://github.com/charmbracelet/glow/releases/download/v${GLOW_VERSION}/glow_${GLOW_VERSION}_Linux_${GLOW_ARCH}.tar.gz" \
+    | tar xz --strip-components=1 -C /usr/local/bin "glow_${GLOW_VERSION}_Linux_${GLOW_ARCH}/glow"
+
+# chafa >= 1.16 from source (yazi image preview; Debian ships 1.14)
+ARG CHAFA_VERSION=1.18.1
+RUN apt-get update && apt-get install -y --no-install-recommends \
+    libglib2.0-dev libjpeg-dev libpng-dev libwebp-dev libfreetype6-dev && \
+    curl -fsSL -o /tmp/chafa.tar.xz \
+      "https://github.com/hpjansson/chafa/releases/download/${CHAFA_VERSION}/chafa-${CHAFA_VERSION}.tar.xz" && \
+    cd /tmp && tar xf chafa.tar.xz && cd chafa-${CHAFA_VERSION} && \
+    ./configure --prefix=/usr/local --disable-static --disable-man && \
+    make -j$(nproc) && make install && ldconfig && \
+    cd / && rm -rf /tmp/chafa* && \
+    apt-get purge -y --auto-remove libglib2.0-dev libjpeg-dev libpng-dev libwebp-dev libfreetype6-dev && \
+    apt-get clean && rm -rf /var/lib/apt/lists/*
+
+# Playwright + Chromium (browser automation / E2E tests)
+ENV PLAYWRIGHT_BROWSERS_PATH=/opt/playwright
+RUN npx playwright install --with-deps chromium && \
+    chmod -R a+rwx /opt/playwright && \
+    CHROME_BIN="$(find /opt/playwright -name chrome -type f | head -1)" && \
+    mkdir -p /opt/google/chrome && \
+    ln -s "$CHROME_BIN" /opt/google/chrome/chrome && \
+    apt-get clean && rm -rf /var/lib/apt/lists/* && \
+    npm cache clean --force && \
+    rm -rf /root/.cache/ms-playwright
+
+# pnpm via corepack (overrides base npm-installed pnpm)
+ARG PNPM_VERSION="10.33.0"
+RUN corepack enable && corepack prepare pnpm@${PNPM_VERSION} --activate
+
+# Starship prompt (pinned version)
+ARG STARSHIP_VERSION=1.22.1
+RUN curl -fsSL "https://github.com/starship/starship/releases/download/v${STARSHIP_VERSION}/starship-$([ "$TARGETARCH" = "arm64" ] && echo "aarch64" || echo "x86_64")-unknown-linux-musl.tar.gz" \
+    | tar xz -C /usr/local/bin starship
+
+# Ghostty terminal integration (pinned version)
+ARG GHOSTTY_SHELL_TAG=v1.1.3
+COPY .devcontainer/ghostty/xterm-ghostty.terminfo /tmp/xterm-ghostty.terminfo
+RUN tic -x /tmp/xterm-ghostty.terminfo && rm /tmp/xterm-ghostty.terminfo
+RUN mkdir -p /usr/share/ghostty/shell-integration/fish/vendor_conf.d \
+             /usr/share/ghostty/shell-integration/bash && \
+    curl -fsSL "https://raw.githubusercontent.com/ghostty-org/ghostty/${GHOSTTY_SHELL_TAG}/src/shell-integration/fish/vendor_conf.d/ghostty-shell-integration.fish" \
+         -o /usr/share/ghostty/shell-integration/fish/vendor_conf.d/ghostty-shell-integration.fish && \
+    curl -fsSL "https://raw.githubusercontent.com/ghostty-org/ghostty/${GHOSTTY_SHELL_TAG}/src/shell-integration/bash/ghostty.bash" \
+         -o /usr/share/ghostty/shell-integration/bash/ghostty.bash
+
+# Fish system configs (/etc/fish/conf.d/ is the only path not shadowed by bind mounts)
+RUN mkdir -p /etc/fish/conf.d
+COPY .devcontainer/ghostty/ghostty-shell-integration.fish /etc/fish/conf.d/ghostty-shell-integration.fish
+RUN echo 'starship init fish | source' > /etc/fish/conf.d/starship.fish
+RUN echo 'fish_add_path -gP ~/.claude/bin' > /etc/fish/conf.d/claude-path.fish
+RUN echo 'status is-interactive; and rbenv init - fish | source' > /etc/fish/conf.d/rbenv.fish
+
+# Pre-create user-local directories so bind mounts don't leave root-owned parents
+RUN mkdir -p /home/$USERNAME/.local/share /home/$USERNAME/.local/state \
+    && chown -R $USERNAME:$USERNAME /home/$USERNAME/.local
+
+# Global npm tools
+RUN npm install -g @anthropic-ai/claude-code \
+    && npm cache clean --force
+
+# Switch to vscode user
+USER vscode
+ENV PATH="/home/vscode/.rbenv/bin:/home/vscode/.rbenv/shims:/home/vscode/.claude/bin:/home/vscode/.bun/bin:/home/vscode/.local/bin:$PATH"
+
+# bun (JS runtime/bundler, pinned version)
+ARG BUN_VERSION=1.2.17
+RUN curl -fsSL https://bun.sh/install | bash -s "bun-v${BUN_VERSION}"
+
+# Git config for delta
+RUN git config --global core.pager delta && \
+    git config --global interactive.diffFilter "delta --color-only" && \
+    git config --global delta.navigate true && \
+    git config --global delta.side-by-side true && \
+    git config --global merge.conflictstyle zdiff3