Installazione

Questa pagina La accompagna dall'acquisto fino a un telefono associato che invia il suo primo SMS. Non presuppone alcuna conoscenza del prodotto. Calcoli circa un quarto d'ora, metà del quale per i download.

L'installazione sta in un solo comando. Uno script installa Docker se manca, scarica i file dell'ultima versione, verifica che non siano stati alterati, scrive la configurazione, avvia il gateway e installa un comando di gestione, sms-gateway. Non c'è nulla da compilare né alcun indirizzo di server da digitare.

Che cosa installa

Il gateway è un solo programma, che ascolta su una sola porta e conserva tutto in una sola cartella di dati (un volume Docker). Gira in un container Docker, sulla Sua macchina.

Conseguenza pratica: fare il backup della cartella di dati significa fare il backup dell'intera installazione, e spostarla significa spostare il gateway (veda Backup e ripristino e Migrare su un altro server).

Che cosa serve

Sulla Sua macchina non si compila nulla: il gateway è pubblicato pronto all'uso per processori amd64 e arm64, e Docker sceglie quello giusto. Basta una macchina piccola: il gateway usa pochissima memoria, e il piano più piccolo della maggior parte dei provider è sufficiente per iniziare.

Il percorso in cinque passi

Passo 1: crei il Suo account e acquisti

Vada su sms-gateway.araylab.com. Il pulsante Acquista la licenza Le chiede prima di accedere: inserisca il Suo indirizzo e-mail e riceverà un link di accesso. Nessuna password da ricordare. Arriva nella Sua area clienti, per ora vuota.

Il pagamento è gestito da Gumroad, che emette anche la fattura e si occupa dell'IVA. In Madagascar, il pagamento tramite Mobile Money (MVola, Orange Money, Airtel Money) viene convalidato a mano: la licenza compare dopo questa convalida, non immediatamente.

Una volta confermato il pagamento, riceve un'e-mail che annuncia che la licenza è pronta. Per la Sua sicurezza, quell'e-mail non contiene la chiave: La rimanda alla Sua area clienti.

Passo 2: copi la Sua chiave di licenza

Nell'area clienti, la licenza mostra la sua chiave, nel formato XXXX-XXXX-XXXX-XXXX, con un pulsante per copiarla. Lì compaiono anche le istruzioni di installazione e il link per scaricare l'app Android, non appena la licenza è attiva.

Può tornare in qualsiasi momento per visualizzare di nuovo la chiave, e rigenerarla se è trapelata (veda Rigenerare la chiave).

Passo 3: esegua il comando di installazione

Sulla macchina che ospiterà il gateway, in un terminale.

Linux (VPS, Oracle Cloud, server locale, Raspberry Pi):

curl -fsSL https://sms-gateway.araylab.com/install.sh | sudo bash

Senza opzioni, lo script Le pone due domande: se può installare Docker nel caso manchi, e se i Suoi telefoni raggiungeranno il gateway tramite un nome di dominio o sulla rete locale (veda Scegliere la modalità). Per rispondere a tutto in anticipo:

# Con un nome di dominio: HTTPS automatico (consigliato)
curl -fsSL https://sms-gateway.araylab.com/install.sh | sudo bash -s -- --domain sms.example.com --yes

# Sulla rete locale, senza nome di dominio
curl -fsSL https://sms-gateway.araylab.com/install.sh | sudo bash -s -- --lan --yes

macOS: lo stesso comando, con Docker Desktop installato e avviato in precedenza. L'installazione va in ~/sms-gateway, e il comando sms-gateway viene posto in quella cartella.

Windows (Docker Desktop obbligatorio), in PowerShell aperto come amministratore:

irm https://sms-gateway.araylab.com/install.ps1 | iex

Su Windows, lo script non chiede la modalità: installa in modalità rete locale per impostazione predefinita. Per cambiarla, imposti queste variabili nella stessa finestra di PowerShell prima di eseguire il comando:

$env:SMSGW_DOMAIN = "sms.example.com"
irm https://sms-gateway.araylab.com/install.ps1 | iex

Se Docker Desktop manca, lo script per Windows propone di installarlo con winget, poi si ferma e Le chiede di riavviare Windows, avviare Docker Desktop una volta e rieseguire il comando. Installa in %ProgramData%\SmsGateway, apre la porta 8080 nel firewall di Windows per le reti private in modalità rete locale, poi apre la dashboard nel Suo browser.

Alla fine, ogni script mostra l'indirizzo della dashboard e il codice di installazione che serve a creare l'account amministratore (passo 4). Su Linux e macOS, sms-gateway url mostra di nuovo l'indirizzo e sms-gateway setup-code mostra il codice, finché non esiste alcun account.

Preferisce leggere prima lo script? Passare direttamente a bash uno script scaricato significa fidarsi di esso. Può scaricarlo, leggerlo e poi eseguirlo:

curl -fsSL https://sms-gateway.araylab.com/install.sh -o install.sh
less install.sh
sudo bash install.sh --domain sms.example.com

Lo script, dal canto suo, verifica tutto ciò che scarica in seguito con un checksum SHA-256 pubblicato: un file che non corrisponde interrompe l'installazione prima che venga installato qualsiasi cosa.

Che cosa fa lo script, in ordine

1. Verifica di essere eseguito come root su una macchina Linux amd64 o arm64 (o su macOS).
2. Installa Docker se manca, tramite lo script ufficiale di Docker, dopo averglielo chiesto (o senza chiedere con --yes).
3. Cerca l'ultima versione pubblicata (o quella indicata con --version), ne scarica i file e ne verifica il checksum.
4. Chiede la modalità se nessuna opzione l'ha impostata. In modalità dominio, verifica che il dominio punti a questa macchina e che le porte 80 e 443 siano libere. Un problema produce un avviso e una domanda, non un arresto definitivo: può correggere il DNS in seguito.
5. In modalità rete locale, installa avahi-daemon, che rende risolvibile il nome <nome-macchina>.local sulla Sua rete.
6. Scrive la configurazione in /opt/sms-gateway/.env, leggibile solo da root. Una configurazione esistente viene conservata: rieseguire il comando aggiorna il gateway senza cancellare le Sue impostazioni.
7. Scarica il gateway, lo avvia e attende che risponda (al massimo due minuti).
8. Installa il comando sms-gateway e mostra l'indirizzo della dashboard, il codice di installazione e i passi successivi.

Le opzioni (Linux e macOS)

Come interagiscono le opzioni:

• Senza --domain né --lan, lo script chiede. Con --yes e nessuna modalità a una prima installazione, si ferma: non esiste una modalità predefinita, perché quella sbagliata produce telefoni che non si collegano mai.
• Rieseguendolo su un'installazione esistente, la modalità e la porta già registrate vengono conservate. Indicare di nuovo --domain o --lan cambia la modalità: l'indirizzo pubblico cambia, e i telefoni già associati devono essere associati di nuovo.
• --port è considerata solo alla prima installazione. In seguito prevale la porta registrata nella configurazione; modifichi invece GATEWAY_PORT nel file .env (veda Impostazioni modificabili).
• --yes risponde sì anche agli avvisi. In modalità dominio, un'installazione con un DNS errato o con le porte 80/443 occupate prosegue comunque: il gateway funziona, ma l'HTTPS no, finché non corregge la causa.

Passo 4: apra la dashboard, crei l'amministratore, incolli la chiave

Apra l'indirizzo mostrato dallo script. Un'installazione nuova apre la schermata Creare il primo account: Token di installazione, nome, indirizzo e-mail, password. La password deve essere lunga almeno 12 caratteri. Questo primo account è il superamministratore, e la schermata che lo crea si chiude definitivamente non appena esiste un account.

Il token di installazione è il codice di installazione mostrato alla fine dello script. Dimostra che chi crea l'account ha accesso alla macchina: senza di esso, il primo sconosciuto che trovasse su internet un gateway appena installato potrebbe diventarne l'amministratore. Se non lo ha più sotto mano:

Il codice scompare non appena l'account è creato: i comandi qui sopra rispondono allora che non ne resta nessuno, ed è normale.

Creare l'account non apre la sessione: la schermata conferma la creazione, poi La porta alla schermata di accesso, dove digita l'indirizzo e-mail e la password appena scelti.

Una volta effettuato l'accesso, compare una finestra Attivare questo gateway. Incolli la chiave copiata al passo 2. Spazi, trattini e minuscole sono accettati. Non c'è nient'altro da digitare: il gateway sa già come raggiungere il nostro server delle licenze.

Se in quel momento il nostro server non risponde, la finestra indica Il nostro server non risponde. La Sua chiave viene comunque registrata e nulla viene sospeso: il gateway invia normalmente e riprova l'attivazione da solo. Un guasto da parte nostra non viene mai trattato come una licenza non valida. Dettagli in Licenza.

Passo 5: installi l'app Android e associ il telefono

1. Scarichi l'app dalla Sua area clienti, sul telefono stesso oppure su un computer e poi la copi. L'app non è sul Play Store: il link viene dato solo ai titolari di una licenza.
2. La installi. Android Le chiede di autorizzare l'installazione dalla fonte utilizzata (browser o gestore di file). La autorizzi per questa installazione.
3. Nella dashboard, apra Dispositivi e faccia clic su Associa un dispositivo. Compare un codice QR, con un codice alternativo per un telefono la cui fotocamera non funziona. È valido cinque minuti e può essere usato una sola volta; Genera un nuovo codice gliene fornisce un altro.
4. Nell'app, scansioni il codice QR. Il telefono si collega al gateway e compare in linea in Dispositivi, con le sue SIM.
5. Invii un SMS di prova da Invio rapido, poi risponda da un altro telefono: la risposta compare in Conversazioni.

L'app chiede di essere esclusa dall'ottimizzazione della batteria e mostra una notifica permanente: è ciò che la mantiene attiva in background. Tenga il telefono in carica. Tutto ciò che riguarda i telefoni (SIM, quota giornaliera, mantenere il telefono sveglio) è in Dispositivi.

Se digita l'indirizzo a mano invece di scansionare, lo scriva per intero, con https:// o http:// (https://sms.example.com o http://server.local:8080). Senza, l'app presuppone una connessione HTTPS, che fallisce su un'installazione in rete locale.

Scegliere la modalità: dominio o rete locale

È l'unica vera scelta dell'installazione, e decide l'indirizzo che i telefoni chiamano. Questo indirizzo viene scritto in ogni codice QR di associazione, poi conservato dal telefono. Un indirizzo sbagliato produce un codice QR che si scansiona perfettamente e un telefono che non raggiunge mai nulla.

Scelga la modalità dominio ogni volta che può: non ha nessuna delle riserve che seguono.

Che cosa implica la modalità rete locale

• L'app Android accetta connessioni non cifrate solo verso un nome .local. Un semplice indirizzo IP come http://192.168.1.20:8080 viene rifiutato dal telefono. Per questo l'installer usa http://<nome-macchina>.local:8080.
• Verifichi che il telefono risolva quel nome prima di proseguire: apra http://<nome-macchina>.local:8080/health nel browser del telefono, collegato alla stessa wifi. Una risposta {"status":"ok",...} significa che l'associazione può funzionare.
• La sessione della dashboard viaggia non cifrata sulla Sua rete. L'installer imposta GATEWAY_INSECURE_COOKIES=true, altrimenti i browser si rifiuterebbero di mantenere la sessione in HTTP in chiaro. Accettabile su una rete aziendale che controlla, non su una wifi condivisa.
• Il nome della macchina non deve cambiare, perché è scritto nei codici QR. Rinominarla La costringe ad associare di nuovo i telefoni.
• Una wifi ospiti spesso isola i suoi dispositivi: il telefono vede internet ma non la macchina. Il test /health qui sopra lo rivela. Metta i telefoni sulla rete interna.

Tutto ciò che è specifico di questo percorso (indirizzo fisso, wifi ospiti, accesso dall'esterno) è in Server locale.

Che cosa implica la modalità dominio

• Il DNS deve puntare alla macchina prima che il certificato possa essere ottenuto. Lo script La avvisa se non è così; il certificato viene ottenuto automaticamente non appena il DNS è corretto.
• Le porte 80 e 443 devono essere raggiungibili da internet, la 80 compresa: serve a dimostrare che il dominio è Suo. Le apra nel firewall della macchina e presso il Suo provider, che spesso filtra anch'esso.
• Nient'altro è esposto: un piccolo server web (Caddy) gestisce l'HTTPS davanti al gateway, che ascolta solo sulla macchina stessa.
• Se un proxy come Cloudflare si trova davanti al dominio, lo disattivi mentre il certificato viene ottenuto.

Il comando sms-gateway

Installato su Linux e macOS, si esegue come root (o con sudo) da qualsiasi cartella.

Rieseguire il comando di installazione ha lo stesso effetto di sms-gateway update.

Su Windows, il comando sms-gateway non esiste. Apra PowerShell in %ProgramData%\SmsGateway e usi direttamente Docker Compose:

Tenga il computer acceso e Docker Desktop impostato per avviarsi con Windows: il gateway funziona solo mentre Docker Desktop è in esecuzione.

Arrestare o riavviare non fa perdere nulla. Mentre il gateway è fermo, i telefoni conservano i messaggi in uscita e in entrata nella propria coda e li consegnano quando torna.

Rigenerare la chiave

Nell'area clienti, Rigenera la chiave sostituisce la Sua chiave di licenza con una nuova. Lo faccia se la chiave è trapelata (un ticket di assistenza, uno screenshot, un ex collaboratore), o per liberare la licenza prima di installare su un'altra macchina.

Il gateway installato non si ferma. Tuttavia non può più rinnovare la propria attivazione finché porta la vecchia chiave: apra Licenza nella dashboard e vi inserisca la nuova chiave. Tra due rigenerazioni deve passare almeno un minuto.

Risoluzione dei problemi

Cominci sempre con sms-gateway status, poi sms-gateway logs.

Accesso alla rete

La macchina ha bisogno di un accesso HTTPS in uscita verso:

Se bck1.araylab.com è bloccato, nulla smette di funzionare, ma la schermata della licenza continuerà a indicare che il nostro server non risponde.

Impostazioni modificabili

L'installer scrive la configurazione in /opt/sms-gateway/.env (leggibile solo da root; su Windows, %ProgramData%\SmsGateway\.env). Per un'installazione standard non c'è nulla da aggiungere. Tutto ciò che regola ogni giorno (finestra di invio, nuovi tentativi, fuso orario, notifiche, regole di instradamento...) si imposta nella dashboard, in Impostazioni e nelle schermate collegate, non qui: veda Impostazioni. Nessuna impostazione della dashboard ha una variabile equivalente, e nessuna variabile qui sotto si modifica dalla dashboard.

Dopo aver modificato il file .env, applichi la modifica con sms-gateway restart (su Windows: docker compose up -d nella cartella di installazione). Un aggiornamento o una nuova esecuzione dell'installer conserva il file; riscrive solo la versione e, se indica di nuovo --domain o --lan, le righe della modalità.

Nel file .env

Queste righe sono scritte dall'installer. Può modificarle, sapendo che cosa governa ciascuna.

Il file elenca anche, commentate, le impostazioni qui sotto (un aggiornamento aggiunge questo elenco una volta a un .env scritto da una versione precedente). Tolga il # davanti a una riga per usarla, poi riavvii. Il docker-compose.yml fornito passa ciascuna di esse al gateway; assente o vuota, il gateway applica il suo valore predefinito. Poiché vivono in .env e non in docker-compose.yml, un aggiornamento le conserva.

Interazioni da conoscere:

• La modalità è fatta di quattro righe che vanno insieme: GATEWAY_PUBLIC_URL, GATEWAY_DOMAIN, COMPOSE_PROFILES e GATEWAY_BIND (più GATEWAY_INSECURE_COOKIES). Cambiarne una senza le altre produce, ad esempio, un sito HTTPS funzionante e telefoni che non si associano. Per cambiare modalità o dominio, riesegua l'installer con --domain o --lan: le riscrive insieme.
• Cambiare GATEWAY_PUBLIC_URL non aggiorna i telefoni già associati: conservano l'indirizzo del loro codice QR. Li associ di nuovo dopo una modifica del genere.
• Un GATEWAY_TRUSTED_PROXIES troppo ampio (ad esempio 0.0.0.0/0) permette a chiunque di spacciarsi per qualsiasi indirizzo IP e di aggirare il blocco degli accessi. Lasciato vuoto, il gateway vede ogni visitatore con l'indirizzo del proxy, e tutti condividono gli stessi limiti.

Impostazioni avanzate

Il gateway legge anche le due variabili qui sotto. Non compaiono nel file scritto dall'installer, perché un'installazione cliente ne ha raramente bisogno.

Non tocchi queste. Esistono nel programma, ma un'installazione cliente non ne ha bisogno:

I backup non hanno variabili: il backup automatico si regola nella dashboard, in Impostazioni > Backup ed esportazione. Veda Backup.

Due regole valgono per ogni variabile:

• Un valore vuoto conta come assente: si applica il valore predefinito.
• Un valore non valido ferma il gateway all'avvio, con un messaggio che nomina la variabile, invece di farlo funzionare con un valore che Lei non ha scelto. Veda la sezione successiva.

Quando il gateway rifiuta di avviarsi

Il messaggio si trova in sms-gateway logs, su una riga che contiene gateway stopped. Il gateway si riavvia in ciclo finché la causa non viene corretta.

Perché un indirizzo http:// in chiaro viene rifiutato: in HTTP, la sessione della dashboard viaggerebbe non cifrata attraverso internet. Solo un nome .local (modalità rete locale) o localhost sono accettati senza HTTPS.

Perché la modalità carrier viene rifiutata senza tabella: non instraderebbe nulla per operatore, e Lei crederebbe di pagare la tariffa verso la stessa rete mentre paga quella verso altre reti.

Un ripristino che fallisce (veda Backup e ripristino) non impedisce mai l'avvio: il gateway si avvia sul database che ha e registra l'errore.

La chiave master

Al primo avvio, il gateway crea una chiave master, secret.key, nella sua cartella di dati. Protegge i segreti dei telefoni associati, i segreti dei webhook e la Sua chiave di licenza memorizzata nel database, e identifica la Sua macchina presso il nostro server delle licenze (viene inviata solo un'impronta derivata da essa, mai la chiave).

Perderla significa associare di nuovo tutti i telefoni e reinserire la chiave di licenza. Vive accanto al database, non al suo interno: un'esportazione del database da sola non la contiene, mentre l'archivio di sms-gateway backup, che copia l'intera cartella di dati, la contiene.

Che cosa contiene la cartella di dati

Il container è blindato: non può scrivere da nessuna parte tranne in questa cartella e in uno spazio temporaneo usato per le esportazioni del database. Se sostituisce il docker-compose.yml fornito con una Sua configurazione, conservi la riga hostname: sms-gateway (senza di essa, ogni ricreazione del container sembra un trasloco agli occhi del nostro server delle licenze) e il montaggio /tmp (senza di esso, l'esportazione del database fallisce).

Backup

L'intera installazione vive nella cartella di dati. Il backup più semplice è:

sudo sms-gateway backup

Eseguito dalla cartella in cui vuole l'archivio, ferma il gateway per i pochi secondi della copia (i telefoni conservano nel frattempo i loro messaggi), scrive sms-gateway-backup-<data>.tar.gz nella cartella corrente, lo riavvia e attende che risponda. Questo archivio contiene la chiave master insieme al database: lo conservi come il documento più sensibile dell'installazione, e non sulla stessa macchina.

Il gateway esegue anche backup automatici, senza interrompere gli invii: ogni giorno alle 03:00 nel fuso orario della piattaforma per impostazione predefinita, sette copie conservate, nella cartella di dati. Cambi l'ora, la frequenza e il numero di copie, o lo disattivi, in Impostazioni > Backup ed esportazione, che elenca e ripristina anche i backup ed esporta i Suoi dati in CSV o JSON. Queste copie restano sulla macchina: ne scarichi una, o copi un archivio di sms-gateway backup, per conservare una copia altrove.

Tutto è descritto in dettaglio in Backup e ripristino.

Le guide di hosting

Questa pagina copre l'installazione in sé. Ciò che è specifico di ogni tipo di macchina ha una sua guida:

E poi