Improve Docker/Compose build defaults and reproducibility

- Add x-default-args with sane defaults in compose.yaml
- Fix Poetry dev options and add npm global packages config in .env.dist
- Pin Poetry version during install and harden Arch mirrorlist setup
- Avoid partial upgrades in vim-ide stage and make pacman cache cleanup non-interactive
- Document NPM_GLOBAL_PACKAGES in README

Author: jamm1985

.dockerignore

@@ -0,0 +1,18 @@
+.git
+.gitignore
+
+__pycache__/
+*.pyc
+.mypy_cache/
+.pytest_cache/
+.ruff_cache/
+
+.venv/
+dist/
+build/
+.tox/
+
+.env
+.DS_Store
+.idea/
+.vscode/

.env.dist

@@ -9,14 +9,15 @@ DOCKER_USER_HOME=/home/developer
 
 MIRROR_LIST_COUNTRY=RU
 BUILD_PACKAGES="pyenv git gnupg sudo postgresql-libs mariadb-libs openmp"
-VIM_PACKAGES="python vim ctags ripgrep bat npm nodejs-lts-jod openai-codex gemini-cli"
+VIM_PACKAGES="python vim ctags ripgrep bat npm nodejs-lts-jod"
+NPM_GLOBAL_PACKAGES="@openai/codex @google/gemini-cli"
 
 PYTHON_VERSION=3.14
 PYTHONUNBUFFERED=1
 PIP_DEFAULT_TIMEOUT=100
 POETRY_VERSION=2.2.1
 POETRY_OPTIONS_APP="--only main --compile"
-POETRY_OPTIONS_DEV="--no-root --with dev --compile"
+POETRY_OPTIONS_DEV="--no-root --with-dev --compile"
 POETRY_NO_INTERACTION=1
 
 JUPYTER_TOKEN=_change_me_please_!1_

Dockerfile

@@ -19,14 +19,16 @@ RUN set -eux; \
 	useradd --no-log-init -g $DOCKER_USER --uid=$DOCKER_HOST_UID \
   -d $DOCKER_USER_HOME -ms /bin/bash $DOCKER_USER
 RUN mkdir /application && chown $DOCKER_USER:$DOCKER_USER /application
-RUN curl -s \
-  "https://archlinux.org/mirrorlist/?country=$MIRROR_LIST_COUNTRY&protocol=http&protocol=https&ip_version=4" \
-  | sed -e 's/^#Server/Server/' -e '/^#/d' > /etc/pacman.d/mirrorlist
-RUN pacman -Syu --noconfirm && pacman -S --noconfirm $BUILD_PACKAGES
+RUN set -eux; \
+  curl -fsSL "https://archlinux.org/mirrorlist/?country=${MIRROR_LIST_COUNTRY}&protocol=http&protocol=https&ip_version=4" \
+  | sed -e 's/^\s*#Server/Server/' -e '/^\s*#/d' \
+  > /etc/pacman.d/mirrorlist; \
+  grep -q '^Server' /etc/pacman.d/mirrorlist
+RUN pacman -Syu --noconfirm && pacman -S --noconfirm --needed $BUILD_PACKAGES
 RUN echo "${DOCKER_USER} ALL=(ALL) NOPASSWD: ALL" >> /etc/sudoers
 ENV PYENV_ROOT=$DOCKER_USER_HOME/.pyenv
 ENV PATH=$PYENV_ROOT/shims:$PYENV_ROOT/bin:$PATH
-RUN pyenv install $PYTHON_VERSION
+RUN pyenv install --skip-existing $PYTHON_VERSION
 RUN pyenv global $PYTHON_VERSION
 RUN pyenv rehash
 ENV PYTHONUNBUFFERED=1
@@ -39,7 +41,7 @@ ENV VIRTUAL_ENV=/opt/venv
 RUN python -m venv --copies $VIRTUAL_ENV
 ENV PATH=$VIRTUAL_ENV/bin:$PATH
 RUN pip install --upgrade pip
-RUN curl -sSL https://install.python-poetry.org | python -
+RUN curl -sSL https://install.python-poetry.org | POETRY_VERSION=$POETRY_VERSION python -
 ENV PATH=$POETRY_HOME/bin:$PATH
 ENV PYTHONPATH=/application/src
 ENV PROJECT_ROOT=/application
@@ -62,14 +64,17 @@ ARG POETRY_OPTIONS_APP="--only main --compile"
 RUN poetry install $POETRY_OPTIONS_APP -n -v -C /build && \
   rm -rf $POETRY_CACHE_DIR/* && rm -rf $PIP_CACHE_DIR/*
 RUN sed -i "/\b\($DOCKER_USER\)\b/d" /etc/sudoers
-RUN pacman -Scc <<< Y <<< Y
+RUN pacman -Scc --noconfirm
 USER $DOCKER_USER
 WORKDIR /application
 
 FROM python-base AS build-deps-dev
+ARG DOCKER_USER=devuser
 ARG POETRY_OPTIONS_DEV="--no-root --with-dev --compile"
 COPY pyproject.toml poetry.lock /build/
 RUN poetry install $POETRY_OPTIONS_DEV -n -v -C /build 
+RUN mkdir -p $POETRY_CACHE_DIR $PIP_CACHE_DIR && \
+  chown -R $DOCKER_USER $POETRY_CACHE_DIR $PIP_CACHE_DIR
 
 FROM build-deps-dev AS dev-build
 ARG DOCKER_USER=devuser
@@ -80,7 +85,9 @@ FROM build-deps-dev AS vim-ide
 ARG DOCKER_USER=devuser
 ARG DOCKER_USER_HOME=/home/devuser
 ARG VIM_PACKAGES="python vim ctags ripgrep bat npm nodejs-lts-jod"
-RUN pacman -Sy && pacman -S --noconfirm $VIM_PACKAGES
+ARG NPM_GLOBAL_PACKAGES=""
+RUN pacman -S --noconfirm --needed $VIM_PACKAGES
+RUN if [ -n "$NPM_GLOBAL_PACKAGES" ]; then npm install -g --no-fund --no-audit $NPM_GLOBAL_PACKAGES; fi
 USER $DOCKER_USER
 RUN curl -fLo $DOCKER_USER_HOME/.vim/autoload/plug.vim --create-dirs \
   https://raw.githubusercontent.com/junegunn/vim-plug/master/plug.vim

README.md

@@ -64,7 +64,7 @@ Use it as-is or tailor it to match your team's development workflow.
 
 ```bash
 cp .env.dist .env
-vim .env  # Set OS packages, Python version, Poetry version, etc., and your API keys for OPENAI_API_KEY and GEMINI_API_KEY.
+vim .env  # Set OS packages, a released PYTHON_VERSION, Poetry version, etc., and your API keys for OPENAI_API_KEY and GEMINI_API_KEY.
 ```
 
 2. Set up Python project dependencies
@@ -114,6 +114,7 @@ docker compose run --rm app
 ```
 
 - Optional: Run Codex or Gemini (see more examples below)
+  - Note: `codex` and `gemini` CLIs are installed during the image build via `NPM_GLOBAL_PACKAGES` in `.env`.
 
 ```bash
 docker compose build codex

compose.yaml

@@ -3,24 +3,27 @@ x-default-env: &default-env
   PIP_DEFAULT_TIMEOUT: "100"
   PYTHONUNBUFFERED: "1"
 
+x-default-args: &default-args
+  TZ: ${TZ:-Asia/Vladivostok}
+  DOCKER_HOST_UID: ${DOCKER_HOST_UID:-1000}
+  DOCKER_HOST_GID: ${DOCKER_HOST_GID:-1000}
+  DOCKER_USER: ${DOCKER_USER:-developer}
+  DOCKER_USER_HOME: ${DOCKER_USER_HOME:-/home/developer}
+  MIRROR_LIST_COUNTRY: ${MIRROR_LIST_COUNTRY:-RU}
+  BUILD_PACKAGES: ${BUILD_PACKAGES:-pyenv git gnupg sudo postgresql-libs mariadb-libs openmp}
+  VIM_PACKAGES: ${VIM_PACKAGES:-python vim ctags ripgrep bat npm nodejs-lts-jod}
+  PYTHON_VERSION: ${PYTHON_VERSION:-3.14}
+  POETRY_VERSION: ${POETRY_VERSION:-2.2.1}
+  POETRY_OPTIONS_APP: ${POETRY_OPTIONS_APP:---only main --compile}
+  POETRY_OPTIONS_DEV: ${POETRY_OPTIONS_DEV:---no-root --with-dev --compile}
+  NPM_GLOBAL_PACKAGES: ${NPM_GLOBAL_PACKAGES:-}
+
 services:
   python-base:
     platform: linux/amd64
     build:
       target: python-base
-      args: &default-args
-        - TZ=${TZ}
-        - DOCKER_HOST_UID=${DOCKER_HOST_UID}
-        - DOCKER_HOST_GID=${DOCKER_HOST_GID}
-        - DOCKER_USER=${DOCKER_USER}
-        - DOCKER_USER_HOME=${DOCKER_USER_HOME}
-        - MIRROR_LIST_COUNTRY=${MIRROR_LIST_COUNTRY}
-        - BUILD_PACKAGES=${BUILD_PACKAGES}
-        - VIM_PACKAGES=${VIM_PACKAGES}
-        - PYTHON_VERSION=${PYTHON_VERSION}
-        - POETRY_VERSION=${POETRY_VERSION}
-        - POETRY_OPTIONS_APP=${POETRY_OPTIONS_APP}
-        - POETRY_OPTIONS_DEV=${POETRY_OPTIONS_DEV}
+      args: *default-args
     environment:
       <<: *default-env
   poetry: