Merge pull request #4067 from AlchemyCMS/bin-start-refresh-flag

chore(dev): make Docker dev rebuilds easier and uid-safe

Author: tvdeyen

AGENTS.md

@@ -59,6 +59,13 @@ bin/start
 
 This starts a Rails server and pnpm watch task in the dummy application for running a full dev environment.
 
+After changing dependencies (`Gemfile` or `package.json`), rebuild the image and
+refresh the baked `node_modules` in one step:
+
+```bash
+bin/start --refresh
+```
+
 ### Starting the Rails console
 
 ```bash

README.md

@@ -363,6 +363,13 @@ server, Sass watcher, and JS bundle watcher):
 $ bin/start
 ```
 
+After changing dependencies (`Gemfile` or `package.json`), rebuild the image and
+refresh the baked `node_modules` in one step:
+
+```bash
+$ bin/start --refresh
+```
+
 Or, to run the dummy app locally without Docker:
 
 ```bash

bin/setup

@@ -12,6 +12,11 @@ def system!(*args)
 end
 
 FileUtils.chdir GEM_ROOT do
+  # Docker Compose reads .env for the uid/gid baked into the image's container
+  # user, which must match the host to write into the bind mounted workspace on
+  # Linux. Written per machine and gitignored so any compose invocation matches.
+  File.write(".env", "USER_ID=#{Process.uid}\nGROUP_ID=#{Process.gid}\n")
+
   system! "gem install bundler --conservative"
   system("bundle check") || system!("bundle install")
   system("pnpm -v &> /dev/null") || system!("corepack enable")

bin/start

@@ -13,4 +13,17 @@ USER_ID="${USER_ID:-$(id -u)}"
 GROUP_ID="${GROUP_ID:-$(id -g)}"
 export USER_ID GROUP_ID
 
-exec docker compose up --build "$@"
+# node_modules is baked into the image but shadowed by an anonymous volume, so a
+# rebuilt image is not picked up until that volume is recreated. `--refresh`
+# renews it after changing dependencies; a plain start skips the reseed cost.
+renew=""
+args=""
+for arg in "$@"; do
+  if [ "$arg" = "--refresh" ]; then
+    renew="--renew-anon-volumes"
+  else
+    args="$args $arg"
+  fi
+done
+
+exec docker compose up --build $renew $args

docker-compose.yml

@@ -13,8 +13,8 @@ x-app: &app
 # volume. node_modules sits under the bind mount, so an anonymous volume
 # (`- /workspace/node_modules`) shadows the host directory and surfaces the
 # image's copy instead of the host's (which has platform-specific binaries).
-# After changing dependencies, rebuild the image; refresh node_modules with
-# `docker compose up --build --renew-anon-volumes`.
+# After changing dependencies, rebuild the image and refresh node_modules with
+# `bin/start --refresh`.
 #
 # USER_ID/GROUP_ID select the uid/gid of the image's `alchemy` user, which has to
 # own the `.:/workspace` bind mount to be able to write into it. `bin/start` sets