Vai al contenuto principale

Installazione

Installazione del server Sync-in tramite NPM e l'interfaccia a riga di comando (CLI).

Il server è progettato per funzionare in ambienti basati su Linux (Debian, Ubuntu, AlmaLinux, Rocky Linux ecc.) e in sistemi basati su BSD (FreeBSD, macOS ecc.).

⚠️ Gli ambienti Windows non sono supportati ufficialmente.

📋 Prerequisiti​

Prima di installare Sync-in, verifica che l'ambiente soddisfi i requisiti seguenti.

🟢 Node.js​

Versione richiesta: 22.x – 24.x – Installa Node.js: nodejs.org/download

✅ Verifica la versione di Node.js installata:

node -v

✅ Verifica la versione di npm installata; installalo se non è già disponibile:

npm -v

🛢️ MariaDB​

Versione richiesta: 11.x – Installa MariaDB: mariadb.org/download

✅ Verifica la versione installata:

mariadb --version
informazioni

Il nome del programma può variare a seconda del sistema: utilizza mysql o mariadb, secondo necessità.

Verifica che:

  • il servizio MariaDB sia in esecuzione;
  • la porta 3306 sia aperta se il database è remoto;
  • sia stato creato manualmente un database prima di avviare il server.
Creare un database locale con un utente dedicato

Connettiti a MariaDB come amministratore (o root):

mariadb -u root -p

Esegui quindi i comandi seguenti:

CREATE DATABASE sync_in CHARACTER SET utf8mb4 COLLATE utf8mb4_uca1400_ai_ci;

CREATE USER 'sync_in_user'@'localhost' IDENTIFIED BY 'sync_in_user_password';

GRANT ALL PRIVILEGES ON sync_in.* TO 'sync_in_user'@'localhost';

FLUSH PRIVILEGES;
avvertenza

Promemoria importante relativo a localhost in MariaDB

  • 'sync_in_user'@'localhost'

    • ➡ Connessione consentita soltanto dal computer che ospita MariaDB, tramite socket Unix o connessione TCP locale.

  • 'sync_in_user'@'%'

    • ➡ Connessione possibile da qualsiasi indirizzo IP.
    • ⚠ Rischio maggiore: utilizzare soltanto in casi specifici, con una password robusta e un filtro degli indirizzi IP nel firewall.

  • 'sync_in_user'@'IP' o 'sync_in_user'@'hostname'

    • ➡ Connessione limitata a questo specifico indirizzo IP o nome host.
    • ✅ Opzione consigliata per un accesso remoto sicuro.
Configurazione consigliata
[mysqld]
innodb_ft_cache_size = 16000000 # 16MB
max_allowed_packet   = 1G

Dettagli:

  • innodb_ft_cache_size: utilizzato da InnoDB durante la creazione o l'aggiornamento degli indici FULLTEXT. Valori più elevati velocizzano la creazione degli indici, aumentando però l'uso della RAM.
  • max_allowed_packet: definisce la dimensione massima dei pacchetti scambiati tra il client e il server MariaDB, ad esempio in presenza di BLOB di grandi dimensioni o esportazioni SQL voluminose.

🚀 Installazione​

1. Pacchetto NPM​

Puoi installare il server Sync-in in una cartella dedicata mediante l'opzione --prefix di NPM:

Nota per l'installazione su FreeBSD

Prima di continuare, verifica che sia disponibile la libreria vips (versione ≥ 8.17.2). Se necessario, passa al repository latest di FreeBSD.

  • Verifica la versione disponibile:

    pkg rquery '%v' vips

  • Installa le dipendenze di compilazione:

    pkg install -y python3 gmake pkgconf llvm

  • Installa la libreria vips:

    pkg install vips

  • Installa il server Sync-in:

    npm install @sync-in/server node-addon-api node-gyp --prefix ./sync-in
npm install @sync-in/server --prefix ./sync-in

Il pacchetto del server viene installato nella directory ./sync-in, con la struttura seguente:

  • ./sync-in/node_modules/ → dipendenze installate
  • ./sync-in/package.json → metadati del pacchetto

2. Configurazione​

Il file di configurazione del server environment.yaml deve trovarsi in questa directory.

Per distribuire direttamente nell'ambiente una configurazione minima, puoi utilizzare la CLI sync-in-server:

cd ./sync-in && npx sync-in-server init

oppure utilizzare l'argomento --prefix:

npx --prefix ./sync-in sync-in-server init
suggerimento

Utilizza l'opzione --prefix se esegui i comandi della CLI da una directory diversa da sync-in, usata qui come esempio.

Modifica il file ./sync-in/environment.yaml:

auth:
  encryptionKey: "changeEncryptionKeyWithStrongKey"
  token:
    access:
      secret: "changeAccessWithStrongSecret"
    refresh:
      secret: "changeRefreshWithStrongSecret"
mysql:
  # Usa il nome utente e la password definiti in precedenza
  url: mysql://sync_in_user:sync_in_user_password@mariadb:3306/sync_in
Sicurezza

Utilizza stringhe lunghe e generate casualmente per i segreti, così da garantire la massima sicurezza.

informazioni

Racchiudi le password tra virgolette se contengono caratteri speciali.

suggerimento

Tutti i parametri di configurazione del server Sync-in possono essere definiti mediante variabili d'ambiente con il prefisso SYNCIN_; consulta la sezione dedicata.

3. Database​

Dopo aver completato la configurazione, inizializza il database dalla directory sync-in:

npx sync-in-server migrate-db

Output previsto:

🗄️ Running database migrations...
Load configuration → environment.yaml
✅ Database migrations completed successfully.

4. Archiviazione dei dati​

Per impostazione predefinita è configurato un percorso in cui vengono archiviati tutti i dati dell'applicazione.

Puoi personalizzarlo modificando il file environment.yaml, come nell'esempio seguente:

applications:
  files:
    dataPath: /home/sync-in/data

5. Creare un amministratore​

npx sync-in-server create-user --role admin --login "userLogin" --password "userPassword"
suggerimento

Per creare un utente senza privilegi di amministratore, sostituisci --role admin con --role user.

Se non specifichi questi argomenti ed esegui semplicemente:

npx sync-in-server create-user

il server utilizzerà le credenziali predefinite dell'amministratore:

  • Nome utente: sync-in
  • Password: sync-in
avvertenza

Importante: per motivi di sicurezza, è fortemente consigliato modificare queste credenziali al primo accesso.

6. Avviare il server​

Puoi avviare il server in due modi:

  • In modalità collegata, mantenendo il processo collegato al terminale:

    npx sync-in-server start

  • In modalità scollegata (daemon):

    npx sync-in-server start -d
    informazioni

    In modalità daemon, il processo non è più collegato alla console dell'utente.
    I log vengono scritti automaticamente in logs/server.log.
    Il percorso del file di log può essere personalizzato in environment.yaml.