Docker Desktop local setup can stall containers during dependency install (bind-mounted vendor / node_modules)

[pathwaynavigator]

Description

When setting up Forus locally using Docker Desktop, dependency installation for both backend (Composer) and frontend (npm) can cause containers to stall and Docker Desktop to become unresponsive.

In some cases, containers cannot be restarted and Docker Desktop must be restarted entirely to recover. This makes local setup unreliable, especially for new developers or clean environments.

---

Environment

• Docker Desktop: on Ubuntu 25.10 (likely affects Windows and macOS as well)
• Main repository: teamforus/Forus - release v163 (commit 3f61218, 4 days ago)
• Backend: teamforus/forus-backend - release v163 (commit d2dae97, 4 days ago)
• Frontend: teamforus/forus-frontend-react - release v163 (commit 7fad5d6, 4 days ago)
• Setup: Following readme-docker.md in each repository

---

Steps to reproduce

Backend

1. Clone teamforus/forus-backend
2. Follow readme-docker.md
3. Use Docker Compose with the project directory bind-mounted (current default)
4. Run composer install inside the container

Frontend

1. Clone teamforus/forus-frontend-react
2. Follow readme-docker.md
3. Remove node_modules
4. Run npm install inside the container

---

Observed behavior

• Dependency installation stalls while creating thousands of files
• Docker Containers become unresponsive and can be reset or removed by using commands.
  • docker compose down / docker compose up does not recover the environment
• Docker Desktop restart is required

---

Expected behavior

• Dependency installation completes reliably
• Containers remain responsive
• Local setup completes without requiring Docker Desktop restart

---

Analysis

Composer and npm create large dependency trees with thousands of small files. On Docker Desktop, writing these files through bind mounts can overwhelm the filesystem sync and event pipeline, leading to stalls or deadlocks. This appears to be a Docker Desktop limitation when using bind-mounted dependency directories.

---

Proposed direction (requesting feedback)

Docker recommends using named volumes for data generated and managed by containers,
rather than bind mounts, especially for performance and reliability reasons.
See: https://docs.docker.com/engine/storage/volumes/

It seems a possible mitigation is to store dependency directories in Docker named volumes instead of bind mounts:

• Backend: mount vendor/ as a named volume
• Frontend: mount node_modules/ as a named volume

This keeps source code bind-mounted while avoiding filesystem sync issues for dependencies.

Before making changes to both repositories, feedback is requested on:

• Is this a suitable solution?
• Whether this approach should be adopted as the default Docker Desktop setup
• Whether alternative approaches are preferred

[pathwaynavigator]

PR's with proposed solutions:

• Add vendor_data volume to docker-compose forus-backend#2737
• Add node_modules volume to docker-compose forus-frontend-react#896