docs: document Google Wallet infrastructure setup

[hugo2006alm]

Summary

• Documents Google Wallet issuer, Google Cloud service account, Generic Class/Object, and publishing setup for [Infra] Set up Google Wallet Generic Pass issuer and publishing access #340.
• Explains the runtime environment contract used by feat: add attendee pass to Google Wallet #364, including base64 encoding, Coolify mapping, and the approved public origin.
• Clarifies that Wallet configuration is optional at startup, while all three variables are required to enable the attendee action.
• Records environment isolation for class and object IDs and the persistent student-code barcode.
• Links the guide from the README.

Scope and merge order

This PR changes documentation only. PR #364 contains the application endpoint, service, UI, and tests for #3. Merge this guide before #364 so the operational setup is documented before the feature lands. Issuer provisioning and publishing access under #340 still require external validation before enabling Wallet for attendees.

Validation

• Checked the guide against Google's Generic Pass onboarding, REST authentication, class/object, brand, and publishing documentation.
• Ran Prettier on the changed Markdown and git diff --check.

Refs #340
Refs #3

[Copilot]

Copilot was unable to review this pull request because the user who requested the review has reached their quota limit.

[david-fs-valente]

Doc-only change, technically accurate against the actual code and against Google's Wallet docs (verified: env var names match #364's implementation exactly, QR/JWT flow description matches src/app/api/qrcode and src/app/api/saved, external links resolve). No AGENTS.md violations (no db push guidance, no raw process.env guidance, no secret material pasted). Requesting changes for one accuracy issue before merge; the README-link nit below is optional.

[david-fs-valente]

Thanks, this is a clear walkthrough. The env var names and the ISSUER_ID.SUFFIX class format match #364, the Google links all resolve, and there are no real IDs or secrets in it.

I'm requesting changes for two accuracy problems that will trip up whoever sets this up. Both are inline:

• the doc says the variables are required, but #364 makes them optional;
• there's no base64 encoding command, and #364's parser is strict.

Not inline:

• Link from README. README.md links every other docs/*.md (OBSERVABILITY, database-workflow, SHARED_DATA). Please add a one-line pointer so this can be found.
• Deployment caveat. #364 sets the compose file aside: docker-compose.app.yml has an explicit environment: list and no env_file. Until #364 adds the three GOOGLE_WALLET_* variables there, setting them in Coolify as this doc says won't reach the container.

[david-fs-valente]

This doesn't match #364. There, all three variables are optional in env.server.ts ("Optional at process level so non-Wallet environments still boot"), and when they're missing POST /api/wallet returns 503 while the "Adicionar ao Google Wallet" button is still shown. Suggest saying they're optional at boot, but that all three must be set in any environment where the button is exposed.

[david-fs-valente]

Please add how to produce this value. #364's parser rejects anything that doesn't round-trip exactly, and GNU base64 wraps at 76 columns by default, so base64 key.json pasted into .env or Coolify gives a 503 "credentials are invalid". Something like:

base64 -w0 key.json   # Linux
base64 -i key.json    # macOS

Also state that the value must be a single line of standard base64 with padding, encoding the complete JSON key file (it must contain client_email and private_key).

[david-fs-valente]

Merge-order and PR-number references (here, and at lines 70, 78, 158 and in the handoff section) will go stale once both PRs merge. Someone setting this up next edition needs the current contract, not the merge order. Suggest moving the merge-order note to the PR description and pointing at the code instead: src/config/env.server.ts, src/application/services/googleWalletService.ts, POST /api/wallet.

[david-fs-valente]

Worth adding: grant the service account no IAM roles on the GCP project. Wallet access comes only from this Developer invite. People often add Editor "to make it work". It may also help to mention that the iam.disableServiceAccountKeyCreation org policy can block step 2, and who to ask about it.

[david-fs-valente]

Classes are per environment, but #364's object IDs (<issuer>.fallstack-2026-<studentId>) aren't. If a DB is ever cloned between environments on the same issuer (e.g. staging restored from prod), staging would overwrite production passes. Worth a warning here, or recommend a separate issuer for non-prod.

[david-fs-valente]

Nit: this is the only place it's called "Google Wallet Business Console". Everywhere else it's "Google Pay & Wallet console". Same console, so pick one name.

[david-fs-valente]

Please specify that these are Coolify runtime variables, not build variables. They're server-only, and shouldn't end up in image layers. Also note that the save JWT's origins is taken from NEXT_PUBLIC_BASE_URL, so that value must be the real public host in each environment.

[dinisjcorreia]

Reviewed documentation against companion PR #364 and current Google Wallet guidance. Configuration, QR behavior, deployment mapping, and publishing prerequisites match. No blocking findings.