Beacon-Docs/CONTRIBUTING.md

Contributing to Beacon

Thank you for your interest in contributing. This page is the shared workflow for all three Beacon repositories:

• beacon-docs, this repo: deployment, configuration and operator documentation.
• beacon-server: the API and ingest. Its own CONTRIBUTING.md covers Go style, tests, database and API changes.
• beacon-web: the frontend. Its own CONTRIBUTING.md covers TypeScript style, tests and the feature layout.

Please read this before opening a PR anywhere.

Before you start

Talk first for anything bigger than a small fix. On beacon-server and beacon-web, open or comment on an issue before starting work, so maintainers can say if something is already in progress or out of scope. Issues are disabled on beacon-docs; for a docs restructure, a new deployment type or a correction you are unsure about, reach out on the MeshCore Canada Discord. For typos, broken links and small clarifications, just open a PR.

One thing per PR. Each pull request covers one logical change: a bug fix, a new endpoint, a corrected variable table. PRs that touch many unrelated things are hard to review and hard to revert.

No fully AI-generated contributions. We welcome contributors who use AI tools to assist their work, but a PR should reflect the author's own understanding and judgement. PRs that appear to be unreviewed AI output may be closed without further comment.

Branches

Every Beacon repo, docs included:

• main holds stable releases only and is protected. Never target it directly.
• dev is active development. All PRs target dev.

In beacon-docs, main describes the current release and dev describes what is coming next.

Workflow

1. Fork, or create a branch from dev.
2. Make your change.
3. Run that repo's checklist (below for docs; in each code repo's CONTRIBUTING for code).
4. Open a pull request with a clear description of what changed and why, referencing any related issue.

Running the full stack locally

Most changes to either code repo are easier to check against the other one running next to it.

beacon-server, with a throwaway PostgreSQL in Docker:

git clone https://github.com/MeshCore-Beacon/beacon-server.git && cd beacon-server
cp env.example .env
cp config.yaml.example config.yaml
docker run -d --name beacon-postgres -p 5432:5432 \
  -e POSTGRES_USER=beacon -e POSTGRES_PASSWORD=beacon -e POSTGRES_DB=beacon postgres:16-alpine
go run ./cmd/beacon

Set POSTGRES_DSN and your broker credentials in .env (every variable is described in Configuration). Migrations run on startup. The API is on http://localhost:8080 and Swagger at http://localhost:8080/swagger/index.html.

beacon-web, in a second terminal:

git clone https://github.com/MeshCore-Beacon/beacon-web.git && cd beacon-web
npm install
cp .env.example .env.local
npm run dev

In .env.local, uncomment and set:

VITE_DEV_PROXY=http://localhost:8080
VITE_API_BASE=/api/v1
VITE_WS_URL=ws://localhost:5173/ws

Vite then proxies /api and /ws to the server and presents the server's own origin on the WebSocket, so beacon-server's same-origin rule is satisfied without touching its config. If you would rather have the browser talk to localhost:8080 directly, add websocket: {allowed_origins: [http://localhost:5173]} to the server's config.yaml instead. Open http://localhost:5173.

Checklist before opening a docs PR

• Docs match reality. If you change a variable, path, command or image name, check it against the actual files in docker-deployment-*/ and app_config/, and against the code in beacon-server or beacon-web when the behaviour lives there.
• Links resolve. Relative links point at files that exist; anchors match a heading.
• Compose still parses. If you touched a docker-compose.yml:

  docker compose -f docker-deployment-type1/docker-compose.yml config
  

• No secrets. Never commit a real .env, real passwords, channel keys or MQTT credentials. Use placeholders like CHANGE_ME in examples.
• No em dashes. Use a comma, a period or a new sentence.

Documentation style

• Write for an operator deploying Beacon for the first time. Assume Docker knowledge, not knowledge of this project.
• Lead with the action. "Set DOMAIN to your public hostname", not "the DOMAIN variable should be configured".
• Say why only where the why prevents a mistake.
• Prefer concrete, copy-pasteable commands over prose, in fenced blocks with a language tag.
• One page, one job. Headings are things a reader searches for, not categories.
• Keep tables in step with the example config files; when a key changes, update app_config/config.yaml.example and the page that describes it in the same PR.
• Relative links between files in this repo, so they work on GitHub and in local clones.

Adding or changing a deployment

The deployment folders are meant to be copied to a server and run as-is. When editing one:

• Keep the folder self-contained: docker-compose.yml, the data/ tree, and a .env the user creates from app_config/.env.example.
• Every variable a user must set appears in app_config/.env.example (for .env) or app_config/config.yaml.example (for app config), and in Configuration.
• Keep service names and Caddyfile upstreams consistent; the proxy must resolve the names it proxies to.
• A new deployment type gets its own docker-deployment-typeN/ folder with a README, Caddyfile templates under app_config/caddy/, and a line in the main README.

Commit messages

Conventional commits, imperative, one line under 72 characters, with an optional scope:

docs(readme): clarify VITE_MAP_CENTER fallback behaviour
docs(deploy): add type 2 split server and web compose files
feat(routes): add observation_count to known routes response
fix(ingest): correct lat/lon divisor for advert payloads
chore: update logos

Releases

Versioning, image tags and the release flow are in Releases and versioning.

Repo structure

docker-deployment-type1/   all-in-one Docker Compose deployment
docker-deployment-type2/   split server and web deployment
app_config/                example .env and config.yaml, proxy configs (Caddy, nginx, Apache), fail2ban
docs/                      operator and design documentation
logos/                     brand assets

Recognition

If you would like to be listed as a contributor, add yourself to CONTRIBUTORS.md in your PR.