From ac00eb9674de774ac45656b53b5d623deda55587 Mon Sep 17 00:00:00 2001 From: tiennm99 Date: Fri, 18 Sep 2026 10:47:56 +0700 Subject: [PATCH] style: order environment variables by how much the service needs them environment: blocks were in no particular order. They now run must-have -> should-have -> optional, with related variables kept adjacent as a group that takes the tier of its most important member: PUID/PGID, PASSWORD with SUDO_PASSWORD, DOCKER_MODS ahead of the INSTALL_PACKAGES and NODEJS_MOD_VERSION that configure it, the four GIT_* entries, the PASEO_* daemon settings. Each .env.example is reordered to match its compose file. The names do not map one to one -- PASSWORD feeds both PASSWORD and SUDO_PASSWORD, SERVICE_HOSTNAME feeds HOST -- so an entry sits where the first compose entry reading it sits. The HOST comment in both compose files is dropped; the READMEs already carry that explanation in full. CLAUDE.md records the ordering convention. alloy and gitea-mirror-local are untouched: every variable there is required, so the tiers collapse and the existing grouping is the better one. --- CLAUDE.md | 30 ++++++++++++++++++++++++++++++ code-server-base/compose.yml | 4 ++-- code-server/.env.example | 8 ++++---- code-server/compose.yml | 13 ++++++------- paseo/.env.example | 16 ++++++++-------- paseo/compose.yml | 7 +++---- 6 files changed, 53 insertions(+), 25 deletions(-) diff --git a/CLAUDE.md b/CLAUDE.md index 4c07ffe..6ed73a3 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -41,6 +41,36 @@ links out to each service. Per-service detail (variables, ports, storage) belongs in that service's README, not the root one. Adding a service means adding its README and a row to the root table. +## Environment variable order + +`environment:` entries are ordered by how badly the service needs them — not +alphabetically, and not by when they were added: + +1. **Must have** — without it the service does not do its job, or is exposed. + Auth secrets, the uid/gid its files belong to, host allow-lists, proxy + trust, and the mod list that supplies the toolchain. +2. **Should have** — it starts without these, but behaves wrongly for this + setup: timezone, default workspace, shell, git identity, pinned tool + versions, extra packages. +3. **Optional** — cosmetics and conveniences; dropping one changes nothing + functional. Window titles, prompt labels. + +Grouping wins over the tiers. Variables that belong together stay on adjacent +lines — `PUID`/`PGID`, `PASSWORD`/`SUDO_PASSWORD`, the four `GIT_*` entries, +the `PASEO_*` daemon settings, `DOCKER_MODS` with the `INSTALL_PACKAGES` and +`NODEJS_MOD_VERSION` that configure it — and the whole group sits at the tier +of its most important member, even when a member on its own would rank lower. +Within a group, the variable others configure comes first. + +Do not write the tier into the file as a comment — the order is the +documentation. Where every variable is required, as in `alloy`, the tiers +collapse and the existing grouping stands. + +`.env.example` follows its compose file's order. The names differ — one +`PASSWORD` can feed several container variables, and `SERVICE_HOSTNAME` feeds +`HOST` — so each entry sits where the first compose entry that reads it sits. +Reordering a compose file means reordering the `.env.example` with it. + ## Deployment target Services are deployed through Coolify and Dokploy, not plain `docker compose` diff --git a/code-server-base/compose.yml b/code-server-base/compose.yml index 0b738a7..45f121c 100644 --- a/code-server-base/compose.yml +++ b/code-server-base/compose.yml @@ -4,11 +4,11 @@ services: environment: - PUID=1000 - PGID=1000 + - PASSWORD=${PASSWORD} + - SUDO_PASSWORD=${PASSWORD} - TZ=Asia/Ho_Chi_Minh - DEFAULT_WORKSPACE=/config/workspace - PWA_APPNAME=code-server - - PASSWORD=${PASSWORD} - - SUDO_PASSWORD=${PASSWORD} volumes: - 'code-server-config:/config' volumes: diff --git a/code-server/.env.example b/code-server/.env.example index 8875be7..1a7f70e 100644 --- a/code-server/.env.example +++ b/code-server/.env.example @@ -2,10 +2,6 @@ # # cp .env.example .env -# Container hostname, also passed in as HOST -- the name zsh's prompt shows. -# Not named HOSTNAME: the deploying shell's own HOSTNAME would override it. -SERVICE_HOSTNAME=code-server - # Web UI login password. MUST NOT be blank -- the LinuxServer image serves # code-server without authentication when PASSWORD is empty. # Also used for SUDO_PASSWORD inside the container. @@ -15,3 +11,7 @@ PASSWORD= # Git identity baked into the container (author + committer). GIT_NAME= GIT_EMAIL= + +# Container hostname, also passed in as HOST -- the name zsh's prompt shows. +# Not named HOSTNAME: the deploying shell's own HOSTNAME would override it. +SERVICE_HOSTNAME=code-server diff --git a/code-server/compose.yml b/code-server/compose.yml index 307d99b..290cfcf 100644 --- a/code-server/compose.yml +++ b/code-server/compose.yml @@ -5,20 +5,19 @@ services: environment: - PUID=1000 - PGID=1000 - - TZ=Asia/Ho_Chi_Minh - # Hostname zsh's prompt reads, overriding the one Coolify injects. - - HOST=${SERVICE_HOSTNAME} - - DEFAULT_WORKSPACE=/config/workspace - - PWA_APPNAME=code-server + - PASSWORD=${PASSWORD} + - SUDO_PASSWORD=${PASSWORD} - 'DOCKER_MODS=linuxserver/mods:universal-package-install|linuxserver/mods:universal-docker|linuxserver/mods:code-server-golang|linuxserver/mods:code-server-nodejs|linuxserver/mods:code-server-npmglobal|linuxserver/mods:code-server-python3|linuxserver/mods:code-server-zsh' - INSTALL_PACKAGES=gh|git|glab|unzip|zip - NODEJS_MOD_VERSION=24 - - PASSWORD=${PASSWORD} - - SUDO_PASSWORD=${PASSWORD} + - TZ=Asia/Ho_Chi_Minh + - DEFAULT_WORKSPACE=/config/workspace - GIT_AUTHOR_NAME=${GIT_NAME} - GIT_AUTHOR_EMAIL=${GIT_EMAIL} - GIT_COMMITTER_NAME=${GIT_NAME} - GIT_COMMITTER_EMAIL=${GIT_EMAIL} + - HOST=${SERVICE_HOSTNAME} + - PWA_APPNAME=code-server volumes: - 'code-server-config:/config' - '/var/run/docker.sock:/var/run/docker.sock' diff --git a/paseo/.env.example b/paseo/.env.example index 1f9737b..20af898 100644 --- a/paseo/.env.example +++ b/paseo/.env.example @@ -17,11 +17,9 @@ PASEO_HOSTNAMES= # `uniquelocal` covers the private ranges Docker bridge networks use. PASEO_TRUSTED_PROXIES=uniquelocal -# Container hostname, shown as the host label in the web UI. Without it the -# label is a random container ID. Also passed in as HOST -- the name zsh's -# prompt shows. Not named HOSTNAME: the deploying shell's own HOSTNAME would -# override it. -SERVICE_HOSTNAME=paseo +# Shell for Paseo's terminals. Paseo reads $SHELL and otherwise falls back to +# /bin/sh (dash); it ignores the user's login shell, so `chsh` has no effect. +SHELL=/bin/zsh # Agent CLIs to install on start, if not already present. Space- or # comma-separated, from: claude codex opencode copilot omp pi. Leave empty to @@ -37,6 +35,8 @@ TZ=Asia/Ho_Chi_Minh GIT_NAME= GIT_EMAIL= -# Shell for Paseo's terminals. Paseo reads $SHELL and otherwise falls back to -# /bin/sh (dash); it ignores the user's login shell, so `chsh` has no effect. -SHELL=/bin/zsh +# Container hostname, shown as the host label in the web UI. Without it the +# label is a random container ID. Also passed in as HOST -- the name zsh's +# prompt shows. Not named HOSTNAME: the deploying shell's own HOSTNAME would +# override it. +SERVICE_HOSTNAME=paseo diff --git a/paseo/compose.yml b/paseo/compose.yml index 21b0c45..99b0c0b 100644 --- a/paseo/compose.yml +++ b/paseo/compose.yml @@ -3,18 +3,17 @@ services: build: . hostname: ${SERVICE_HOSTNAME} environment: - - TZ=${TZ} - # Hostname zsh's prompt reads, overriding the one Coolify injects. - - HOST=${SERVICE_HOSTNAME} - - SHELL=${SHELL} - PASEO_PASSWORD=${PASEO_PASSWORD} - PASEO_HOSTNAMES=${PASEO_HOSTNAMES} - PASEO_TRUSTED_PROXIES=${PASEO_TRUSTED_PROXIES} + - SHELL=${SHELL} - AGENT_CLIS=${AGENT_CLIS} + - TZ=${TZ} - GIT_AUTHOR_NAME=${GIT_NAME} - GIT_AUTHOR_EMAIL=${GIT_EMAIL} - GIT_COMMITTER_NAME=${GIT_NAME} - GIT_COMMITTER_EMAIL=${GIT_EMAIL} + - HOST=${SERVICE_HOSTNAME} volumes: - 'paseo-home:/home/paseo' - 'paseo-workspace:/workspace'