🚀 Schnelleinstieg für Entwickler¶

Willkommen bei Carambus! Dieser Guide hilft dir, schnell mit der Entwicklung zu beginnen.

📋 Voraussetzungen¶

Ruby 3.2+ (empfohlen: 3.2.1)
Rails 7.2+
PostgreSQL 15+
Redis
Git
Docker (optional, aber empfohlen)
SSH-Key für GitHub-Zugriff

🔑 GitHub-Zugriff einrichten (Wichtig!)¶

Das Repository verwendet SSH-Authentifizierung, nicht HTTPS!

Schritt 1: SSH-Key generieren¶

# SSH-Key generieren
ssh-keygen -t rsa -b 4096 -C "deine-email@example.com"

# SSH-Key zu ssh-agent hinzufügen
ssh-add ~/.ssh/id_rsa

# Öffentlichen Schlüssel anzeigen
cat ~/.ssh/id_rsa.pub

Schritt 2: SSH-Key zu GitHub hinzufügen¶

Den öffentlichen Schlüssel kopieren (Ausgabe von cat ~/.ssh/id_rsa.pub)
GitHub → Settings → SSH and GPG keys → "New SSH key"
Schlüssel einfügen und speichern

Schritt 3: SSH-Verbindung testen¶

# Test der SSH-Verbindung
ssh -T git@github.com

# Sollte ausgeben: "Hi username! You've successfully authenticated..."

🐳 Option 1: Docker-Setup (Empfohlen)¶

# Terminal öffnen und ausführen:
git clone git@github.com:GernotUllrich/carambus.git
cd carambus

# Docker-Setup starten (alles läuft automatisch)
docker-compose -f docker-compose.development.api-server.yml up

Vorteile: - ✅ Alle Dependencies werden automatisch installiert - ✅ Datenbank wird automatisch eingerichtet - ✅ Keine Konflikte mit lokalen Services - ✅ Einfach zu starten/stoppen

🖥️ Option 2: Lokales Setup¶

# Repository klonen (WICHTIG: SSH-URL verwenden!)
git clone git@github.com:GernotUllrich/carambus.git
cd carambus

# Dependencies installieren
bundle install
yarn install

# Datenbank einrichten
# Option 1: Bestehenden Datenbank-Dump importieren (empfohlen)
# Stellen Sie sicher, dass Sie eine Datenbank-Dump-Datei haben (z.B., carambus_api_development_YYYYMMDD_HHMMSS.sql)
# Datenbank erstellen und Dump importieren:
createdb carambus_development
psql -d carambus_development -f /pfad/zu/ihrem/dump.sql

# Option 2: Neue Datenbank erstellen (falls kein Dump verfügbar)
rails db:create
rails db:migrate
rails db:seed

# Server starten
rails server

🔑 Credentials einrichten¶

Wichtig: Du brauchst die development.key und credentials.yml.enc von einem funktionierenden System.

Schritt 1: Lokale Ordner erstellen¶

# Im carambus-Ordner lokale Ordner erstellen
mkdir -p docker-development-api/config/credentials
mkdir -p docker-development-api/database

Schritt 2: Credentials kopieren¶

# Diese Dateien in docker-development-api/config/credentials/ kopieren:
# - development.key
# - credentials.yml.enc

# Beispiel (von einem anderen System):
cp /path/to/working/system/config/credentials/development.key docker-development-api/config/credentials/
cp /path/to/working/system/config/credentials/credentials.yml.enc docker-development-api/config/credentials/

Schritt 3: Datenbank-Dump kopieren¶

# Datenbank-Dump in docker-development-api/database/ kopieren:
cp /path/to/carambus_api_development_dump.sql.gz docker-development-api/database/

Woher bekommen? - Von einem anderen Entwickler im Team - Aus deinem lokalen carambus_api Ordner - Vom Team Lead

🗄️ Datenbank einrichten¶

Option 1: Automatisch über Docker (Empfohlen)¶

# 1. Docker starten - das importiert automatisch alle Dumps!
docker-compose -f docker-compose.development.api-server.yml up --build

# PostgreSQL importiert automatisch alle .sql/.sql.gz Dateien aus:
# ./docker-development-api/database/

Option 2: Manuell über psql (nur wenn PostgreSQL läuft)¶

# Nur wenn der PostgreSQL-Container läuft:
docker ps | grep postgres

# Falls Container läuft, dann:
gunzip -c docker-development-api/database/carambus_api_development_dump.sql.gz | docker exec -i carambus-postgres-1 psql -U www_data -d carambus_api_development

# Falls Container nicht läuft, zuerst Docker starten (Option 1)

Option 3: Mit leerer Datenbank starten¶

# Falls kein Dump vorhanden:
rails db:create
rails db:migrate

🚨 Häufige Probleme & Lösungen¶

GitHub-Zugriff funktioniert nicht¶

# SSH-Key überprüfen
ssh-add -l

# Falls leer, Key hinzufügen:
ssh-add ~/.ssh/id_rsa

# SSH-Verbindung testen
ssh -T git@github.com

Docker läuft nicht¶

# macOS (MacBook):
open -a Docker
# Warten bis "Docker Desktop is running" in der Menüleiste erscheint

# Linux (Server):
sudo systemctl start docker
sudo systemctl status docker

# Windows:
# Docker Desktop über Start-Menü starten

# Dann warten bis Docker läuft, dann:
docker-compose up

Docker-Container startet nicht¶

# Container stoppen und neu starten
docker-compose down
docker-compose up --build

# Falls User-Berechtigungsprobleme:
# Docker-Container läuft als root, nicht als www-data
# Das ist normal für Development-Umgebung

# Logs überprüfen
docker-compose logs web

Ports sind belegt¶

# Ports überprüfen
lsof -i :3000
lsof -i :5432
lsof -i :6379

# Falls belegt, andere Ports verwenden oder Services stoppen

Credentials-Fehler¶

# Entwicklungsschlüssel kopieren
cp /path/to/working/system/config/credentials/development.key config/credentials/
cp /path/to/working/system/config/credentials/credentials.yml.enc config/credentials/

Datenbank-Fehler¶

# Datenbank neu erstellen
rails db:drop
rails db:create
rails db:migrate

# Oder Dump importieren (über psql)
gunzip -c docker-development-api/database/dump.sql.gz | psql -h localhost -p 5433 -U www_data -d carambus_api_development

Hinweis zu Dump-Import-Fehlern: Beim Import eines Datenbank-Dumps können einige Fehler auftreten, die ignoriert werden können: - relation "table_name" already exists - Tabelle existiert bereits - multiple primary keys for table "table_name" are not allowed - Primärschlüssel bereits definiert - relation "index_name" already exists - Index existiert bereits - constraint "constraint_name" for relation "table_name" already exists - Constraint bereits definiert - duplicate key value violates unique constraint - Metadaten bereits gesetzt

Diese Fehler sind normal, wenn die Datenbank bereits teilweise initialisiert wurde.

🔍 Erste Schritte nach dem Setup¶

Server starten: rails server oder Docker
Browser öffnen: http://localhost:3000
Admin-Interface: http://localhost:3000/admin
API testen: http://localhost:3000/api

📚 Nächste Schritte¶

Entwicklerhandbuch lesen
API-Dokumentation studieren
Datenbankdesign verstehen
Mit dem Team sprechen über aktuelle Tasks

🆘 Hilfe benötigt?¶

Team Lead: Gernot Ullrich
Dokumentation: Dieses Repository
Issues: GitHub Issues verwenden
Chat: Team-Chat (Slack/Discord)

Viel Erfolg beim Einstieg! 🎯