Déployer Evolution API (API WhatsApp)

Introduction

Pour développer et héberger Evolution API sur Square Cloud, il est essentiel de suivre une séquence structurée de configurations et de prérequis. Ce guide technique couvrira l’ensemble du processus, de la configuration initiale au déploiement en production.

Prérequis

Compte Square Cloud : Inscrivez-vous via la page d’inscription en utilisant votre adresse e-mail.
Plan actif : Garantit des ressources dédiées et des performances optimisées pour votre application. Consultez nos plans disponibles et choisissez celui qui convient le mieux à vos besoins.

Evolution API est une API open source pour WhatsApp. Elle gère plusieurs instances WhatsApp au même endroit, via son gestionnaire web ou son API REST, et les connecte à des outils comme n8n, Chatwoot et Typebot. Ce guide utilise le runtime Node.js.

Obtenir le projet

Téléchargez le projet depuis nos releases evolutionapi-web, qui contiennent déjà les fichiers nécessaires au déploiement sur Square Cloud, ou depuis le dépôt officiel.

Le dépôt officiel liste typescript dans les devDependencies. Square Cloud installe les dépendances en mode production, sans les devDependencies, donc l’étape npm run build échoue. Notre release le déplace déjà dans dependencies ; avec le dépôt officiel, déplacez-le vous-même.

Configurer Evolution API

Evolution API lit un fichier .env à la racine du projet au démarrage : ce fichier va donc dans votre ZIP. Partez du .env de notre release (ou du .env.example du dépôt officiel) et modifiez les variables ci-dessous. Les variables définies dans les Variables d’environnement du tableau de bord ont la priorité sur le fichier .env, ce qui fait du tableau de bord le meilleur endroit pour les secrets comme AUTHENTICATION_API_KEY et DATABASE_CONNECTION_URI. Consultez Variables d’environnement.

Base de données

Evolution API a besoin d’une base de données PostgreSQL. Vous pouvez en héberger une sur Square Cloud avec le plan Standard ou supérieur : consultez comment créer et connecter une base de données gérée. Après sa création, définissez son URL dans le .env sous DATABASE_CONNECTION_URI, avec le certificat client pour la connexion PostgreSQL. Voici un exemple de la configuration nécessaire :

.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

Evolution API se connecte via Prisma, qui attend le certificat client sous forme de fichier .p12. Téléchargez les fichiers du certificat (.crt et .key) depuis la page de la base de données dans le tableau de bord, convertissez-les et placez le .p12 dans votre projet :

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

Le mot de passe d’export que vous choisissez est le sslpassword de l’URL, et sslidentity est le chemin du fichier .p12. Gardez le .p12 dans votre ZIP, car l’application le lit sur le disque.

Appliquer les migrations

Une fois la variable d’environnement et le certificat définis, appliquez les migrations sur votre base de données. Depuis le dossier du projet sur votre ordinateur, installez les dépendances avec npm install (il a besoin du fichier runWithProvider.js) et exécutez la commande suivante :

Windows
Linux

npm run db:deploy:win

npm run db:deploy

Vous mettez à jour depuis une version précédente ? Exécutez à nouveau la même commande avant d’envoyer les nouveaux fichiers, car les nouvelles versions peuvent apporter de nouvelles migrations.

Serveur

Comme indiqué dans le fichier .env.example du dépôt, définissez les variables du serveur : SERVER_TYPE, SERVER_PORT, SERVER_URL et la langue.

.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...

Evolution API lit son port dans SERVER_PORT (et non dans PORT) et utilise 8080 par défaut s’il est absent : conservez donc SERVER_PORT=80.

Clé d’API globale

Il est important de configurer une clé d’API globale sécurisée pour éviter tout accès non autorisé. Remplacez-la par une longue valeur aléatoire qui vous est propre : la clé des fichiers d’exemple est publique.

.env

# Other variables...
AUTHENTICATION_API_KEY=MySuperSecureAPIKEY

Cache Redis (optionnel)

Vous pouvez configurer un système de cache dans Evolution API. Pour ce faire, vous aurez besoin d’une base de données Redis, que vous pouvez également héberger sur Square Cloud.
Pour la configurer, vous devrez également télécharger le certificat et définir l’URL de connexion. Notez le schéma rediss:// : les bases de données Square Cloud n’acceptent que les connexions TLS.

.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

Configurer Square Cloud

Créez un fichier squarecloud.app à la racine du projet. La commande START génère le client Prisma, compile le projet et le démarre ; l’installation et la compilation nécessitent environ 3072 Mo de 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 doit correspondre à l’adresse de SERVER_URL. Lors d’un envoi depuis le tableau de bord, sélectionnez « Publication Web », définissez le même sous-domaine et collez la commande START comme commande de démarrage.

Contenu du ZIP

Le dossier complet du projet : package.json, runWithProvider.js, src/, prisma/ et les autres fichiers de la release ou du dépôt.
.env, avec les variables ci-dessus.
Le certificat client .p12.
squarecloud.app.

Excluez node_modules/, que npm install a créé pour les migrations : Square Cloud installe les dépendances sur le serveur.

Déployer et vérifier

Via le tableau de bord

Accéder à la page d'upload

Accédez à la page d’upload et téléversez le fichier zip de votre projet.

Configurer votre environnement

Après avoir téléversé votre zip, vous devrez configurer le nom, le fichier principal ou l’environnement d’exécution ainsi que d’autres paramètres de votre projet.
Si vous téléversez un projet web, veillez à sélectionner « Publication Web » et à définir un sous-domaine pour votre projet.

Déployer votre projet

Enfin, cliquez sur le bouton « Deploy » pour héberger votre projet sur Square Cloud.
Une fois le déploiement effectué, vous pouvez suivre l’état et les logs de votre projet depuis le tableau de bord.

Téléversement d'une application vers Square Cloud

Confirmez que votre application est en ligne

Votre premier déploiement prend généralement moins d’une minute. Dans le tableau de bord, attendez que le statut de votre application affiche « en cours d’exécution » et vérifiez les logs pour détecter d’éventuelles erreurs de démarrage.
Si vous avez déployé un site web ou une API, ouvrez https://<votre-sous-domaine>.squareweb.app dans votre navigateur, vous devriez voir votre application répondre. Si vous avez déployé un bot, envoyez-lui une commande pour confirmer qu’il est en ligne.

Votre application ne démarre pas ? Consultez le guide de dépannage pour les causes les plus courantes et leurs solutions.

Via la CLI

Pour utiliser cette méthode, votre projet a besoin d’un fichier de configuration nommé squarecloud.app à sa racine. Il indique à Square Cloud comment exécuter votre application.

Guide du fichier de configuration

Apprenez comment créer le fichier de configuration squarecloud.app qui définit l’environnement de votre application.

Installer la CLI

Installez la CLI Square Cloud. Si vous l’avez déjà, exécutez la même commande pour la mettre à jour :

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

npm install -g @squarecloud/cli@latest

Se connecter

Exécutez la commande ci-dessous. Elle ouvre votre navigateur : approuvez-y la connexion et la CLI est prête. Il n’y a aucune clé API à copier. Pour les scripts et la CI, consultez Authentification de la CLI.

squarecloud auth login

Téléverser votre projet

Depuis le dossier de votre projet, exécutez la commande ci-dessous. La CLI compresse le dossier courant en zip, sans ce que liste squarecloud.ignore, puis l’envoie :

squarecloud upload

Pour téléverser un zip que vous avez créé vous-même, passez-le avec --file :

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

Confirmez que votre application est en ligne

Votre premier déploiement prend généralement moins d’une minute. Vérifiez le statut et les logs de votre application directement depuis le terminal :

squarecloud app status
squarecloud app logs

Si vous avez déployé un site web ou une API, ouvrez https://<votre-sous-domaine>.squareweb.app dans votre navigateur, vous devriez voir votre application répondre. Si vous avez déployé un bot, envoyez-lui une commande pour confirmer qu’il est en ligne.

Votre application ne démarre pas ? Consultez le guide de dépannage pour les causes les plus courantes et leurs solutions.

Réduire la RAM après la première exécution

Après la première exécution, vous pouvez réduire la RAM à 1536 Mo ou 2048 Mo et définir la commande de démarrage uniquement sur :

npm run start:prod

Premier accès

Ouvrez https://my-evolution-api.squareweb.app/manager pour accéder au gestionnaire web. Connectez-vous avec votre SERVER_URL comme URL du serveur et votre AUTHENTICATION_API_KEY comme clé d’API globale, puis créez votre première instance WhatsApp.

Erreurs courantes

Domaine personnalisé

Pour utiliser un domaine personnalisé (par exemple mysite.com) au lieu de l’URL par défaut mysite.squareweb.app, vous avez besoin du plan Standard ou supérieur. L’URL par défaut provient du champ SUBDOMAIN du fichier de configuration. Pour connecter votre domaine, suivez comment configurer votre propre domaine.

Prérequis minimum en RAM

Minimum : 512 Mo de RAM pour les sites web et les API, ce qui suffit pour un build statique sur le runtime statique. Pour les applications qui génèrent les pages sur un serveur (Next.js, Nuxt, Angular SSR et similaires), nous recommandons au moins 1 Go de RAM. Pour les applications plus volumineuses, allouez davantage de RAM afin d’éviter que l’application ne manque de mémoire et ne plante.

Impossible de trouver ce site.

Vérifiez que le sous-domaine/domaine correspond à ce qui est configuré dans le champ SUBDOMAIN ou dans les paramètres du domaine personnalisé. Si vous venez tout juste de mettre en ligne le site, patientez jusqu’à 60 secondes pour que Square active le premier accès.

Le site a mis trop de temps à répondre…

Votre serveur doit écouter sur le port 80 et l’hôte 0.0.0.0. Square Cloud définit les variables d’environnement PORT (80) et HOST (0.0.0.0) dans votre application : lisez-les dans votre code au lieu de coder en dur d’autres valeurs. Un serveur qui n’écoute que sur localhost ou 127.0.0.1 ne reçoit jamais de requêtes.

Evolution API ne parvient pas à se connecter à la base de données

Vérifiez que sslidentity pointe vers le fichier .p12 présent dans votre ZIP et que sslpassword est le mot de passe d’export que vous avez choisi. Pour les autres erreurs SSL/TLS, consultez les erreurs de connexion à la base de données.

Prochaines étapes

Base de données gérée

Créez la base de données PostgreSQL dont Evolution API a besoin.

Erreurs de connexion à la base de données

Corrigez les erreurs SSL/TLS et de connexion.

Bot WhatsApp

Créez un bot WhatsApp unique avec whatsapp-web.js ou Baileys.

Contactez-nous

Si vous rencontrez toujours des difficultés techniques, notre équipe de support spécialisée est disponible pour vous aider. Contactez-nous et nous serons ravis de vous aider à résoudre tout problème. La qualité du support compte pour beaucoup dans la note que les développeurs donnent à Square Cloud, 4,9/5 sur 402 avis sur Google et Trustpilot.

Bots

Sites web

API et backends

Bases de données

Applications auto-hébergées

Guides

Guides de migration

Déployer Evolution API (API WhatsApp)

Introduction

Prérequis

Obtenir le projet

Configurer Evolution API

Base de données

Appliquer les migrations

Serveur

Clé d’API globale

Cache Redis (optionnel)

Configurer Square Cloud

Contenu du ZIP

Déployer et vérifier

Via le tableau de bord

Via la CLI

Guide du fichier de configuration

Réduire la RAM après la première exécution

Premier accès

Erreurs courantes

Domaine personnalisé

Prérequis minimum en RAM

Impossible de trouver ce site.

Le site a mis trop de temps à répondre…

Evolution API ne parvient pas à se connecter à la base de données

Prochaines étapes

Base de données gérée

Erreurs de connexion à la base de données

Bot WhatsApp

Contactez-nous

​Introduction

​Prérequis

​Obtenir le projet

​Configurer Evolution API

​Base de données

​Appliquer les migrations

​Serveur

​Clé d’API globale

​Cache Redis (optionnel)

​Configurer Square Cloud

​Contenu du ZIP

​Déployer et vérifier

​Via le tableau de bord

​Via la CLI

Guide du fichier de configuration

​Réduire la RAM après la première exécution

​Premier accès

​Erreurs courantes

​Domaine personnalisé

​Prérequis minimum en RAM

​Impossible de trouver ce site.

​Le site a mis trop de temps à répondre…

​Evolution API ne parvient pas à se connecter à la base de données

​Prochaines étapes

Base de données gérée

Erreurs de connexion à la base de données

Bot WhatsApp

​Contactez-nous

Introduction

Prérequis

Obtenir le projet

Configurer Evolution API

Base de données

Appliquer les migrations

Serveur

Clé d’API globale

Cache Redis (optionnel)

Configurer Square Cloud

Contenu du ZIP

Déployer et vérifier

Via le tableau de bord

Via la CLI

Réduire la RAM après la première exécution

Premier accès

Erreurs courantes

Domaine personnalisé

Prérequis minimum en RAM

Impossible de trouver ce site.

Le site a mis trop de temps à répondre…

Evolution API ne parvient pas à se connecter à la base de données

Prochaines étapes

Contactez-nous