Evolution API deployen (WhatsApp-API)

Einführung

Um Evolution API auf Square Cloud zu entwickeln und zu hosten, ist es wichtig, einer strukturierten Abfolge von Konfigurationen und Voraussetzungen zu folgen. Dieser technische Leitfaden deckt den gesamten Prozess ab, von der anfänglichen Einrichtung bis zum Produktions-Deployment.

Voraussetzungen

Square Cloud Konto: Registriere dich über die Registrierungsseite mit deiner E-Mail-Adresse.
Aktiver Plan: Stellt dedizierte Ressourcen und optimierte Leistung für deine Anwendung sicher. Sieh dir unsere verfügbaren Pläne an und wähle den passendsten für deine Bedürfnisse.

Warum die Evolution API verwenden?

Die Evolution API ist eine Open-Source-API für WhatsApp. Sie verwaltet mehrere WhatsApp-Instanzen an einem Ort, über ihren Web-Manager oder ihre REST-API, und verbindet sie mit Tools wie n8n, Chatwoot und Typebot.

Projekt einrichten

Lade das Projekt aus den Releases von evolutionapi-web herunter, die bereits die für das Deploy auf Square Cloud benötigten Dateien enthalten, oder aus dem offiziellen Repository.

Das offizielle Repository führt typescript in den devDependencies. Square Cloud installiert Abhängigkeiten im Produktionsmodus, ohne devDependencies, daher schlägt der Schritt npm run build fehl. Unser Release verschiebt es bereits nach dependencies; beim offiziellen Repository verschiebst du es selbst.

Die Evolution API liest beim Start eine .env-Datei im Stammverzeichnis des Projekts, diese Datei gehört also in deine ZIP-Datei. Beginne mit der .env aus unserem Release (oder mit .env.example aus dem offiziellen Repository) und passe die Variablen unten an. Variablen, die du im Dashboard unter Umgebungsvariablen festlegst, haben Vorrang vor der .env-Datei; das Dashboard ist daher der bessere Ort für Geheimnisse wie AUTHENTICATION_API_KEY und DATABASE_CONNECTION_URI. Siehe Umgebungsvariablen.

Datenbankkonfiguration

Die Evolution API braucht eine PostgreSQL-Datenbank. Du kannst eine auf Square Cloud hosten, ab dem Standard-Plan: siehe wie du eine verwaltete Datenbank erstellst und verbindest. Lege danach ihre URL in der .env als DATABASE_CONNECTION_URI fest, zusammen mit dem Client-Zertifikat für die PostgreSQL-Verbindung. Hier ein Beispiel für die erforderliche Konfiguration:

.env

DATABASE_PROVIDER=postgresql
DATABASE_CONNECTION_URI='postgresql://squarecloud:password@host:port/database?sslmode=require&sslidentity=path/to/client-identity.p12&sslpassword=p12password'
DATABASE_CONNECTION_CLIENT_NAME='evolution_exchange'
DATABASE_SAVE_DATA_INSTANCE=true
DATABASE_SAVE_DATA_NEW_MESSAGE=true
DATABASE_SAVE_MESSAGE_UPDATE=true
DATABASE_SAVE_DATA_CONTACTS=true
DATABASE_SAVE_DATA_CHATS=true
DATABASE_SAVE_DATA_LABELS=true
DATABASE_SAVE_DATA_HISTORIC=true
DATABASE_SAVE_IS_ON_WHATSAPP=true
DATABASE_SAVE_IS_ON_WHATSAPP_DAYS=7
DATABASE_DELETE_MESSAGE=true

Die Evolution API verbindet sich über Prisma, das das Client-Zertifikat als .p12-Datei erwartet. Lade die Zertifikatsdateien (.crt und .key) von der Seite der Datenbank im Dashboard herunter, konvertiere sie und lege die .p12 in dein Projekt:

openssl pkcs12 -export -out client-identity.p12 -inkey <certificate>.key -in <certificate>.crt

Das Export-Passwort, das du wählst, ist das sslpassword der URL, und sslidentity ist der Pfad zur .p12-Datei. Behalte die .p12 in deiner ZIP-Datei, denn die Anwendung liest sie von der Festplatte. Nachdem die Umgebungsvariable und das Zertifikat festgelegt sind, wende die Migrationen auf deine Datenbank an. Installiere im Projektordner auf deinem Computer die Abhängigkeiten mit npm install (der Befehl braucht die Datei runWithProvider.js) und führe den folgenden Befehl aus:

Windows
Linux

npm run db:deploy:win

npm run db:deploy

Serverkonfiguration

Wie in der Datei .env.example des Repositories gezeigt, lege die Servervariablen fest: SERVER_TYPE, SERVER_PORT, SERVER_URL und die Sprache.

.env

SERVER_NAME=evolution
SERVER_TYPE=http
SERVER_PORT=80
# Your application's URL: https://<subdomain>.squareweb.app, or your custom domain
SERVER_URL="https://my-evolution-api.squareweb.app"
LANGUAGE=en
# Other variables below...

Die Evolution API liest ihren Port aus SERVER_PORT (nicht aus PORT) und fällt ohne diese Variable auf 8080 zurück, behalte also SERVER_PORT=80. Es ist wichtig, einen sicheren globalen API-Schlüssel zu konfigurieren, um unbefugten Zugriff zu vermeiden. Ersetze ihn durch einen eigenen langen Zufallswert: Der Schlüssel in Beispieldateien ist öffentlich.

.env

# Other variables...
AUTHENTICATION_API_KEY=MySuperSecureAPIKEY

Square Cloud konfigurieren

Erstelle eine Datei squarecloud.app im Stammverzeichnis des Projekts. Der START-Befehl erzeugt den Prisma-Client, baut das Projekt und startet es; Installation und Build brauchen etwa 3072 MB RAM:

squarecloud.app

DISPLAY_NAME=Evolution API
RUNTIME=nodejs
START=npx prisma generate --schema prisma/postgresql-schema.prisma && npm run build && npm run start:prod
MEMORY=3072
VERSION=recommended
SUBDOMAIN=my-evolution-api
AUTORESTART=true

SUBDOMAIN muss zur Adresse in SERVER_URL passen. Beim Upload über das Dashboard wählst du “Web Publication”, legst dieselbe Subdomain fest und fügst den START-Befehl als Startbefehl ein.

Deployen

Über das Dashboard

Upload-Seite aufrufen

Rufe die Upload-Seite auf und lade die ZIP-Datei deines Projekts hoch.

Umgebung konfigurieren

Nachdem du deine ZIP-Datei hochgeladen hast, musst du den Namen, die Hauptdatei oder Runtime-Umgebung und weitere Einstellungen für dein Projekt konfigurieren.
Wenn du ein Web-Projekt hochlädst, achte darauf, “Web Publication” auszuwählen und deinem Projekt eine Subdomain zuzuweisen.

Projekt bereitstellen

Klicke abschließend auf die Schaltfläche “Deploy”, um dein Projekt auf Square Cloud zu hosten.
Nach dem Deploy kannst du den Status und die Logs deines Projekts über das Dashboard überwachen.

Anwendung wird auf Square Cloud hochgeladen

Bestätige, dass deine App live ist

Dein erstes Deploy dauert in der Regel weniger als eine Minute. Warte im Dashboard, bis der Status deiner Anwendung als “running” angezeigt wird, und prüfe die Logs auf Startfehler.
Wenn du eine Website oder API bereitgestellt hast, öffne https://<deine-subdomain>.squareweb.app in deinem Browser: du solltest sehen, dass deine Anwendung reagiert. Wenn du einen Bot bereitgestellt hast, sende ihm einen Befehl, um zu bestätigen, dass er online ist.

App startet nicht? Im Leitfaden zur Fehlerbehebung findest du die häufigsten Ursachen und Lösungen.

Über die CLI

Um diese Methode zu nutzen, braucht dein Projekt eine Konfigurationsdatei mit dem Namen squarecloud.app im Stammverzeichnis. Sie teilt Square Cloud mit, wie deine Anwendung ausgeführt wird.

Leitfaden zur Konfigurationsdatei

Erfahre, wie du die Konfigurationsdatei squarecloud.app erstellst, die die Umgebung deiner Anwendung definiert.

CLI installieren

Installiere die Square Cloud CLI. Falls du sie bereits hast, führe denselben Befehl aus, um sie zu aktualisieren:

curl -fsSL https://cli.squarecloud.app/install | bash

npm install -g @squarecloud/cli@latest

Anmelden

Führe den folgenden Befehl aus. Er öffnet deinen Browser: Bestätige dort die Anmeldung, und die CLI ist einsatzbereit. Es gibt keinen API-Schlüssel zu kopieren. Für Skripte und CI siehe CLI-Authentifizierung.

squarecloud auth login

Projekt hochladen

Führe in deinem Projektordner den folgenden Befehl aus. Die CLI packt den aktuellen Ordner als ZIP, lässt dabei weg, was in der squarecloud.ignore steht, und lädt ihn hoch:

squarecloud upload

Um eine selbst erstellte ZIP-Datei hochzuladen, übergib sie mit --file:

squarecloud upload --file <path/to/zip>

Bestätige, dass deine App live ist

Dein erstes Deploy dauert in der Regel weniger als eine Minute. Prüfe den Status und die Logs deiner Anwendung direkt im Terminal:

squarecloud app status
squarecloud app logs

Wenn du eine Website oder API bereitgestellt hast, öffne https://<deine-subdomain>.squareweb.app in deinem Browser: du solltest sehen, dass deine Anwendung reagiert. Wenn du einen Bot bereitgestellt hast, sende ihm einen Befehl, um zu bestätigen, dass er online ist.

App startet nicht? Im Leitfaden zur Fehlerbehebung findest du die häufigsten Ursachen und Lösungen.

Zusätzliche Informationen

Nach dem ersten Start kannst du den RAM auf 1536MB oder 2048MB reduzieren und den Startbefehl auf lediglich Folgendes setzen:

npm run start:prod

Cache-System

Du kannst in der Evolution API ein Cache-System konfigurieren. Dazu benötigst du eine Redis-Datenbank, die du ebenfalls auf Square Cloud hosten kannst.
Um sie zu konfigurieren, musst du außerdem das Zertifikat herunterladen und die URL zur Verbindung festlegen. Beachte das Schema rediss://: Square-Cloud-Datenbanken akzeptieren nur TLS-Verbindungen.

.env

CACHE_REDIS_ENABLED=true
CACHE_REDIS_URI="rediss://default:MySecurePassword@square-cloud-db-ID.squareweb.app:7170"
CACHE_REDIS_TTL=604800
# Prefix serves to differentiate data from one installation to another that are using the same redis
CACHE_REDIS_PREFIX_KEY=evolution
# Enabling this variable will save the connection information in Redis and not in the database.
CACHE_REDIS_SAVE_INSTANCES=false

Fehlerbehebung

Eigene Domain

Um eine eigene Domain (z. B. mysite.com) anstelle der Standard-URL mysite.squareweb.app zu verwenden, benötigst du den Standard-Plan oder höher. Die Standard-URL ergibt sich aus dem Feld SUBDOMAIN in der Konfigurationsdatei. Um deine Domain zu verbinden, folge der Anleitung wie du deine eigene Domain einrichtest.

Mindestanforderungen an den Arbeitsspeicher

Minimum: 512MB RAM für Websites und APIs, genug für einen statischen Build auf der statischen Runtime. Für Apps, die Seiten auf einem Server rendern (Next.js, Nuxt, Angular SSR und ähnliche), empfehlen wir mindestens 1GB RAM. Für größere Anwendungen solltest du mehr RAM zuweisen, damit der Anwendung nicht der Speicher ausgeht und sie abstürzt.

Diese Seite konnte nicht gefunden werden.

Prüfe, ob die Subdomain/Domain mit dem übereinstimmt, was im Feld SUBDOMAIN oder in den Einstellungen der eigenen Domain konfiguriert ist. Wenn du die Seite gerade erst hochgeladen hast, warte bis zu 60 Sekunden, bis Square den ersten Zugriff aktiviert.

Die Seite hat zu lange zum Antworten gebraucht…

Dein Server muss auf Port 80 und Host 0.0.0.0 lauschen. Square Cloud setzt in deiner Anwendung die Umgebungsvariablen PORT (80) und HOST (0.0.0.0): Lies sie in deinem Code aus, statt andere Werte fest einzutragen. Ein Server, der nur auf localhost oder 127.0.0.1 lauscht, erhält nie Anfragen.

Nächste Schritte

Verwaltete Datenbank

Erstelle die PostgreSQL-Datenbank, die die Evolution API braucht.

Datenbank-Verbindungsfehler

Behebe SSL/TLS- und Verbindungsfehler.

WhatsApp-Bot

Baue einen einzelnen WhatsApp-Bot mit whatsapp-web.js oder Baileys.

Kontaktiere uns

Falls du weiterhin technische Schwierigkeiten hast, steht dir unser spezialisiertes Support-Team zur Verfügung. Kontaktiere uns und wir helfen dir gerne, jedes Problem zu lösen: die Qualität unseres Supports ist ein wichtiger Grund, warum Entwickler Square Cloud mit 4,9/5 bei 402 Bewertungen auf Google und Trustpilot bewerten.

Bots

Websites

APIs und Backends

Datenbanken

Selbst gehostete Apps

Anleitungen

Migrationsleitfäden

Evolution API deployen (WhatsApp-API)

Einführung

Voraussetzungen

Warum die Evolution API verwenden?

Projekt einrichten

Datenbankkonfiguration

Serverkonfiguration

Square Cloud konfigurieren

Deployen

Über das Dashboard

Über die CLI

Leitfaden zur Konfigurationsdatei

Zusätzliche Informationen

Cache-System

Fehlerbehebung

Eigene Domain

Mindestanforderungen an den Arbeitsspeicher

Diese Seite konnte nicht gefunden werden.

Die Seite hat zu lange zum Antworten gebraucht…

Nächste Schritte

Verwaltete Datenbank

Datenbank-Verbindungsfehler

WhatsApp-Bot

Kontaktiere uns

​Einführung

​Voraussetzungen

​Warum die Evolution API verwenden?

​Projekt einrichten

​Datenbankkonfiguration

​Serverkonfiguration

​Square Cloud konfigurieren

​Deployen

​Über das Dashboard

​Über die CLI

Leitfaden zur Konfigurationsdatei

​Zusätzliche Informationen

​Cache-System

​Fehlerbehebung

​Eigene Domain

​Mindestanforderungen an den Arbeitsspeicher

​Diese Seite konnte nicht gefunden werden.

​Die Seite hat zu lange zum Antworten gebraucht…

​Nächste Schritte

Verwaltete Datenbank

Datenbank-Verbindungsfehler

WhatsApp-Bot

​Kontaktiere uns

Einführung

Voraussetzungen

Warum die Evolution API verwenden?

Projekt einrichten

Datenbankkonfiguration

Serverkonfiguration

Square Cloud konfigurieren

Deployen

Über das Dashboard

Über die CLI

Zusätzliche Informationen

Cache-System

Fehlerbehebung

Eigene Domain

Mindestanforderungen an den Arbeitsspeicher

Diese Seite konnte nicht gefunden werden.

Die Seite hat zu lange zum Antworten gebraucht…

Nächste Schritte

Kontaktiere uns