Prerequisites

You can read this documentation without any of the below. To run the platform you need the repositories, a Node toolchain, and access to the non-production Firebase project.

The one rule

Never copy a production secret onto a laptop, into a chat, or into a document. The API repositories fail closed when the Firebase project and the Stripe key mode do not match the environment, so a "borrowed" production file usually does not work anyway — and it turns a laptop into a production credential store. Ask the maintainer for the non-production env files.

Toolchain

Tool	Version	Why
Node.js	20 LTS or newer	All services target Node 20; Vite 3 and Vite 5 both run on it.
npm	10+	Every repository uses npm, including the lockfiles.
Git	current	Branch discipline matters here; use git switch, not detached checkouts.
Docker	current, optional	Needed for the worker and multimedia images, not for the SPAs or APIs.
Firebase CLI	current, optional	Emulator use and rules/index inspection.
Google Cloud CLI	current, optional	Only if you operate the GCE worker, buckets or Secret Manager.
ffmpeg	any recent build, optional	Only for debugging the worker outside its container.

Check what you have:

node --version    # v20.x or newer
npm --version
git --version
docker --version  # optional

Repositories

All paths are under /shared/from_machine_c/PROJECTS/GREYSCREEN/DEV_PROCESS/ unless noted. /home/prof/local_share/from_machine_c is the same tree.

Repository	Needed for
gstv-website	Public site
greyscreen-webview	Mobile SPA
greyscreen-expo-webview	Phone shell
gstv-tv	Android TV
gstv-admin-web	Back office
gstv-customer-api	Public API
gstv-admin-api	Admin API
gstv-vps	Transcode worker
gstv-multimedia	HLS streaming
vps-reverse-proxy (under PROJECTS/REVERSE_PROXY_SERVERS/)	Gateway and test stack
gstv-infra	GCE templates and startup script (operator only)
gstv-migration	Indexes and RTDB rules (reference only)

You do not need all of them to work on one. The per-repository guide maps a task to the folder and command.

Access

Access	Used for	Notes
Firebase project greyscreen-test-5fb86	Dev and test	The non-production trust domain. A service-account JSON is required by both APIs.
Firestore + RTDB data	Catalogue, queues, pairing	The test stack currently shares the production project — see Environments.
GCS buckets with -test suffix	Uploads and playback	The APIs validate the suffix against APP_ENV.
GitHub production environment	Release approval	Only needed to deploy to production.
Test VPS (82.38.44.60)	Reading logs, restarting the test stack	SSH access; deploys use flock, never two at once.
Stripe test keys	Card checkout	Must begin with sk_test_ outside production.
Flutterwave credentials	Mobile money	The production merchant is used in every environment. Treat charges as real.

What "local" means

There are three practical setups:

1. Frontend only — the SPA runs on your machine and talks to https://test.greyscreentv.com. No secrets. This is enough for most UI work.
2. Frontend + one API — the SPA talks to a local API that talks to the test Firebase project. You need a non-production service-account key and the .env.*.local files.
3. The full stack — both APIs, the multimedia server, and optionally the worker, all local. This needs gcsfuse, a GCS key, and a bucket you are allowed to write to. Avoid running the worker against a shared queue unless you know who else consumes it.

Start with option 1 unless your change is server-side.

Before you begin

• You know which branch you are on (git status).
• You have the repository's .env.template in front of you, not a production .env.
• Your Node version is 20 or newer.
• You have asked for access to the non-production Firebase project, if your task needs it.
• You have read Environments, especially the test-stack caveat.

Next: Environments → Running locally.