Rox the software running BeWelcome.org 🌏

A community-driven hospitality exchange network

Why this is incredible 😍

• 🛌 Member profiles with focus on finding a place to stay
• 🔎 Search members by map, location, username
• 👬 Comment system to increase trust between each other
• 📝 Forum and groups for discussions
• 🚣🚴 Activities, galleries to show who you are
• 🔧 Volunteer tools (safety, moderation, spam, rights member welcome tools and more)
• 🌈 On page translation for 305 languages
• 🙋💪 BeWelcome is people and volunteers Learn more

Join the team 👧👦👩👨

You like the idea? Development is only one way to contribute! Find out how to get active, including as designer, tester, translator, moderator, helping others and much more! 😍

Get your Rox development enviroment 💻

1. 🎈 Set up you local development enviroment and fork the repository on Github.
2. 🔍 Pick a good starter issue
3. ✨ Create a pull request and @mention the people from the issue to review
4. 🌞 Fix the remaining things during review
5. 🎉 Wait for it being merged!

You probably want to get started by checking out the code in src/.

build/ is deprecated and the code needs to be rewritten in src/.

To make changes in Javascript bear in mind that the Webpack needs to process each change before it reflects on the site. It is a good idea to run bun encore dev --watch which will keep updating files as you keep saving them.

Documentation

Documentation is in the doc tree and can be compiled using mkdocs:

$ mkdocs build

The result can then be accessed via doc/html/ in your cloned repository.

Procedure

If you see an updated composer.json or composer.lock make sure to run

composer install --prefer-dist --no-progress --no-interaction --no-scripts

Also run

bun i --frozen-lockfile

everytime you see a change in either package.json or bun.lock.

If any .scss file or a file in assets/ changed a make build is necessary.

Production image & deployment 🚀

The production image is built in CI, not on the deploy server. The deploy host only runs docker compose pull && docker compose up -d — there is no on-server docker compose ... --build and no composer install on the server.

How the image is built

The build-image workflow builds the production bewelcome_php target from the Dockerfile and pushes a multi-arch (linux/amd64 + linux/arm64) manifest to ghcr.io/bewelcome/rox. Each architecture is built on a native runner (no QEMU) and pushed by digest, then a merge job stitches the digests into one tagged manifest list so docker pull resolves the right arch automatically. The image is self-contained: vendor/ and the compiled front-end assets (public/build/) are baked in at build time, so it boots with no host checkout and no bind-mount of the source tree.

It runs:

• on every push to develop that touches image-affecting paths (Dockerfile, src/**, composer.lock, assets/**, etc.), and
• on every v* tag push.

Tags are produced by docker/metadata-action:

Tag	Meaning
sha-<shortsha>	Immutable per-commit pin — use this to deploy and roll back
develop	Moving pointer to the latest develop build (convenience only)
vX.Y.Z, X.Y, X	SemVer tags, published only for v* tag pushes

Every published image is scanned with Trivy (CRITICAL/HIGH/MEDIUM; unfixed CVEs only). Results appear in the Scan image job log.

After a successful push on develop, the workflow sends a repository_dispatch (event_type: rox-image-pushed) to BeWelcome/sysadmins-infra, which deploys the new sha-<shortsha> image to stage automatically — but only if all three gates pass:

1. the image build and push succeed,
2. the Trivy scan finds no CRITICAL/HIGH/MEDIUM unfixed vulnerabilities, and
3. the parallel CI workflow on the same commit also succeeds (phpunit, linters, security checks, etc.).

If CI fails, the image may still be pushed to GHCR for inspection, but stage deploy is blocked. The dispatch is not sent for v* tags — production releases are triggered manually/gated from sysadmins-infra.

Cut a production release

git tag vX.Y.Z
git push --tags

This publishes the SemVer image tags. Promote it to production from the sysadmins-infra deploy workflow.

Roll back

Redeploy a previous immutable tag from sysadmins-infra by pointing the deploy at an earlier ghcr.io/bewelcome/rox:sha-<shortsha> (the digest is recorded in the dispatch payload, so the rollback target is exact).

Required secrets

The cross-repo dispatch authenticates as the bewelcome-platform-deployer GitHub App (installed on sysadmins-infra). The workflow mints a short-lived installation token at run time from two Actions secrets in this repo:

• DEPLOY_APP_ID — the App's ID
• DEPLOY_APP_PRIVATE_KEY — the App's private key

GHCR push itself uses the built-in GITHUB_TOKEN (permissions: packages: write).

Useful links

• Writing great Git commit messages
• Git crash course

Coding standards

• PSR-1
• PSR-2

To ensure coding standards are followed run make everytime before you commit. Fixing coding standard issues can be achieved with

make phpcsfix

twice in a row.