feat: Add DevContainer configuration for local development

[Ramjivan]

This PR introduces a devcontainer setup for BeWelcome Rox to standardise and simplify the developer onboarding experience, solving Issue #69.

🎯 What this does:

1. Zero manual setup: A contributor can clone the repo, click "Reopen in Container" in VS Code (or use GitHub Codespaces), and the environment will build, install dependencies, seed the DB, and compile assets automatically.
2. Reuses existing infrastructure: It points directly to the existing docker-compose.yml and docker-compose.override.yml.dist. No new Docker networks or redundant configurations are introduced.
3. Ports & Defaults: Standard ports (8080, 8043, 1080) are auto-forwarded and labelled for a cleaner experience.
4. Fixes minor typo: Corrected docker/db/word.sql to docker/db/words.sql in docker-entrypoint.sh.

💡 Discussion Points for the Team:

I would love to get your thoughts on a couple of implementation details so we can ensure this is the right approach for everyone:

• Xdebug Installation: I have added xdebug to the bewelcome_php_dev stage in the Dockerfile directly. This ensures the Docker layer caches the compilation and it is immediately available (set to off by default for performance). Question: Are we comfortable adding this to the Dockerfile, or would you prefer it to be installed dynamically (e.g. via a postCreateCommand script) to keep the Dockerfile completely untouched?
• GitHub Codespaces: This devcontainer.json configuration also natively supports GitHub Codespaces! Since the repo is public, contributors can use it for free. Perhaps we should document this as an alternative in INSTALL.md in the future?
• Target Branch: This is targeting develop. Does this align with our usual branching strategy for infrastructure enhancements?

Closes #69

[Ramjivan]

🧪 How to Test This PR

If you want to help test this DevContainer setup, here is how you can do it quickly:

Prerequisites:

• Docker installed and running
• VS Code with the "Dev Containers" extension installed (ms-vscode-remote.remote-containers)

Steps to test:

1. Fetch and checkout this branch:

   git fetch origin pull/484/head:test-devcontainer
   git checkout test-devcontainer

2. Open the project in VS Code:

   code .

3. A notification will appear in the bottom right: "Folder contains a Dev Container configuration file. Reopen folder to develop in a container." Click Reopen in Container.
   (Alternatively, press F1 and type Dev Containers: Reopen in Container)
4. Wait for the image to build and the postCreateCommand to finish running (it will download dependencies and seed the database).
5. Once the terminal becomes available, the app should be running!
   • App: http://localhost:8080
   • MailCatcher: http://localhost:1080

What to look out for:

• Check if Xdebug activates properly if you trigger it via VS Code.
• Let us know if the database seeded correctly for you without manual intervention.

[Neophytis]

Good work on this — devcontainer support has been wanted for a while (closes #69) and the overall setup is clean. Two things before merging:

1. Target branch / base stack

This PR targets develop which uses FrankenPHP. Our actual beta and production Docker deployment runs on feature/docker-master (php-fpm + nginx). A devcontainer built against develop means contributors work against a runtime that doesn't match what gets deployed — which is the main thing a devcontainer should prevent.

I'd suggest rebasing against feature/docker-master and pointing dockerComposeFile at that branch's docker-compose.yml. The Codespaces support carries over unchanged and contributors get an environment that actually mirrors production.

2. Xdebug in the Dockerfile

Baking xdebug into the Dockerfile (disabled by default via xdebug.mode=off) is the right approach. It avoids recompiling the extension on every fresh container and keeps it opt-in with XDEBUG_MODE=debug. The postCreateCommand alternative would hit a compile penalty on every rebuild. Current approach is correct.

[Ramjivan]

Thanks Peter! Makes total sense. I've updated this PR:

1. Changed the base branch to feature/docker-master
2. Configured devcontainer.json to target the php container and route port 80 for Nginx
3. Kept Xdebug in the bewelcome_php_dev stage inside the Dockerfile.

This is now ready for review against the production-mirroring stack!

[Ramjivan]

I also just added a small hostRequirements block to explicitly configure GitHub Codespaces machine sizes (2 CPUs, 4GB RAM) as Peter requested!

[thisismeonmounteverest]

@Ramjivan Seems the checks fail as they now use yarn again but develop moved to bun.

Regarding FrankenPHP or nginx/PHP-FPM: FrankenPHP is likely faster and therefore the better choice in the future. Any way to set this up that it can be tested in parallel?

Mailcatcher (even sj26/mailcatcher) doesn't get updates anymore (last push 2 years ago). MailPit had the last update 8 days ago and has an API which could be used for testing.

[Ramjivan]

@thisismeonmounteverest @Neophytis

Yeah, the CI failures are just coming from the base docker-master branch failing on its own.

To let us test both setups, I opened #486 pointing at develop for the FrankenPHP side. We can keep this PR pointing at docker-master for Nginx.

Totally agree on swapping to MailPit. Want me to add that change into these PRs, or keep it in a separate PR?

[thisismeonmounteverest]

@Ramjivan I think we can switch to mailpit here. As it is not used for anything else than development.