MedusaJS: Ein komplettes Setup-Tutorial für den Einstieg

MedusaJS ist ein leistungsstarkes, Open-Source E-Commerce-Framework, das dir die Flexibilität bietet, deinen eigenen Online-Shop zu erstellen. In diesem Tutorial zeige ich dir, wie du MedusaJS von Grund auf einrichtest und deine erste E-Commerce-Anwendung zum Laufen bringst.

Was ist MedusaJS?

MedusaJS ist ein modulares E-Commerce-Framework, das aus einem Node.js-Server und einem Admin-Dashboard besteht. Es bietet dir die Möglichkeit, einen vollständig anpassbaren Online-Shop zu erstellen, ohne dabei auf die Flexibilität verzichten zu müssen. Das Framework ist headless, was bedeutet, dass du dein eigenes Storefront mit deiner bevorzugten Technologie erstellen kannst.

Voraussetzungen

Bevor wir mit der Installation beginnen, stelle sicher, dass du folgende Tools auf deinem System installiert hast:

• Node.js v20+ (LTS Version) - Download
• Git CLI - Download
• PostgreSQL - Download

PostgreSQL Installation prüfen

Um zu überprüfen, ob PostgreSQL installiert ist, führe folgenden Befehl aus:

psql --version

Falls PostgreSQL noch nicht installiert ist, installiere es für dein Betriebssystem. Auf Ubuntu/Debian kannst du es mit folgendem Befehl installieren:

sudo apt-get update
sudo apt-get install postgresql postgresql-contrib

Installation: Der schnelle Weg

Die einfachste Methode, eine Medusa-Anwendung zu erstellen, ist die Verwendung des offiziellen create-medusa-app Tools. Dieses Tool richtet automatisch alles für dich ein, inklusive der Datenbankverbindung.

Schritt 1: Medusa-Anwendung erstellen

Öffne dein Terminal und führe folgenden Befehl aus:

npx create-medusa-app@latest my-medusa-store

Ersetze my-medusa-store mit dem Namen deines Projekts. Der Installer wird dich nach einigen Informationen fragen:

1. Projektname: Der Name deines Projekts (wird auch als Datenbankname verwendet)
2. Next.js Starter Storefront: Möchtest du das vorkonfigurierte Next.js Storefront installieren? (Ja/Nein)

Für den Anfang empfehle ich, mit “Nein” zu beginnen, damit du die Grundlagen der Medusa-Installation verstehst. Du kannst das Storefront später jederzeit hinzufügen.

Schritt 2: Installation abwarten

Der Installationsprozess kann einige Minuten dauern. Das Tool wird:

• Die Medusa-Anwendung in einem Verzeichnis mit deinem Projektnamen installieren
• Eine PostgreSQL-Datenbank für das Projekt einrichten
• Alle notwendigen Abhängigkeiten installieren
• Die Datenbank migrieren

Schritt 3: Erfolgreiche Installation

Nach erfolgreicher Installation sollte:

• Die Medusa-Anwendung auf http://localhost:9000 laufen
• Das Medusa Admin Dashboard auf http://localhost:9000/app verfügbar sein
• Der Installer automatisch das Admin Dashboard in deinem Browser öffnen

Schritt 4: Admin-User initialisieren

Nach dem Setup musst du den Admin-User initialisieren. Dies kannst du entweder über die Web-Oberfläche machen (beim ersten Öffnen des Admin Dashboards) oder über die Kommandozeile.

Option 1: Über die Web-Oberfläche

Beim ersten Öffnen des Admin Dashboards wirst du aufgefordert, einen Admin-Benutzer zu erstellen. Gib die Anmeldedaten ein und klicke auf “Erstellen”.

Option 2: Über die Kommandozeile (manuell)

Alternativ kannst du den Admin-User auch direkt über die Kommandozeile erstellen. Navigiere dazu in das Projektverzeichnis und führe folgenden Befehl aus:

cd my-medusa-store
npx medusa user -e user@email.de -p SuperSecretPassword

Ersetze:

• user@email.de mit deiner gewünschten E-Mail-Adresse
• SuperSecretPassword mit deinem gewünschten Passwort

Wichtig: Der Medusa-Server muss laufen, damit dieser Befehl funktioniert. Stelle sicher, dass der Entwicklungsserver gestartet ist.

Nach erfolgreicher Erstellung des Admin-Users kannst du dich im Admin Dashboard unter http://localhost:9000/app anmelden.

Entwicklungsserver starten

Um den Entwicklungsserver nach der Installation zu starten, navigiere in das Projektverzeichnis und führe folgenden Befehl aus:

cd my-medusa-store
npm run dev

Oder wenn du Yarn verwendest:

yarn dev

Der Server startet auf http://localhost:9000 und das Admin Dashboard ist unter http://localhost:9000/app erreichbar.

Projektstruktur verstehen

Nach der Installation solltest du folgende Verzeichnisstruktur sehen:

my-medusa-store/
├── src/
│   ├── api/          # API-Routen
│   ├── models/       # Datenbankmodelle
│   ├── services/     # Business-Logik
│   └── subscribers/  # Event-Subscriber
├── medusa-config.ts  # Hauptkonfigurationsdatei
├── package.json
└── .env              # Umgebungsvariablen

Wichtige Dateien

• medusa-config.ts: Die Hauptkonfigurationsdatei für deine Medusa-Anwendung
• .env: Enthält sensible Daten wie Datenbankverbindungen und API-Keys
• src/api/: Hier definierst du deine benutzerdefinierten API-Endpunkte

Konfiguration anpassen

CORS-Einstellungen

Wenn du später ein eigenes Storefront entwickelst, musst du die CORS-Einstellungen in der .env Datei anpassen:

STORE_CORS=http://localhost:3000
AUTH_CORS=http://localhost:5173,http://localhost:9000,http://localhost:3000

Füge die URLs deines Storefronts zu STORE_CORS hinzu, damit die Medusa API Anfragen von deinem Storefront akzeptiert.

Datenbankverbindung

Die Datenbankverbindung wird automatisch während der Installation konfiguriert. Du findest die Verbindungsdetails in der .env Datei:

DATABASE_URL=postgres://postgres:postgres@localhost:5432/my-medusa-store

Alternative: Installation mit Docker

Falls du Docker bevorzugst oder Probleme mit der lokalen PostgreSQL-Installation hast, kannst du Medusa auch mit Docker einrichten.

Voraussetzungen für Docker

• Docker
• Docker Compose

Schritt 1: Repository klonen

git clone https://github.com/medusajs/medusa-starter-default.git --depth=1 my-medusa-store
cd my-medusa-store

Schritt 2: Docker Compose erstellen

Erstelle eine docker-compose.yml Datei:

services:
  postgres:
    image: postgres:15-alpine
    container_name: medusa_postgres
    restart: unless-stopped
    environment:
      POSTGRES_DB: medusa-store
      POSTGRES_USER: postgres
      POSTGRES_PASSWORD: postgres
    ports:
      - "5432:5432"
    volumes:
      - postgres_data:/var/lib/postgresql/data
    networks:
      - medusa_network

volumes:
  postgres_data:

networks:
  medusa_network:

Schritt 3: Dependencies installieren

npm install --legacy-peer-deps

Schritt 4: Docker Container starten

docker compose up -d

Schritt 5: Medusa-Konfiguration anpassen

In medusa-config.ts musst du die SSL-Einstellungen für die Datenbankverbindung anpassen:

import { loadEnv, defineConfig } from "@medusajs/framework/utils"

loadEnv(process.env.NODE_ENV || "development", process.cwd())

module.exports = defineConfig({
  projectConfig: {
    // ... andere Konfigurationen
    databaseDriverOptions: {
      ssl: false,
      sslmode: "disable",
    },
  },
})

Schritt 6: Admin-User initialisieren

Nach dem Setup musst du den Admin-User manuell initialisieren. Dies ist notwendig, damit du dich im Admin Dashboard anmelden kannst.

Führe folgenden Befehl aus, um einen Admin-User zu erstellen:

docker compose exec medusa npx medusa user -e user@email.de -p SuperSecretPassword

Ersetze:

• user@email.de mit deiner gewünschten E-Mail-Adresse
• SuperSecretPassword mit deinem gewünschten Passwort

Wichtig: Der Medusa-Container muss laufen, damit dieser Befehl funktioniert. Stelle sicher, dass alle Container gestartet sind (docker compose up -d).

Nach erfolgreicher Erstellung des Admin-Users kannst du dich im Admin Dashboard unter http://localhost:9000/app anmelden.

Erste Schritte im Admin Dashboard

Nachdem du dich im Admin Dashboard angemeldet hast, kannst du:

1. Produkte erstellen: Navigiere zu “Products” und füge dein erstes Produkt hinzu
2. Regionen konfigurieren: Richte Versandregionen und Steuersätze ein
3. Zahlungsmethoden einrichten: Konfiguriere Zahlungsanbieter wie Stripe
4. Versandoptionen: Definiere Versandmethoden für deine Regionen

Häufige Probleme und Lösungen

Problem: Installation schlägt fehl

Lösung: Stelle sicher, dass:

• Node.js v20 oder höher installiert ist
• PostgreSQL läuft und erreichbar ist
• Genügend Festplattenspeicher verfügbar ist

Problem: CORS-Fehler

Lösung: Überprüfe die CORS-Einstellungen in deiner .env Datei und füge die URL deines Storefronts hinzu.

Problem: Datenbankverbindungsfehler

Lösung:

• Überprüfe, ob PostgreSQL läuft: sudo systemctl status postgresql
• Überprüfe die DATABASE_URL in der .env Datei
• Stelle sicher, dass die Datenbank existiert

Problem: Port bereits belegt

Lösung: Ändere den Port in der medusa-config.ts oder beende den Prozess, der den Port verwendet.

Nächste Schritte

Nach erfolgreicher Installation kannst du:

1. Storefront entwickeln: Erstelle dein eigenes Storefront mit Next.js, React oder einer anderen Technologie
2. Plugins installieren: Erweitere Medusa mit offiziellen oder Community-Plugins
3. API anpassen: Passe die API-Endpunkte an deine Bedürfnisse an
4. Custom Services: Erstelle eigene Services für spezielle Business-Logik

Fazit

MedusaJS bietet eine solide Grundlage für dein E-Commerce-Projekt. Mit diesem Setup hast du eine vollständig funktionsfähige Backend-Infrastruktur, die du nach deinen Wünschen anpassen kannst. Die modulare Architektur ermöglicht es dir, genau die Features zu implementieren, die du benötigst, ohne unnötigen Ballast.

Falls du Fragen hast oder auf Probleme stößt, schaue in die offizielle Medusa-Dokumentation oder die Troubleshooting-Guides.

Viel Erfolg mit deinem MedusaJS-Projekt! 🚀