Deploy di Evolution API (API WhatsApp)

Introduzione

Per sviluppare e ospitare Evolution API su Square Cloud, è essenziale seguire una sequenza strutturata di configurazioni e prerequisiti. Questa guida tecnica coprirà l’intero processo, dalla configurazione iniziale al deploy in produzione.

Prerequisiti

Account Square Cloud: Registrati tramite la pagina di registrazione usando la tua email.
Piano attivo: Garantisce risorse dedicate e prestazioni ottimizzate per la tua applicazione. Consulta i nostri piani disponibili e scegli quello più adatto alle tue esigenze.

Perché usare Evolution API?

Evolution API è un’API open source per WhatsApp. Gestisce più istanze WhatsApp in un unico posto, tramite il suo manager web o la sua API REST, e le collega a strumenti come n8n, Chatwoot e Typebot.

Configurazione del progetto

Scarica il progetto dalle release di evolutionapi-web, che contengono già i file necessari per il deploy su Square Cloud, oppure dal repository ufficiale.

Il repository ufficiale elenca typescript tra le devDependencies. Square Cloud installa le dipendenze in modalità produzione, senza devDependencies, quindi il passaggio npm run build fallisce. La nostra release lo sposta già in dependencies; con il repository ufficiale, spostalo tu.

Evolution API legge un file .env nella radice del progetto all’avvio, quindi questo file va nel tuo ZIP. Parti dal .env della nostra release (o da .env.example nel repository ufficiale) e modifica le variabili qui sotto. Le variabili impostate in Environment Variables nella dashboard hanno la precedenza sul file .env, il che rende la dashboard il posto migliore per i segreti come AUTHENTICATION_API_KEY e DATABASE_CONNECTION_URI. Consulta Variabili d’ambiente.

Configurazione del database

Evolution API ha bisogno di un database PostgreSQL. Puoi ospitarne uno su Square Cloud con il piano Standard o superiore: consulta come creare e connettere un database gestito. Dopo averlo creato, imposta il suo URL nel .env come DATABASE_CONNECTION_URI, insieme al certificato client per la connessione PostgreSQL. Ecco un esempio della configurazione necessaria:

.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 si connette tramite Prisma, che si aspetta il certificato client come file .p12. Scarica i file del certificato (.crt e .key) dalla pagina del database nella dashboard, convertili e metti il .p12 nel tuo progetto:

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

La password di esportazione che scegli è la sslpassword dell’URL, e sslidentity è il percorso del file .p12. Tieni il .p12 nel tuo ZIP, perché l’applicazione lo legge dal disco. Con la variabile d’ambiente e il certificato impostati, applica le migrazioni al tuo database. Dalla cartella del progetto sul tuo computer, installa le dipendenze con npm install (serve il file runWithProvider.js) ed esegui il seguente comando:

Windows
Linux

npm run db:deploy:win

npm run db:deploy

Configurazione del server

Come mostrato nel file .env.example del repository, imposta le variabili del server: SERVER_TYPE, SERVER_PORT, SERVER_URL e la lingua.

.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 legge la porta da SERVER_PORT (non da PORT) e senza di essa usa 8080, quindi mantieni SERVER_PORT=80. È importante configurare una chiave API globale sicura per evitare accessi non autorizzati. Sostituiscila con un tuo valore casuale e lungo: la chiave dei file di esempio è pubblica.

.env

# Other variables...
AUTHENTICATION_API_KEY=MySuperSecureAPIKEY

Configurare Square Cloud

Crea un file squarecloud.app nella radice del progetto. Il comando START genera il client Prisma, esegue la build del progetto e lo avvia; installazione e build richiedono circa 3072 MB di 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 deve corrispondere all’indirizzo in SERVER_URL. Quando carichi dalla dashboard, seleziona “Web Publication”, imposta lo stesso sottodominio e incolla il comando START come comando di avvio.

Deploy

Tramite dashboard

Accedi alla pagina di upload

Accedi alla pagina di upload e carica il file zip del tuo progetto.

Configura il tuo ambiente

Dopo aver caricato il tuo zip, dovrai configurare il nome, il file principale o il runtime environment e altre impostazioni per il tuo progetto.
Se stai caricando un progetto web, assicurati di selezionare “Web Publication” e di impostare un sottodominio per il tuo progetto.

Esegui il deploy del tuo progetto

Infine, clicca sul pulsante “Deploy” per ospitare il tuo progetto su Square Cloud.
Dopo il deploy, puoi monitorare lo stato e i log del tuo progetto dalla dashboard.

Caricamento dell'applicazione su Square Cloud

Conferma che la tua app sia online

Il primo deploy richiede di solito meno di un minuto. Nella dashboard, attendi che lo stato della tua applicazione mostri “in esecuzione” e controlla i log per eventuali errori di avvio.
Se hai fatto il deploy di un sito web o di un’API, apri https://<tuo-sottodominio>.squareweb.app nel tuo browser: dovresti vedere la tua applicazione rispondere. Se hai fatto il deploy di un bot, invia un comando per confermare che sia online.

La tua app non si avvia? Consulta la guida alla risoluzione dei problemi per le cause più comuni e le relative soluzioni.

Tramite CLI

Per utilizzare questo metodo, il tuo progetto deve avere un file di configurazione chiamato squarecloud.app nella sua radice. Indica a Square Cloud come eseguire la tua applicazione.

Guida al file di configurazione

Scopri come creare il file di configurazione squarecloud.app che definisce l’ambiente della tua applicazione.

Installa la CLI

Installa la CLI di Square Cloud. Se ce l’hai già, esegui lo stesso comando per aggiornarla:

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

npm install -g @squarecloud/cli@latest

Accedi

Esegui il comando qui sotto. Apre il tuo browser: approva l’accesso lì e la CLI è pronta. Non c’è nessuna chiave API da copiare. Per script e CI, consulta Autenticazione della CLI.

squarecloud auth login

Carica il tuo progetto

Dalla cartella del tuo progetto, esegui il comando qui sotto. La CLI comprime la cartella corrente, escludendo ciò che elenca squarecloud.ignore, e la carica:

squarecloud upload

Per caricare uno zip che hai creato tu, passalo con --file:

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

Conferma che la tua app sia online

Il primo deploy richiede di solito meno di un minuto. Controlla lo stato e i log della tua applicazione direttamente dal terminale:

squarecloud app status
squarecloud app logs

Se hai fatto il deploy di un sito web o di un’API, apri https://<tuo-sottodominio>.squareweb.app nel tuo browser: dovresti vedere la tua applicazione rispondere. Se hai fatto il deploy di un bot, invia un comando per confermare che sia online.

La tua app non si avvia? Consulta la guida alla risoluzione dei problemi per le cause più comuni e le relative soluzioni.

Informazioni aggiuntive

Dopo la prima esecuzione, puoi ridurre la RAM a 1536MB o 2048MB e impostare il comando di avvio solo a:

npm run start:prod

Sistema di cache

Puoi configurare un sistema di cache in Evolution API. Per farlo, avrai bisogno di un database Redis che puoi anch’esso ospitare su Square Cloud.
Per configurarlo, dovrai anche scaricare il certificato e impostare l’URL per la connessione. Nota lo schema rediss://: i database di Square Cloud accettano solo connessioni 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

Risoluzione dei problemi

Dominio personalizzato

Per utilizzare un dominio personalizzato (ad esempio, mysite.com) invece dell’URL predefinito mysite.squareweb.app, hai bisogno del piano Standard o superiore. L’URL predefinito deriva dal campo SUBDOMAIN nel file di configurazione. Per collegare il tuo dominio, segui come configurare il tuo dominio.

Requisiti minimi di RAM

Minimo: 512MB di RAM per siti web e API, sufficienti per una build statica sul runtime statico. Per le app che generano le pagine su un server (Next.js, Nuxt, Angular SSR e simili), consigliamo almeno 1GB di RAM. Per applicazioni più grandi, alloca più RAM per evitare che l’applicazione esaurisca la memoria e si arresti in modo anomalo.

Impossibile trovare questo sito.

Verifica che il sottodominio/dominio corrisponda a quanto configurato nel campo SUBDOMAIN o nelle impostazioni del dominio personalizzato. Se hai appena caricato il sito, attendi fino a 60 secondi affinché Square abiliti il primo accesso.

Il sito ha impiegato troppo tempo per rispondere…

Il tuo server deve ascoltare sulla porta 80 e sull’host 0.0.0.0. Square Cloud imposta le variabili d’ambiente PORT (80) e HOST (0.0.0.0) nella tua applicazione: leggile nel codice invece di scrivere altri valori fissi. Un server che ascolta solo su localhost o 127.0.0.1 non riceve mai richieste.

Prossimi passi

Database gestito

Crea il database PostgreSQL di cui ha bisogno Evolution API.

Errori di connessione al database

Risolvi gli errori SSL/TLS e di connessione.

Bot WhatsApp

Crea un singolo bot WhatsApp con whatsapp-web.js o Baileys.

Contattaci

Se continui a riscontrare difficoltà tecniche, il nostro team di supporto specializzato è disponibile ad assisterti. Contattaci e saremo felici di aiutarti a risolvere qualsiasi problema: la qualità del supporto è una parte importante del motivo per cui gli sviluppatori valutano Square Cloud 4,9/5 su 402 recensioni su Google e Trustpilot.

Bots

Siti web

API e backend

Database

App self-hosted

Guide

Guide alla migrazione

Deploy di Evolution API (API WhatsApp)

Introduzione

Prerequisiti

Perché usare Evolution API?

Configurazione del progetto

Configurazione del database

Configurazione del server

Configurare Square Cloud

Deploy

Tramite dashboard

Tramite CLI

Guida al file di configurazione

Informazioni aggiuntive

Sistema di cache

Risoluzione dei problemi

Dominio personalizzato

Requisiti minimi di RAM

Impossibile trovare questo sito.

Il sito ha impiegato troppo tempo per rispondere…

Prossimi passi

Database gestito

Errori di connessione al database

Bot WhatsApp

Contattaci

​Introduzione

​Prerequisiti

​Perché usare Evolution API?

​Configurazione del progetto

​Configurazione del database

​Configurazione del server

​Configurare Square Cloud

​Deploy

​Tramite dashboard

​Tramite CLI

Guida al file di configurazione

​Informazioni aggiuntive

​Sistema di cache

​Risoluzione dei problemi

​Dominio personalizzato

​Requisiti minimi di RAM

​Impossibile trovare questo sito.

​Il sito ha impiegato troppo tempo per rispondere…

​Prossimi passi

Database gestito

Errori di connessione al database

Bot WhatsApp

​Contattaci

Introduzione

Prerequisiti

Perché usare Evolution API?

Configurazione del progetto

Configurazione del database

Configurazione del server

Configurare Square Cloud

Deploy

Tramite dashboard

Tramite CLI

Informazioni aggiuntive

Sistema di cache

Risoluzione dei problemi

Dominio personalizzato

Requisiti minimi di RAM

Impossibile trovare questo sito.

Il sito ha impiegato troppo tempo per rispondere…

Prossimi passi

Contattaci