NORDSTAR selbst betreiben
Vom leeren Rechner bis zur laufenden Coaching-Plattform. Jeder Schritt einzeln, jeder Klick benannt. Vorkenntnisse brauchst du keine — auch nicht mit dem Terminal.
Was am Ende dasteht
Damit klar ist, wofür der Aufwand gut ist.
Eine laufende Coaching-Plattform auf deinem eigenen Rechner, mit einem fiktiven Beispielunternehmen namens Acme Cloud Solutions und fünf vorbereiteten Zugängen — je einer pro Rolle. Du kannst dich sofort anmelden und dich umsehen, bevor du irgendetwas anpasst.
| Login | Name | Rolle | Was sie zeigt |
|---|---|---|---|
admin | Alex Admin | Administrator | Nutzerverwaltung, Unternehmenskontext |
manager1 | Miriam Ott | Manager 2nd Line | Sicht über alle Teams |
manager2 | Sven Bauer | Manager 1st Line | Team-Coaching, Forecast |
ae | Nina Kranz | Account Executive | eigene Deals, Voice-Coaching |
se | Jonas Reiter | Solution Engineer | technische Qualifizierung |
Das Passwort lautet überall demo1234.
Du brauchst ein Google-Konto. Alles andere — Node.js, Git — installieren wir gleich gemeinsam. Bezahlt wird nichts: Firebase und Gemini haben Gratiskontingente, die für den Eigengebrauch reichen. Nur wenn du später E-Mail-Benachrichtigungen willst, muss das Google-Projekt auf den kostenpflichtigen Blaze-Tarif — der bleibt bei diesem Nutzungsumfang trotzdem bei null.
Es geht auch ganz ohne Google-Konto: Die Plattform läuft im Emulator-Modus komplett auf deinem Rechner. Dann funktioniert alles außer der gesprochenen Coaching-Session. Der Weg steht unten unter Schnellweg ohne Google-Konto.
Node.js und Git installieren
Zwei Werkzeuge, die die Plattform zum Laufen braucht. Einmalig.
- Öffne nodejs.org und lade die große grüne Schaltfläche mit dem Zusatz LTS herunter.
- Doppelklick auf die geladene
.pkg-Datei, dann durch den Installationsdialog klicken. - Git ist auf dem Mac meist schon dabei. Falls nicht, fragt dich macOS beim ersten Aufruf, ob es die Entwicklerwerkzeuge nachinstallieren soll — dort auf Installieren klicken.
- Öffne nodejs.org und lade die große grüne Schaltfläche mit dem Zusatz LTS herunter.
- Doppelklick auf die
.msi-Datei. Alle Vorgaben übernehmen, bis Finish. - Lade zusätzlich Git für Windows und installiere es ebenfalls mit den Vorgaben. Das bringt auch die Git Bash mit, die wir gleich als Terminal verwenden.
Terminal öffnen und Projekt holen
Das Terminal ist ein Fenster, in das man Befehle tippt. Mehr nicht.
Drücke ⌘ + Leertaste, tippe Terminal, Enter. Es öffnet sich ein Fenster mit einer Zeile, die auf deine Eingabe wartet.
Klicke auf Start, tippe Git Bash, Enter. Nimm bewusst Git Bash und nicht die Eingabeaufforderung — die Befehle in dieser Anleitung sind darauf abgestimmt.
Prüfe zuerst, ob Node angekommen ist. Tippe den Befehl und drücke Enter:
node --version
Kommt command not found, ist Node nicht installiert oder das Terminal war schon offen.
Schließe es, öffne es neu, versuch es noch einmal.
Jetzt holst du das Projekt. Der erste Befehl wechselt in deinen Dokumente-Ordner, der zweite lädt den Code:
cd ~/Documents git clone https://github.com/JonahNoel/nordstar.git cd nordstar
Das Repository ist privat — ohne Freigabe schlägt der Befehl fehl. Melde dich einfach direkt bei mir, per WhatsApp oder an heidbrink@3why.de, und nenn mir deinen GitHub-Benutzernamen. Ich trage dich ein, du bekommst eine Einladung per E-Mail — danach funktioniert der Befehl oben.
Beim ersten git clone fragt GitHub nach deiner Anmeldung. Das ist normal.
Zum Schluss die Programmbibliotheken herunterladen. Das dauert ein, zwei Minuten:
npm install
Warnungen über veraltete Pakete sind normal und stören nicht.
Firebase-Projekt anlegen
Hier liegen später alle Daten: Nutzer, Deals, Coaching-Sitzungen.
- Öffne die Firebase Console und melde dich mit deinem Google-Konto an.
- Klicke auf Projekt hinzufügen. Der Name ist frei wählbar, etwa nordstar-meinname. Google Analytics kannst du abwählen — es wird nicht gebraucht.
- Warte, bis das Projekt bereitsteht, und klicke auf Weiter.
Datenbank anlegen
- Links im Menü Erstellen → Firestore Database, dann Datenbank erstellen.
- Als Standort eur3 (europe-west) wählen, wenn du in Europa sitzt.
- Bei der Frage nach dem Modus Im Produktionsmodus starten wählen.
Produktionsmodus heißt: Zunächst ist alles gesperrt. Das ist richtig so. In Schritt 06 spielen wir die passenden Zugriffsregeln ein. Wählst du hier den Testmodus, steht deine Datenbank für einen Monat offen im Netz.
Anmeldung aktivieren
- Erstellen → Authentication, dann Jetzt starten.
- In der Liste E-Mail/Passwort anklicken, den oberen Schalter auf Aktiviert stellen und Speichern.
Echte E-Mail-Adressen braucht niemand. Die Anwendung baut intern aus dem Login ae
die Adresse ae@nordstar.app — das ist nur eine technische Hülle.
Web-App registrieren
- Oben links auf das Zahnrad, dann Projekteinstellungen.
- Nach unten scrollen bis Deine Apps und auf das Symbol </> klicken.
- Einen Spitznamen vergeben, App registrieren.
- Es erscheint ein Codeblock mit
firebaseConfig. Lass dieses Fenster offen — die sechs Werte daraus brauchst du in Schritt 05.
Dienstkonto-Schlüssel herunterladen
- Weiterhin in den Projekteinstellungen, oben auf den Reiter Dienstkonten.
- Neuen privaten Schlüssel generieren, dann Schlüssel generieren.
Es lädt eine
.json-Datei herunter. - Benenne diese Datei in
service-account.jsonum und lege sie in den Projektordnernordstar— also dorthin, wo auchpackage.jsonliegt.
Wer sie hat, hat vollen Zugriff auf dein Firebase-Projekt. Niemals weitergeben, nicht in Chats posten, nicht ins Internet laden. Das Projekt ist so eingerichtet, dass sie versehentlich nicht mitcommittet wird.
Gemini-Schlüssel besorgen
Das Sprachmodell, das die Coaching-Gespräche führt und auswertet.
- Öffne aistudio.google.com/apikey und melde dich mit demselben Google-Konto an.
- API-Schlüssel erstellen anklicken.
- Wenn du gefragt wirst, in welchem Projekt: wähle das Firebase-Projekt aus Schritt 03 — das hält alles beisammen.
- Kopiere den Schlüssel und leg ihn kurz beiseite, etwa in eine Notiz. Er beginnt mit
AIza.
Mit diesem Schlüssel kann jeder auf deine Rechnung Anfragen an Google stellen. Nicht weitergeben.
Einrichtungsassistent ausführen
Er fragt die Werte ab und schreibt alle Konfigurationsdateien selbst.
Zurück ins Terminal, im Ordner nordstar:
npm run setup
Der Assistent fragt nacheinander ab. Die ersten sechs Werte stehen im firebaseConfig-Block
aus Schritt 03 — jeweils der Text zwischen den Anführungszeichen:
| Frage | Was einzutragen ist |
|---|---|
| apiKey | der Wert hinter apiKey: |
| authDomain | …firebaseapp.com |
| projectId | die Projekt-ID |
| storageBucket | …firebasestorage.app |
| messagingSenderId | die lange Zahl |
| appId | beginnt mit 1: |
| measurementId, VAPID | leer lassen, mit Enter überspringen |
| Gemini-API-Schlüssel | der Schlüssel aus Schritt 04 |
| Cloud-Run-Proxy-URL | leer lassen — kommt später in Schritt 08 |
| alle weiteren | Enter drücken, die Vorgaben passen |
Am Ende meldet der Assistent, welche Dateien er geschrieben hat, und listet auf, was noch fehlt.
Regeln ausrollen und Beispieldaten anlegen
Ohne diesen Schritt bleibt die Anwendung nach dem Login leer.
Zuerst das Firebase-Kommandozeilenwerkzeug installieren und anmelden. Es öffnet dafür deinen Browser:
npm install -g firebase-tools firebase login
Meldet der erste Befehl EACCES oder permission denied, stelle
sudo voran: sudo npm install -g firebase-tools. Du wirst dann nach
deinem Mac-Passwort gefragt.
Jetzt die Zugriffsregeln ausrollen. Sie bestimmen, wer welche Daten lesen darf:
npm run deploy:rules
Und die Beispieldaten anlegen — fünf Nutzer, ein Unternehmensprofil, zwei Deals:
npm run seed
Prüfen und starten
Erst kontrollieren, dann öffnen — das erspart die Fehlersuche im Dunkeln.
Das Projekt bringt eine Selbstprüfung mit. Sie geht jede Voraussetzung durch und sagt im Klartext, was fehlt:
npm run doctor
Ein ! beim Voice-Proxy ist an dieser Stelle richtig — den richten wir in Schritt 08 ein. Steht dort ein ✗, nennt die Zeile darunter den Befehl, der es behebt.
Wenn die Prüfung durch ist, starte die Anwendung:
npm run dev
Öffne http://localhost:3000 im Browser
und melde dich an mit ae und demo1234. Du solltest zwei Deals sehen.
Das Terminal bleibt jetzt belegt — dort läuft der Server. Zum Beenden Strg + C drücken. Für weitere Befehle öffne ein zweites Terminalfenster.
Die fünf Demo-Zugänge stehen in dieser Anleitung und im Repository. Solange die Plattform nur auf deinem Rechner läuft, ist das folgenlos. Sobald du sie ins Internet stellst, ändere sie zuerst unter Admin Dashboard → Users.
Sprachfunktion aktivieren
Optional, aber es ist der eigentliche Kern des Produkts.
Bis hierher läuft alles außer dem gesprochenen Coaching. Dafür braucht es einen kleinen Vermittlungsdienst bei Google Cloud, der den Gemini-Schlüssel hält, damit er nicht im Browser landet.
- Installiere die Google-Cloud-CLI
und melde dich an mit
gcloud auth login. - Setze deine Projekt-ID ein und führe die folgenden Befehle aus.
# Projekt-ID eintragen export PROJECT_ID=deine-projekt-id # Gemini-Schlüssel sicher hinterlegen echo -n "DEIN_GEMINI_SCHLUESSEL" | \ gcloud secrets create GEMINI_API_KEY --data-file=- --replication-policy=automatic gcloud secrets add-iam-policy-binding GEMINI_API_KEY \ --member="serviceAccount:$(gcloud projects describe $PROJECT_ID \ --format='value(projectNumber)')-compute@developer.gserviceaccount.com" \ --role=roles/secretmanager.secretAccessor # Dienst ausrollen cd cloud-run gcloud config set project $PROJECT_ID gcloud run deploy nordstar-gemini-proxy \ --source . --region europe-west3 --allow-unauthenticated \ --set-env-vars FIREBASE_PROJECT_ID=$PROJECT_ID \ --set-secrets GEMINI_API_KEY=GEMINI_API_KEY:latest
Am Ende wird eine Adresse ausgegeben, die mit https:// beginnt. Ersetze https
durch wss und trage sie ein — dafür einfach den Assistenten noch einmal laufen lassen:
cd .. npm run setup
Alle bisherigen Werte stehen in eckigen Klammern und werden mit Enter übernommen. Nur bei der Proxy-URL trägst du die neue Adresse ein.
--allow-unauthenticated klingt beunruhigender, als es ist: Browser können bei einer
WebSocket-Verbindung keine Google-Zugangsdaten mitschicken. Der Dienst prüft stattdessen selbst,
ob ein gültiges Anmeldetoken deiner Plattform vorliegt, und lehnt sonst ab.
Schnellweg ohne Google-Konto
Zum Ausprobieren, ohne irgendetwas anzulegen.
Firebase lässt sich lokal nachbilden. Dafür brauchst du zusätzlich eine Java-Laufzeit:
auf dem Mac brew install openjdk, unter Windows von
adoptium.net.
npm install npm install -g firebase-tools cp .env.example .env.local echo "VITE_USE_FIREBASE_EMULATOR=true" >> .env.local
Dann drei Terminalfenster, je ein Befehl:
npm run emulators # Fenster 1 npm run seed:emulator # Fenster 2 npm run dev # Fenster 3
Anmelden mit ae / demo1234. Alles funktioniert außer der Sprachsitzung.
Die Daten liegen nur im Arbeitsspeicher und verschwinden, sobald du die Emulatoren beendest.
Hilfe von Claude Code holen
Wenn du feststeckst, kann ein KI-Assistent im Projektordner direkt mitlesen.
Claude Code ist ein Assistent,
der im Terminal läuft und die Dateien deines Projekts sieht. Das Repository ist darauf vorbereitet:
Es enthält eine Datei CLAUDE.md, die den Aufbau erklärt — der Assistent liest sie von selbst.
Einmalig einrichten
npm install -g @anthropic-ai/claude-code
Danach im Projektordner claude eingeben. Beim ersten Start führt dich das Programm
durch die Anmeldung.
Der Einstiegssatz
Kopiere diesen Text und füge ihn als erste Nachricht ein. Er sagt dem Assistenten, worum es geht, wo er nachschlagen soll und wo seine Grenzen liegen:
Ich installiere NORDSTAR gerade zum ersten Mal und habe wenig Erfahrung mit dem Terminal. Lies bitte zuerst CLAUDE.md, README.de.md und INSTALL.de.md in diesem Verzeichnis, damit du den Aufbau kennst. Führe dann `npm run doctor` aus und erkläre mir in einfachen Worten, was noch fehlt und wie ich es der Reihe nach behebe. Bitte: erst erklären, dann handeln. Frag mich, bevor du Dateien löschst oder überschreibst. Und sag mir, wenn ein Schritt etwas kostet oder nach außen sichtbar wird.
„Was bedeutet diese Fehlermeldung?" — Meldung einfach hineinkopieren.
„Warum bleibt die Seite nach dem Login leer?"
„Erklär mir, was npm run deploy:rules genau macht, bevor ich es ausführe."
Gib dem Assistenten niemals dein Google-Passwort — er braucht es nicht, und Anmeldungen im Browser musst du ohnehin selbst durchführen. Und lass ihn nichts in deinem Firebase-Projekt löschen, ohne dass du verstanden hast, was verschwindet.
Wenn etwas klemmt
Die Meldungen, die erfahrungsgemäß auftreten — im Wortlaut.
command not found: node / npm
Node.js ist nicht installiert, oder das Terminal war beim Installieren schon offen.
Terminal schließen, neu öffnen, node --version erneut versuchen. Hilft das nicht,
Schritt 01 wiederholen.
Missing or insufficient permissions
Die Zugriffsregeln sind noch nicht in deinem Projekt. Führe
npm run deploy:rules aus und lade die Seite neu. Das ist der häufigste Grund für
eine Anwendung, die lädt, aber leer bleibt.
auth/invalid-credential beim Anmelden
Entweder ist in Firebase die Anmeldeart E-Mail/Passwort nicht aktiviert
(Schritt 03), oder npm run seed ist nie durchgelaufen. npm run doctor
sagt dir, welches von beidem.
service-account.json nicht gefunden
Die Datei liegt nicht im richtigen Ordner oder heißt anders. Sie muss genau
service-account.json heißen und direkt neben package.json liegen —
nicht in einem Unterordner, nicht im Download-Ordner.
Die Seite bleibt weiß
Meist fehlen Werte in der Konfiguration. npm run doctor ausführen.
Wenn dort alles grün ist, im Browser mit F12 die Entwicklerkonsole öffnen und die
rote Meldung dort in die Suche oder an den Assistenten geben.
unauthenticated / auth_backend_unavailable
Zwei verschiedene Dinge. unauthenticated heißt: Deine Sitzung ist
abgelaufen — einmal abmelden und neu anmelden. auth_backend_unavailable heißt: Der Server
kann Anmeldetoken nicht prüfen, weil ihm die Zugangsdaten fehlen — lokal also
service-account.json, bei einer Veröffentlichung die Umgebungsvariable
FIREBASE_SERVICE_ACCOUNT.
Die Sprachsitzung verbindet sich nicht
Entweder fehlt die Proxy-Adresse, oder sie beginnt mit https://
statt wss://. Nach jeder Änderung an der Konfiguration muss npm run dev
neu gestartet werden — die Werte werden nur beim Start gelesen.
Der Reiter „Users" bleibt leer
Das ist ein bekannter Fehler der Anwendung, kein Installationsproblem. Die Nutzerverwaltung über diese Oberfläche funktioniert derzeit nicht; Rollen lassen sich über das Seed-Skript setzen.
npm install bricht mit EACCES ab
Fehlende Schreibrechte. Auf dem Mac sudo voranstellen. Unter
Windows die Git Bash als Administrator öffnen (Rechtsklick → Als Administrator ausführen).
Run NORDSTAR yourself
From an empty machine to a working coaching platform. Every step on its own, every click named. No prior experience needed — not even with a terminal.
What you end up with
So it is clear what the effort buys you.
A working coaching platform on your own machine, with a fictitious example company called Acme Cloud Solutions and five prepared logins — one per role. You can sign in and look around before changing anything.
| Login | Name | Role | What it shows |
|---|---|---|---|
admin | Alex Admin | Administrator | user management, company context |
manager1 | Miriam Ott | Manager, 2nd line | view across all teams |
manager2 | Sven Bauer | Manager, 1st line | team coaching, forecast |
ae | Nina Kranz | Account Executive | own deals, voice coaching |
se | Jonas Reiter | Solution Engineer | technical qualification |
The password is demo1234 for all of them.
You need a Google account. Everything else — Node.js, Git — we install together in a moment. Nothing is paid for: Firebase and Gemini have free tiers that cover personal use. Only if you later want email notifications does the Google project need the paid Blaze plan — which still costs nothing at this usage level.
It also works without a Google account: the platform runs entirely on your machine in emulator mode. Everything works except the spoken coaching session. See Shortcut without a Google account below.
Install Node.js and Git
Two tools the platform needs. One time only.
- Open nodejs.org and download the large green button marked LTS.
- Double-click the downloaded
.pkgfile and click through the installer. - Git usually ships with macOS. If not, macOS offers to install the developer tools the first time you use it — click Install.
- Open nodejs.org and download the large green button marked LTS.
- Double-click the
.msifile. Accept all defaults through to Finish. - Also install Git for Windows with its defaults. It brings Git Bash, which we use as the terminal.
Open a terminal and get the project
A terminal is a window you type commands into. That is all it is.
Press ⌘ + Space, type Terminal, press Enter. A window opens with a line waiting for your input.
Click Start, type Git Bash, press Enter. Deliberately use Git Bash rather than Command Prompt — the commands here are written for it.
First check that Node arrived. Type the command and press Enter:
node --version
If you get command not found, Node is not installed, or the terminal was already open
during installation. Close it, open it again, try once more.
Now get the project. The first command moves into your Documents folder, the second downloads the code:
cd ~/Documents git clone https://github.com/JonahNoel/nordstar.git cd nordstar
The repository is private — without an invitation the command fails. Just get in touch with me directly, via WhatsApp or at heidbrink@3why.de, and tell me your GitHub username. I will add you, you get an invitation by email — after that the command above works.
On the first git clone GitHub asks you to sign in. That is expected.
Finally, download the libraries. This takes a minute or two:
npm install
Warnings about outdated packages are normal and harmless.
Create the Firebase project
This is where all data lives: users, deals, coaching sessions.
- Open the Firebase console and sign in with your Google account.
- Click Add project. Any name will do, for example nordstar-yourname. You can switch off Google Analytics — it is not used.
- Wait for the project to be ready, then click Continue.
Create the database
- In the left menu, Build → Firestore Database, then Create database.
- Choose eur3 (europe-west) as the location if you are in Europe.
- When asked about the mode, choose Start in production mode.
Production mode means everything is locked at first. That is correct. In step 06 we deploy the proper access rules. If you pick test mode here, your database sits open on the internet for a month.
Enable sign-in
- Build → Authentication, then Get started.
- Click Email/Password in the list, set the upper toggle to Enabled, and Save.
No real email addresses are needed. Internally the app turns the login ae into
ae@nordstar.app — that is just a technical wrapper.
Register a web app
- Click the gear icon at the top left, then Project settings.
- Scroll down to Your apps and click the </> icon.
- Give it a nickname, then Register app.
- A code block containing
firebaseConfigappears. Keep this window open — you need those six values in step 05.
Download the service account key
- Still in Project settings, open the Service accounts tab.
- Generate new private key, then Generate key. A
.jsonfile downloads. - Rename it to
service-account.jsonand move it into thenordstarproject folder — the same place aspackage.json.
Whoever holds it has full access to your Firebase project. Never share it, never post it in a chat, never upload it. The project is configured so it cannot be committed by accident.
Get a Gemini key
The language model that runs and scores the coaching conversations.
- Open aistudio.google.com/apikey and sign in with the same Google account.
- Click Create API key.
- If asked which project: pick the Firebase project from step 03 — it keeps everything together.
- Copy the key and keep it somewhere for a moment. It starts with
AIza.
Anyone with this key can send requests to Google on your bill. Do not share it.
Run the setup wizard
It asks for the values and writes every configuration file itself.
Back in the terminal, inside the nordstar folder:
npm run setup
The wizard asks one question at a time. The first six values are in the firebaseConfig
block from step 03 — each is the text between the quotation marks:
| Question | What to enter |
|---|---|
| apiKey | the value after apiKey: |
| authDomain | …firebaseapp.com |
| projectId | the project ID |
| storageBucket | …firebasestorage.app |
| messagingSenderId | the long number |
| appId | starts with 1: |
| measurementId, VAPID | leave empty, skip with Enter |
| Gemini API key | the key from step 04 |
| Cloud Run proxy URL | leave empty — it arrives in step 08 |
| everything else | press Enter, the defaults are fine |
At the end the wizard reports which files it wrote and lists what is still missing.
Deploy rules and create sample data
Without this step the app stays empty after login.
First install the Firebase command line tool and sign in. It opens your browser:
npm install -g firebase-tools firebase login
If the first command reports EACCES or permission denied, put
sudo in front: sudo npm install -g firebase-tools. You will be asked for
your Mac password.
Now deploy the access rules. They decide who may read which data:
npm run deploy:rules
And create the sample data — five users, one company profile, two deals:
npm run seed
Check, then start
Verify first, open second — it saves you searching in the dark.
The project ships with a self-check. It walks through every prerequisite and says plainly what is missing:
npm run doctor
A ! next to the voice proxy is correct at this point — that comes in step 08. A ✗ is followed by the exact command that fixes it.
Once the check passes, start the app:
npm run dev
Open http://localhost:3000 and sign in
with ae and demo1234. You should see two deals.
The terminal is now occupied — the server runs there. Press Ctrl + C to stop it. Open a second terminal window for further commands.
The five demo logins are in this guide and in the repository. While the platform only runs on your machine that is harmless. Before you put it on the internet, change them under Admin Dashboard → Users.
Enable the voice feature
Optional, but it is the actual core of the product.
Everything works so far except spoken coaching. That needs a small relay service on Google Cloud which holds the Gemini key, so it never reaches the browser.
- Install the Google Cloud CLI
and sign in with
gcloud auth login. - Insert your project ID and run the commands below.
# insert your project id export PROJECT_ID=your-project-id # store the Gemini key securely echo -n "YOUR_GEMINI_KEY" | \ gcloud secrets create GEMINI_API_KEY --data-file=- --replication-policy=automatic gcloud secrets add-iam-policy-binding GEMINI_API_KEY \ --member="serviceAccount:$(gcloud projects describe $PROJECT_ID \ --format='value(projectNumber)')-compute@developer.gserviceaccount.com" \ --role=roles/secretmanager.secretAccessor # deploy the service cd cloud-run gcloud config set project $PROJECT_ID gcloud run deploy nordstar-gemini-proxy \ --source . --region europe-west3 --allow-unauthenticated \ --set-env-vars FIREBASE_PROJECT_ID=$PROJECT_ID \ --set-secrets GEMINI_API_KEY=GEMINI_API_KEY:latest
At the end an address starting with https:// is printed. Replace https with
wss and store it by running the wizard once more:
cd .. npm run setup
Existing values appear in square brackets and are kept by pressing Enter. Only the proxy URL needs the new address.
--allow-unauthenticated sounds worse than it is: browsers cannot attach Google credentials
to a WebSocket handshake. The service checks for a valid sign-in token from your platform instead, and
rejects anything else.
Shortcut without a Google account
For trying it out without creating anything.
Firebase can be simulated locally. You additionally need a Java runtime: on macOS
brew install openjdk, on Windows from
adoptium.net.
npm install npm install -g firebase-tools cp .env.example .env.local echo "VITE_USE_FIREBASE_EMULATOR=true" >> .env.local
Then three terminal windows, one command each:
npm run emulators # window 1 npm run seed:emulator # window 2 npm run dev # window 3
Sign in with ae / demo1234. Everything works except the voice session.
The data lives in memory only and disappears when you stop the emulators.
Getting help from Claude Code
If you get stuck, an AI assistant can read along inside the project folder.
Claude Code is an assistant that
runs in the terminal and can see your project files. The repository is prepared for it: it contains a
CLAUDE.md file explaining the architecture, which the assistant reads on its own.
One-time setup
npm install -g @anthropic-ai/claude-code
Then type claude inside the project folder. On first start it walks you through signing in.
The opening message
Copy this text and send it as your first message. It tells the assistant what you are doing, where to look, and where its limits are:
I am installing NORDSTAR for the first time and have little experience with the terminal. Please read CLAUDE.md, README.md and INSTALL.md in this directory first, so you know how the project is built. Then run `npm run doctor` and explain in plain language what is still missing and how to fix it, one thing at a time. Please: explain before acting. Ask me before deleting or overwriting files. And tell me when a step costs money or becomes visible to others.
Never give the assistant your Google password — it does not need one, and browser sign-ins are yours to do. And do not let it delete anything in your Firebase project before you understand what disappears.
When something breaks
The messages that actually come up, verbatim.
command not found: node / npm
Node.js is not installed, or the terminal was already open during installation.
Close it, reopen it, try node --version again. If that does not help, repeat step 01.
Missing or insufficient permissions
The access rules are not in your project yet. Run npm run deploy:rules
and reload the page. This is the most common reason for an app that loads but stays empty.
auth/invalid-credential on sign-in
Either Email/Password sign-in is not enabled in Firebase (step 03), or
npm run seed never ran. npm run doctor tells you which.
service-account.json not found
The file is in the wrong folder or has a different name. It must be called exactly
service-account.json and sit next to package.json — not in a subfolder,
not in Downloads.
unauthenticated / auth_backend_unavailable
Two different things. unauthenticated means your session expired — sign out
and back in. auth_backend_unavailable means the server cannot verify sign-in tokens because it
lacks credentials — locally that is service-account.json, in a deployment the
FIREBASE_SERVICE_ACCOUNT environment variable.
The voice session will not connect
Either the proxy address is missing, or it starts with https:// instead of
wss://. After any configuration change npm run dev must be restarted — the
values are only read at startup.
The "Users" tab stays empty
A known bug in the application, not an installation problem. User management through that screen does not currently work; roles can be set through the seed script.