Vai al contenuto principale

​
Introduzione

Per sviluppare e ospitare 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 a pagamento 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 crea un modo più semplice per usare molti strumenti in un unico posto, integrando n8n, chatwoot e altri strumenti. Questo progetto ti permette di creare e connetterti rapidamente con un’istanza tramite esso o tramite la sua API, gestendo più istanze di bot in un unico posto.

​
Configurazione del progetto

Per prima cosa, devi ottenere il progetto da una fonte. Puoi ottenerlo dal repository ufficiale o dal nostro repository che ha già i file necessari per il deploy nelle release.

​
Configurazione del database

Per iniziare la configurazione, abbiamo bisogno di un database. Puoi ospitarne uno su Square Cloud se hai il piano Standard o superiore. Dopo averlo creato, dobbiamo impostare nel nostro .env l’URL come DATABASE_CONNECTION_URI e creare il 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
Con la variabile d’ambiente e il certificato impostati, devi applicare le migrazioni sul tuo database. Per farlo, devi avere il file runWithProvider.js all’interno della cartella del progetto ed eseguire il seguente comando: 
npm run db:deploy:win

​
Configurazione del server

Come mostrato nel file .env.example del repository, devi impostare alcune variabili d’ambiente: server_type, server_port, server_url e la lingua.
.env
SERVER_NAME=evolution
SERVER_TYPE=http
SERVER_PORT=80
# Change the SERVER_URL to your actual server URL.
# you change it to your app url, selected when creating the app
# or when set a domain
SERVER_URL="https://my-evolution-api.squareweb.app"
LANGUAGE=en
# Other variables below...
È importante configurare una chiave API globale sicura per evitare accessi non autorizzati.
.env
# Other variables...
AUTHENTICATION_API_KEY=MySuperSecureAPIKEY

​
Deploy

Per fare il deploy su Square Cloud, dovrai solo impostare il comando di avvio e pubblicare sul web. Per installare e compilare, consigliamo di usare 3096MB di RAM.
startup command
npx prisma generate --schema prisma/postgresql-schema.prisma && npm run build && npm run start:prod

​
Tramite dashboard

1

Accedi alla pagina di upload

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

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

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

​
Tramite CLI

Per utilizzare questo metodo, devi creare un file di configurazione chiamato squarecloud.app nella directory principale del tuo progetto. Questo file conterrà la configurazione necessaria per il tuo progetto.

Scopri di più su: come creare il file di configurazione per Square Cloud.

Il file squarecloud.app è un file di configurazione che verrà utilizzato per configurare la tua applicazione; verrà usato per definire il tuo ambiente.
1

Installa la CLI

Per prima cosa, devi avere la CLI installata nel tuo ambiente. Se non la hai ancora, esegui il seguente comando nel tuo terminale:
npm install -g @squarecloud/cli
Se la hai già, ti consigliamo di aggiornarla. Per farlo, esegui il seguente comando nel tuo terminale:
squarecloud update
2

Autenticati

Ora, per autenticarti e utilizzare gli altri comandi della CLI, troverai la tua chiave di autorizzazione qui cliccando su “Request API Key”. Dopo aver ottenuto la tua chiave di autorizzazione, esegui il seguente comando:
squarecloud auth login
3

Carica il tuo progetto

Infine, per eseguire il deploy della tua applicazione su Square Cloud tramite la CLI, devi eseguire il seguente comando:
squarecloud upload
Oppure, se hai creato lo zip manualmente, puoi usare:
squarecloud upload --file <path/to/zip>

​
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.
.env
CACHE_REDIS_ENABLED=true
CACHE_REDIS_URI="redis://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. Il sottodominio è definito dal campo SUBDOMAIN nel file di configurazione.

​
Requisiti minimi di RAM

Minimo: 512MB di RAM per siti web/API semplici. Per siti con framework (Next.JS, React, Vue, Angular, ecc.), consigliamo sempre 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…

Verifica di aver configurato correttamente la porta 80 e l’host 0.0.0.0 nell’applicazione. Consigliamo di utilizzare le variabili d’ambiente forzate di Square: PORT e HOST dal file .env.

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