# 17-May-2026 — Generate a contributor environment for your group [ref #272](https://github.com/nbarrett/ngx-ramblers/issues/272) ## [build 647](https://github.com/nbarrett/ngx-ramblers/actions/runs/26005601269) — [commit 1ec7640](https://github.com/nbarrett/ngx-ramblers/commit/1ec7640dba6c22bdc8321fc5100430571b86c18f) _____ A site admin can now hand a developer everything they need to run the full NGX-Ramblers stack on their own machine, working against this group and no other. You generate a downloadable bundle from the admin area, send it to the contributor, and they are running locally with a single command. The bundle is deliberately narrow. It points at this site's MongoDB server and carries a freshly generated `AUTH_SECRET`. It includes nothing else: no staging configuration database, no shared platform keys, and no other group's data. ![](https://ngx-ramblers.org.uk/api/aws/s3/site-content/6674f34a-1caf-4448-a324-f5ae30c09f80.jpeg) ## What a contributor environment is NGX-Ramblers normally runs from a central configuration database that holds the settings for every group. A developer helping with one group should never need that database, and should never hold credentials that reach beyond the single group they are working on. A contributor environment solves this. The bundle you generate contains three things, all scoped to your group alone: - **A secrets file** with the database connection, the S3 image bucket, and a fresh `AUTH_SECRET` generated just for this bundle. - **An environments manifest** that names the environment so the contributor can start it by name. - **A README** explaining how to unpack and run it. What the bundle leaves out matters just as much: no staging configuration database, no Fly.io or Cloudflare account keys, and no other group's secrets, bucket or data. If a value would let the holder touch a second group or the live platform, it is not included. ## Generating a bundle Open the admin menu and choose **Contributor Environment**, or go straight to `/admin/contributor-environment`. You will see the form shown above. ### Name the environment The **Environment name** is how the contributor starts the stack locally, with `ngx-cli local dev `. Enter it in kebab-case: lower case, with words joined by hyphens. The field tidies whatever you type into that shape when you click away, so `Pang Valley` becomes `pang-valley`. ## Choosing the database The bundle always uses this site's MongoDB server. You decide which data the contributor works against: - **Develop against the current database** - the contributor reads and writes the group's existing database directly. Choose this when you want them working with live content and you are comfortable with their changes being real. - **Clone the current database into a new schema** - a new schema is created on the same server and populated with a copy of the current data. Choose this when you want the contributor to experiment freely without affecting anything in use. Choosing the clone option reveals a **Schema** field, pre-filled with a suggested name. This is the new schema that will be created alongside the original. ![](https://ngx-ramblers.org.uk/api/aws/s3/site-content/bdfb4b9a-7669-43a7-9d23-e9ca856b6aee.jpeg) ## Generating and downloading Click **Generate developer environment**. The bundle is built and downloaded to your machine as a zip file named `contributor-environment-.zip`. A green confirmation appears once it is ready, repeating the command the contributor needs to run. Send them that zip file - that is the whole handover. ![](https://ngx-ramblers.org.uk/api/aws/s3/site-content/65e0281d-6a31-4ba9-bb73-1cc2824b9693.jpeg) ## Getting the code The bundle is unpacked into a checkout of NGX-Ramblers on the contributor's machine, so the contributor needs that checkout first. How they get it depends on whether they only want to run the code or also want to send changes back, and the second case is the one to set up for from the start. The way to contribute to NGX-Ramblers is to fork the repository and submit changes as a pull request from that fork. A contributor has no write access to the project repository, and nobody outside the maintainers does, so they cannot clone it and push to it directly. They work on their own fork instead. 1. On GitHub, open [github.com/nbarrett/ngx-ramblers](https://github.com/nbarrett/ngx-ramblers) and click **Fork**. This creates the contributor's own copy at `github.com//ngx-ramblers`, which they have full write access to. 2. Clone that fork - not the project repository: ``` git clone https://github.com//ngx-ramblers.git cd ngx-ramblers ``` 3. Add the project repository as a second remote, so the fork can be brought up to date as the project moves on: ``` git remote add upstream https://github.com/nbarrett/ngx-ramblers.git ``` There are now two remotes: `origin` is the contributor's fork, where they push, and `upstream` is the project repository, where they fetch updates from. To bring the fork up to date later: `git fetch upstream`, then rebase the work onto `upstream/main`. This clone is the checkout referred to below. The `non-vcs` folder from the bundle is unpacked into its root. ## Running the environment locally The zip already carries the folder structure the files need: ``` non-vcs/secrets/secrets..env non-vcs/secrets/environments.local.json README-contributor-environment.txt ``` Unpack it so the `non-vcs` folder from the zip sits at the **root of the NGX-Ramblers checkout**. Done correctly, the two secrets files end up exactly here: ``` /non-vcs/secrets/secrets..env /non-vcs/secrets/environments.local.json ``` Watch out for one trap. Double-clicking the zip extracts it into a folder named after the zip, with the `non-vcs` folder inside that. Do not copy that whole folder into the project. If the files end up one level too deep, at `/contributor-environment-/non-vcs/secrets/...` rather than `/non-vcs/secrets/...`, the stack will not find them and will not start. Lift the `non-vcs` folder out of the extracted folder and place it at the checkout root, keeping its contents in place. Then start the stack with: ``` ./bin/ngx-cli local dev --no-docker-worker ``` `--no-docker-worker` skips the background scraping worker, which most contributors do not need. The environment resolves entirely from the bundle, with no staging access, so it runs even when the central configuration database is unreachable. ### Seeing your changes With the stack running, the contributor does not need to do anything to pick up the edits they make. Both halves reload themselves: editing an Angular component, template or service recompiles the frontend and the browser refreshes through hot module replacement, and editing a server file restarts the Node backend. Save the file and the result is there in a second or two, with no stopping, rebuilding or restarting the stack by hand. ## Contributing changes back Once a change is working locally, the route to getting it into the project is the same fork and a pull request: 1. Make the change on a branch and commit it. Run `npm run setup:hooks` once beforehand - the git hooks enforce the commit-message format and lint rules on the contributor's own machine. 2. Push the branch to the fork: `git push origin `. 3. On GitHub, open a pull request from the fork against `nbarrett/ngx-ramblers`. A maintainer reviews it and integrates it onto `main`. For anything beyond a small fix, raise a GitHub issue first so the approach can be agreed before the work starts. NGX-Ramblers is developed trunk-based - the maintainers commit straight to `main`, with no internal pull requests - so an external contributor's pull request is the one reviewed way in, and that is deliberate.