FahrtWerk — Komplettguide für engagierte Schüler:innen

Wie ihr eigenen Code in https://fahrtwerk.vianova.website/ einbringt — von „noch nichts installiert" bis „läuft online".

---

Wen dieser Guide adressiert

Du bist in der AG „Programmierung" der Pestalozzi-Gemeinschaftsschule, hast Lust, an FahrtWerk wirklich mitzuwirken — und nicht nur Texte zu liefern, sondern selber Code zu schreiben. Vorkenntnisse: hilfreich, aber nicht zwingend. Wer schon mal HTML oder ein bisschen Python gesehen hat, kommt sehr gut mit. Wer ganz neu ist, schafft die kosmetischen Aufgaben (Anker #2, #3, #4, #6, #7, #8, #10) auch ohne Probleme.

Veranschlagte Zeit für den ersten kompletten Durchlauf inklusive Setup: ca. 90 Minuten.

---

Teil A — Entwicklungsumgebung einrichten (einmalig)

A.1 Code-Editor: Visual Studio Code

VS Code ist kostenlos, läuft auf Windows, macOS und Linux und ist das, womit auch die Hauptentwicklung passiert.

1. Auf https://code.visualstudio.com/ gehen.
2. Den großen blauen Download-Button drücken — die Seite erkennt dein System automatisch.
3. Installer ausführen, alle Standard-Optionen akzeptieren.
4. Nach dem Start zwei Erweiterungen empfehle ich dringend:
   • „ESLint" (von Microsoft) — markiert Tippfehler in JavaScript live.
   • „Tailwind CSS IntelliSense" — schlägt CSS-Klassen automatisch vor.

Beide findest du im Extensions-Tab (linkes Symbolleisten-Icon mit den vier Würfeln).

A.2 Node.js (Version 20 oder neuer)

Node.js ist die Laufzeit, mit der FahrtWerk läuft. Ohne Node läuft gar nichts.

1. Auf https://nodejs.org/ gehen.
2. Die LTS-Version herunterladen (aktuell 20.x oder 22.x — beide funktionieren).
3. Installer ausführen, Standard-Optionen.
4. Prüfen, ob es geklappt hat — Terminal öffnen (siehe nächster Abschnitt) und tippen:

node --version
npm --version

Beides muss eine Versionsnummer ausspucken. Wenn node --version „Befehl nicht gefunden" sagt, hat die Installation den PATH nicht aktualisiert — Computer einmal neu starten.

A.3 Terminal kennen lernen

Du brauchst ein Terminal-Fenster, um Befehle auszuführen.

• Windows: „Windows Terminal" aus dem Microsoft Store oder einfach in VS Code mit Strg + Ö (das ist die Backtick-Taste).
• macOS: „Terminal" aus dem Programme-Ordner oder ebenfalls in VS Code mit Strg + Ö.
• Linux: Du weißt es eh.

Kleines Mini-Glossar — in den nächsten Abschnitten brauchst du diese Befehle:

Befehl	Was er tut
cd ordnername	wechsle in den Ordner
cd ..	gehe einen Ordner nach oben
ls (macOS/Linux) bzw. dir (Windows)	zeige Inhalt des Ordners
pwd	zeige aktuellen Pfad

A.4 Git installieren

Git ist die Versionsverwaltung. Damit holst du den Code, speicherst Stände und reichst Änderungen ein.

1. Auf https://git-scm.com/downloads gehen.
2. Für dein System herunterladen, installieren — Standard-Optionen.
3. Im Terminal prüfen:

git --version

4. Einmalig deine Identität für Commits hinterlegen (E-Mail muss nicht öffentlich sein):

git config --global user.name "Vorname Nachname"
git config --global user.email "deine-mail@example.de"

A.5 GitHub-Account (empfohlen, optional)

Wenn die Lehrkraft euch über GitHub arbeiten lässt, brauchst du einen Account.

1. Auf https://github.com/signup gehen, mit privater oder Schul-Mail registrieren.
2. Username merken — den wirst du oft brauchen.
3. Sag deiner Lehrkraft den Username, damit sie dich zum FahrtWerk-Repository einlädt.

Falls eure Schule kein GitHub erlaubt: Kein Problem. Dann läuft der Austausch über USB-Stick / E-Mail / Schul-Cloud. Springe zu Teil B, Variante 2.

---

Teil B — FahrtWerk-Quellcode bekommen

Variante 1 — Über GitHub (sauberer Weg)

Du brauchst einmalig die Repo-URL von der Lehrkraft, etwa https://github.com/<schul-org>/fahrtwerk.git.

# Wechsle in einen Ordner, wo deine Projekte liegen sollen, z.B.:
cd ~/Projekte         # macOS/Linux
cd %USERPROFILE%\Projekte   # Windows

# Code herunterladen:
git clone https://github.com/<schul-org>/fahrtwerk.git
cd fahrtwerk

Variante 2 — Über ZIP von der Lehrkraft

1. ZIP-Datei fahrtwerk.zip (oder fahrtwerk.tar.gz) entpacken.
2. Im Terminal in den entpackten Ordner wechseln:

cd Pfad/zum/entpackten/fahrtwerk

Was liegt im Ordner?

Wirf einen kurzen Blick rein. Du siehst grob:

fahrtwerk/
├── docker-compose.yml      ← braucht dich nicht zu interessieren
├── DEPLOY.md               ← Server-Doku, ist Lehrer-Sache
├── docs/
│   └── SCHUELER_GUIDE.md   ← die Kurzversion dieses Guides
├── db/init.sql             ← Datenbank-Schema, NICHT anfassen
└── frontend/               ← HIER spielst du!
    ├── package.json
    ├── tailwind.config.js
    └── src/
        ├── app/            ← Seiten (Next.js App Router)
        ├── components/     ← React-Komponenten
        └── lib/            ← Hilfsdateien (Themen, Pseudonyme, …)

Merke: Für die Schüler-Aufgaben spielt sich alles in frontend/src/ ab. Alles außerhalb ist Infrastruktur — Finger weg.

---

Teil C — Erste Inbetriebnahme lokal

Du installierst jetzt die JavaScript-Pakete und startest FahrtWerk auf deinem eigenen Rechner. Du brauchst dafür kein Internet zum Server, keine Datenbank, kein Lehrer-Login.

# vom Hauptordner fahrtwerk/ aus:
cd frontend
npm install

Beim ersten Mal dauert das 1–3 Minuten. Es lädt rund 200 MB an Paketen runter und legt sie in einem Ordner namens node_modules/ ab. Falls Warnungen über „deprecated" Pakete auftauchen — ignorieren, das ist normal.

Jetzt starten:

npm run dev

Im Terminal sollte stehen:

  ▲ Next.js 14.x.x
  - Local:        http://localhost:3000
  ✓ Ready in 2.3s

Im Browser http://localhost:3000 öffnen — FahrtWerk läuft auf deinem Rechner.

Was du sehen wirst: Die Themenkarten sind sichtbar, du kannst Themen-Detailseiten öffnen. Was nicht geht ohne Datenbank: Kommentare schreiben, Bilder hochladen, Lehrer-Dashboard. Das ist okay — für 8 von 10 Schüler-Ankern brauchst du das nicht.

Stop-Befehl im Terminal: Strg + C beendet npm run dev. Beim nächsten Mal einfach wieder npm run dev tippen, kein erneutes npm install nötig.

---

Teil D — Die zehn Schüler-Anker im Code

An genau zehn Stellen im Quellcode haben wir Markierungen eingebaut, an denen ihr gefahrlos eigene Sachen einbringen könnt. Jede Markierung sieht so aus:

// 🔧 SCHÜLER-AG ANKER #4:
//   ...kurze Erklärung was hier passiert...

Alle Anker auf einmal finden

In VS Code mit Strg + Shift + F (macOS: Cmd + Shift + F) ein Projektweites Suchfenster öffnen, dort SCHÜLER-AG ANKER eintippen — und du bekommst eine Liste aller zehn Stellen. Klick führt dich direkt hin.

Übersicht — was geht wo?

#	Datei	Worum geht's	Schwierigkeit
1	frontend/src/lib/topics.js	Diskussions-Themen ergänzen	⭐⭐
2	frontend/src/lib/identity.js	Pseudonym-Vorschläge	⭐
3	frontend/src/app/page.js	Sticker auf Startseite	⭐
4	frontend/src/components/Footer.js	Slogans im Footer	⭐
5	frontend/src/components/ReportButton.js	Melde-Gründe	⭐⭐
6	frontend/src/app/app/data/rewards.js	Belohnungen in der App	⭐⭐
7	frontend/src/app/app/data/chat-demo.js	Demo-Chat-Nachrichten	⭐
8	frontend/src/app/app/data/emergency.js	Notfall-Kontakte	⭐
9	frontend/src/app/app/data/fahrtwerk-stations.json	Fahrzeugmodelle	⭐⭐
10	frontend/src/app/app/data/identities.js	Demo-Identitäten	⭐

Die Detail-Anleitungen pro Anker stehen in docs/SCHUELER_GUIDE.md direkt im Projekt — die Ordnerstruktur, Pflichtfelder und Regeln pro Aufgabe sind dort schon ausführlich beschrieben.

Beispiel: Ein neues Thema hinzufügen (Anker #1)

Damit du den Ablauf einmal komplett gesehen hast, hier exemplarisch der ganze Mini-Workflow:

1. Datei öffnen. In VS Code im linken Datei-Baum auf frontend/src/lib/topics.js klicken.

2. Anker finden. Strg + F (Suchen-in-Datei), ANKER #1 eingeben.

3. Bestehenden Block kopieren. Du siehst Einträge wie:

{
  slug: 'sicherheit',
  title: 'Wie sicher fühlen wir uns abends an der Bushaltestelle?',
  lead: 'Beleuchtung, Wartezeiten, Mitfahrgelegenheiten — was muss sich ändern?',
  prompt: 'Beschreibt eine konkrete Situation. Foto ist okay, aber bitte ohne Personen darauf.',
  emoji: '🚏',
  color: 'signal',
},

Den ganzen Block (von { bis },) markieren, kopieren, am Ende des Arrays einfügen.

4. Werte ändern. slug muss eindeutig sein und darf nur Kleinbuchstaben + Bindestriche enthalten. Beispiel:

{
  slug: 'lastenrad',
  title: 'Brauchen wir ein Lastenrad an der Schule?',
  lead: 'Für Sportgeräte, Theaterkulissen, Bio-Marktbesuche — wofür würde es reichen?',
  prompt: 'Sammelt konkrete Anlässe, wo ein Lastenrad geholfen hätte. Wer würde es nutzen, wer wartet es?',
  emoji: '🚲',
  color: 'spark',
},

5. Speichern. Strg + S. Wenn npm run dev noch läuft, lädt die Seite im Browser automatisch neu — du siehst deine neue Karte sofort.

6. Sanity-Check im Browser. Karte erscheint? Beim Klick auf die Karte erscheint die Detailseite mit deinem Prompt? Emoji wird gerendert? Wenn ja → fertig.

Wenn etwas kaputt geht

Manchmal vergisst man ein Komma oder eine Klammer. Dann zeigt das Browser-Fenster eine rote Fehlermeldung. So gehst du vor:

1. Lies die Fehlermeldung. Next.js zeigt dir ziemlich exakt die Zeilennummer und manchmal sogar einen Tipp.
2. Browser-DevTools öffnen (F12) — rote Einträge in der Konsole geben oft präzisere Hinweise.
3. Letzte Änderung rückgängig mit Strg + Z in VS Code.
4. Notfall-Reset: Im Terminal git diff zeigt dir genau, was du verändert hast. git checkout -- pfad/zur/datei.js setzt eine einzelne Datei auf den letzten committeten Stand zurück.

---

Teil E — Änderungen einreichen

Variante 1 — Per Git/GitHub (sauber)

Wenn ihr über GitHub arbeitet, ist das der professionelle Weg.

# Vom fahrtwerk/-Hauptordner aus:

# Schritt 1: Eigenen Branch anlegen — niemals direkt auf "main" arbeiten!
git checkout -b mein-name/neue-themen-2025-11

# Schritt 2: Änderungen ansehen
git status
git diff

# Schritt 3: Änderungen committen
git add frontend/src/lib/topics.js
git commit -m "Neues Thema: Lastenrad an der Schule"

# Schritt 4: Auf GitHub hochladen
git push origin mein-name/neue-themen-2025-11

Im Terminal-Output erscheint nach dem push ein Link wie: https://github.com/<schul-org>/fahrtwerk/pull/new/mein-name/...

→ Diesen Link im Browser öffnen, Pull Request anlegen, kurze Beschreibung schreiben („Neues Thema Lastenrad ergänzt, Anker #1, Klassen-Brainstorming vom 12.11."), absenden.

Die Lehrkraft schaut sich den Pull Request an, gibt Feedback oder mergt ihn — danach landet dein Code im offiziellen Stand und nach dem nächsten Deployment auch auf https://fahrtwerk.vianova.website/.

Variante 2 — Per ZIP/USB

Wenn kein GitHub: Im Terminal vom Hauptordner aus:

# Nur deine Änderungen als Patch exportieren:
git diff > meine-aenderungen.patch

Diese .patch-Datei oder den ganzen frontend/src/-Ordner per USB/Mail an die Lehrkraft geben — sie übernimmt den Rest.

---

Teil F — Was auf https://fahrtwerk.vianova.website/ landet

Wichtig zu verstehen: Was du lokal mit npm run dev siehst, ist nur deine Vorschau. Auf der echten Live-Seite erscheint deine Änderung erst nach drei Schritten:

1. Pull Request mergen (oder Patch übernehmen) — macht die Lehrkraft.
2. Deployment auf den Server 142.132.232.211 triggern — macht die Lehrkraft.
3. Traefik liefert die neue Version aus — passiert automatisch innerhalb 1–2 Minuten.

Direkten SSH- oder Server-Zugang bekommt ihr Schüler:innen bewusst nicht — das schützt euch und die Plattform. Aber: Sobald deine Änderung live ist, kannst du im Browser hart neu laden (Strg + Shift + R) und siehst dein Werk auf der echten Domain.

---

Teil G — Was geht nicht im Schüler-Modus?

Damit ihr ohne Frust arbeitet, sind ein paar Sachen bewusst außerhalb der Anker:

• Layout grundlegend umbauen (Farb-System, Schriftarten, Grid)
• Neue Seiten/Routen anlegen
• API-Endpoints (frontend/src/app/api/) verändern
• Direkt mit der Datenbank reden
• Externe npm-Pakete hinzufügen (package.json ist tabu)
• Server-Konfiguration, Docker, Deployment

Wenn euch dafür eine Idee in den Sinn kommt, ist das super — aber dann ist es ein Gespräch mit der Lehrkraft / dem Hauptentwickler-Team und keine Solo-Aktion. Es gibt für die zweite Iteration explizit größere Aufgaben, die genau dort ansetzen.

---

Teil H — Hilfe & Support

Wenn du nicht weiterkommst:

1. Lies die Fehlermeldung in Ruhe. 80 % der Fehler erklären sich selbst, wenn man die Meldung wirklich liest statt nur überfliegt.
2. Such im Code nach dem Anker — die Kommentare oberhalb erklären meist, was rein darf und was nicht.
3. Schau in docs/SCHUELER_GUIDE.md für die Detail-Regeln pro Aufgabe.
4. Frag in der AG. Andere haben oft genau den gleichen Fehler schon mal gehabt.
5. Frag die Lehrkraft. Sie hat einen direkten Draht zu den Hauptentwickler:innen und kann meistens innerhalb eines Tages eine Antwort organisieren.

Wenn etwas richtig kaputt aussieht:

git status und git diff ausführen, Output abfotografieren / kopieren — damit kann jede:r Helfer:in viel schneller sehen, was los ist, als wenn du nur erzählst „geht nicht".

---

Anhang — Mini-Cheatsheet

# Einmalig
git clone <repo-url>
cd fahrtwerk/frontend
npm install

# Bei jeder Arbeitssitzung
cd fahrtwerk/frontend
npm run dev                # Entwicklungsserver auf localhost:3000

# Änderungen festhalten
cd ..                      # zurück in fahrtwerk/
git checkout -b mein-feature
git add .
git commit -m "Was ich gemacht habe"
git push origin mein-feature

# Aktuellen Stand vom Server holen (vor neuer Arbeit!)
git checkout main
git pull

Viel Spaß und willkommen im Team!