Docker dev modernization

[CoryMCodes]

Summary

Resolve #826

This PR modernizes the Docker development setup so a new contributor can clone the repo and run Flaredown in Docker on modern Mac hardware, including Apple Silicon.

The original Docker startup issue was caused by the frontend live reload port binding to 65535. Docker Desktop could create the frontend container, but stalled before starting it because that host port falls into the system ephemeral port range on macOS/Linux. The fix is to move Ember live reload to 4301 and publish only localhost-bound development ports.

During troubleshooting, I also replaced PhantomJS with headless Chrome for frontend tests. That change turned out not to be required for the Docker startup issue itself, but I am proposing we keep it because PhantomJS has been archived since 2018 and this aligns with the broader priority of modernizing Flaredown. The frontend image was forced to linux/amd64, likely to support PhantomJS. Removing PhantomJS lets the frontend image run natively on Apple Silicon and removes a deprecated browser dependency, so it is not the direct fix for the port hang but is part of making Docker development work naturally on modern Macs.The frontend test suite now runs successfully under Chrome in Docker.

What Changed

• Removed the forced linux/amd64 frontend Docker platform so Docker can run natively on modern Mac chips.
• Replaced PhantomJS frontend test runner with headless Chrome/Chromium.
• Installed Chromium in the frontend Docker image and wired Testem to CHROME_BIN.
• Moved Ember live reload from host port 65535 to 4301.
• Bound development ports to 127.0.0.1 instead of all host interfaces.
• Added named Docker volumes for frontend dependencies so bind-mounted source code does not overwrite container-installed dependencies.
• Added frontend entrypoint logic to refresh dependencies when package.json, package-lock.json, Bower config, npm config, or patches change.
• Made Docker database setup remain interactive and documented that it resets local Docker dev/test DBs.
• Fixed app:setup so schema cache is refreshed after migrations before loading seeds.
• Updated docs to present Docker as one supported development method, not necessarily the default.

Verification

• docker compose config --quiet
• docker compose --profile tools run --rm app-setup
• docker compose --profile dev up -d --build
• Frontend reachable at http://127.0.0.1:4300
• Backend reachable at http://127.0.0.1:3000
• Live reload port 4301 listening
• docker compose --profile dev run --rm frontend npm run test
  • Chrome 120.0
  • 452 tests
  • 452 pass
  • 0 fail

[compwron]

shipit

[compwron]

--allow-root is... concerning. Why?

[compwron]

CI is mad on frontend versions - thoughts?

1s
Run npm install
npm ERR! code ENOTSUP
npm ERR! notsup Unsupported engine for flaredown@0.0.0: wanted: {"bower":"1.x","node":"14.x","npm":"6.x"} (current: {"node":"20.20.2","npm":"6.14.18"})
npm ERR! notsup Not compatible with your version of node/npm: flaredown@0.0.0
npm ERR! notsup Not compatible with your version of node/npm: flaredown@0.0.0
npm ERR! notsup Required: {"bower":"1.x","node":"14.x","npm":"6.x"}
npm ERR! notsup Actual:   {"npm":"6.14.18","node":"20.20.2"}

npm ERR! A complete log of this run can be found in:
npm ERR!     /home/runner/.npm/_logs/2026-07-12T06_51_39_229Z-debug.log
Error: Process completed with exit code 1.

[Copilot]

Pull request overview

This PR modernizes Flaredown’s Docker-based development workflow (especially for modern macOS/Apple Silicon) by fixing problematic port publishing, tightening host bindings, and updating the frontend test runner away from PhantomJS toward headless Chrome/Chromium.

Changes:

• Updated Docker Compose dev port publishing (bind to 127.0.0.1) and moved Ember live reload off 65535 to 4301.
• Switched frontend tests from PhantomJS to headless Chrome/Chromium (Docker + Testem config + CI env wiring).
• Added frontend container dependency-volume + entrypoint logic to keep container-installed dependencies from being clobbered by bind mounts.

Reviewed changes

Copilot reviewed 9 out of 12 changed files in this pull request and generated 4 comments.

Show a summary per file

File	Description
README.md	Updates contributor docs to position Docker as an option and document new Docker dev workflow.
Makefile	Changes make seed to run the Docker app-setup tooling flow.
docker-compose.yml	Binds dev ports to localhost, changes live reload port, adds named volumes, adds app-setup tooling service.
frontend/Dockerfile	Removes forced linux/amd64, installs Chromium, sets up entrypoint-driven dependency install.
frontend/bin/docker-entrypoint	Adds checksum-based dependency refresh so bind mounts don’t break node/bower installs.
frontend/testem.js	Runs tests in Chrome (CI/dev) with explicit Chrome path + args.
frontend/README.md	Removes PhantomJS prerequisite from frontend docs.
frontend/package.json	Removes PhantomJS dependency and adjusts Bower install to allow root in containers.
frontend/package-lock.json	Removes PhantomJS-related dependency tree entries.
backend/lib/tasks/app.rake	Refreshes schema cache/column info after migrations; improves interactive prompt handling.
.github/workflows/frontend.yml	Updates frontend CI to use Chrome and pins npm version.
.gitignore	Ignores docs/superpowers/.

Files not reviewed (1)

• frontend/package-lock.json: Generated file

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[compwron]

Concern: the frontend image is no longer self-contained

frontend/Dockerfile drops the build-time RUN npm install, so dependencies now install at container startup via the new bin/docker-entrypoint, into the named volumes frontend_node_modules / frontend_bower_components. A couple of consequences worth considering:

• The first docker compose up runs a full npm install + Bower install at runtime (slow), and the built image on its own has no node_modules. Anything that expects a runnable image without the mounted volume (e.g. a future CI job, or docker run of the image standalone) will break.
• Clean rebuilds now require docker compose down -v — a plain rebuild reuses the stale dependency volume. The entrypoint's checksum guard (over package*.json, .bowerrc, .npmrc, and patches/) handles the common "deps changed" case well, but not a corrupted/partial volume.

Not necessarily a blocker — it's a reasonable way to keep bind-mounted source from clobbering container-installed deps — but it's a meaningful shift in how the image behaves. Worth a short note in the README (e.g. "run docker compose down -v for a clean dependency rebuild") so contributors aren't surprised.

[CoryMCodes]

Addressed the latest review comments in separate commits:

• 98232589 Add frontend env template

  • Adds frontend/env-example instead of telling contributors to copy backend/env-example into frontend/.env.

  • Clarifies that frontend PORT=3000 refers to the backend API port, while FRONTEND_PORT=4300 is the frontend port.

• 4e861424 Run frontend Docker installs as non-root

  • Removes --allow-root from the Bower postinstall command.

  • Runs frontend Docker dependency installation and runtime as the non-root node user.

  • Removes --unsafe-perm from Docker install paths.

• e115d6f1 Clarify database reset seed command

  • Keeps the existing make seed target name, but updates the Makefile and README wording to state that it resets, migrates, loads fixtures, and seeds the database.

• 2b38fc23 Use bundled npm in node-next frontend tests

  • Removes the npm 6 pin from the Node 16/18/20 node-next-test matrix.

  • Leaves npm 6 pinned only for the primary Node 14 job, which matches the app’s current supported runtime.(should fix CI)

• 88baa6a3 Install Chrome explicitly in frontend CI

  • Adds browser-actions/setup-chrome@v2 to the frontend CI jobs.

  • Passes the installed Chrome binary path to npm run test through CHROME_BIN, instead of relying on whatever Chrome happens to be present on the runner image.