Vai al contenuto principale

Installazione tramite Node Package Manager

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

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

⚠️ Gli ambienti Windows non sono supportati ufficialmente.

📋 Prerequisiti​

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

🟢 Node.js​

Versione richiesta: 22.12.0 o successiva – Installare Node.js: nodejs.org/download

✅ Verificare la versione di Node.js installata:

node -v

✅ Verificare la versione di npm installata (installarlo se non è già disponibile):

npm -v

🛢️ MariaDB​

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

✅ Verificare la versione installata:

mariadb --version
informazioni

Il binario può variare a seconda del sistema: utilizzare mysql o mariadb in base alle esigenze.

Verificare 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

Connettersi a MariaDB come amministratore (o root):

mariadb -u root -p

Eseguire 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 su localhost in MariaDB

  • 'sync_in_user'@'localhost'

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

  • 'sync_in_user'@'%'

    • ➡ Connessione possibile da qualsiasi indirizzo IP.
    • ⚠ Rischio maggiore: utilizzare questa opzione soltanto in casi specifici, con una password robusta e un filtro IP a livello di firewall.

  • 'sync_in_user'@'IP' o 'sync_in_user'@'nome_host'

    • ➡ Connessione limitata a questo indirizzo IP o a questo nome host specifico.
    • ✅ Opzione consigliata per un accesso remoto sicuro.
Raccomandazioni per l'ottimizzazione
[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, a costo di un maggiore utilizzo 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 massive.

🚀 Installazione​

1. Pacchetto NPM​

È possibile installare il server Sync-in in una cartella dedicata utilizzando l'opzione --prefix di NPM:

Nota sull'installazione in FreeBSD

Prima di procedere, verificare che sia disponibile la libreria vips (versione ≥ 8.17.2). Se necessario, passare al repository FreeBSD latest.

  • Comando per verificare la versione disponibile:

    pkg rquery '%v' vips

  • Installare le dipendenze di compilazione:

    pkg install -y python3 gmake pkgconf llvm

  • Installare la libreria vips:

    pkg install vips

  • Installare 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 verrà 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 una configurazione minima direttamente nell'ambiente, è possibile utilizzare la CLI sync-in-server:

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

oppure con l'argomento --prefix:

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

Utilizzare l'opzione --prefix se i comandi CLI vengono eseguiti da una directory diversa da sync-in, utilizzata qui come esempio.

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

server:
  # Facoltativo per ora; obbligatorio nella prossima versione principale
  publicUrl: 'https://sync-in.domain.com'
mysql:
  # Utilizzare il nome utente e la password definiti in precedenza
  url: 'mysql://sync_in_user:sync_in_user_password@localhost:3306/sync_in'
auth:
  encryptionKey: 'REPLACE_WITH_LONG_RANDOM_ENCRYPTION_KEY'
  token:
    access:
      secret: 'REPLACE_WITH_LONG_RANDOM_ACCESS_SECRET'
    refresh:
      secret: 'REPLACE_WITH_LONG_RANDOM_REFRESH_SECRET'
URL pubblico

publicUrl deve corrispondere all'indirizzo esposto agli utenti dal server o dal reverse proxy, includendo lo schema e l'eventuale porta non standard. Resta facoltativo fino alla prossima versione principale. L'URL deve essere raggiungibile dai browser degli utenti e, per gli editor per ufficio che comunicano con Sync-in, dai relativi servizi. Quando publicUrl viene omesso, gli editor utilizzano l'origine della richiesta come soluzione di compatibilità. Per motivi di sicurezza, diventerà obbligatorio nella prossima versione principale: gli endpoint degli editor verranno così creati da un'origine attendibile controllata dall'amministratore anziché dalle intestazioni della richiesta.

Sicurezza

Per garantire la massima sicurezza, utilizzare stringhe lunghe e generate casualmente per i segreti.

informazioni

Racchiudere le password tra virgolette singole se contengono caratteri speciali.

suggerimento

I parametri scalari di configurazione del server Sync-in possono essere definiti tramite variabili d'ambiente con il prefisso SYNCIN_; consultare la sezione corrispondente.

3. Database​

Dopo aver completato la configurazione, inizializzare 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​

È configurato un percorso predefinito per archiviare tutti i dati dell'applicazione.

È possibile personalizzarlo modificando il file environment.yaml come mostrato di seguito:

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 non amministratore, sostituire --role admin con --role user.

Durante la creazione dell'account sono disponibili anche gli argomenti facoltativi --email, --first-name, --last-name, --permissions e --storage-quota. Utilizzare --permissions all per assegnare tutte le autorizzazioni utente. --storage-quota è espresso in byte; utilizzare 0 per uno spazio di archiviazione illimitato.

Se questi argomenti non vengono impostati e si esegue semplicemente:

npx sync-in-server create-user

Il server utilizzerà le credenziali di amministratore predefinite:

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

Importante: per motivi di sicurezza, si consiglia vivamente di modificare queste credenziali al primo accesso.

6. Avviare il server​

È possibile avviare il server in due modi:

  • In primo piano (il processo rimane collegato al terminale):

    npx sync-in-server start

  • In background (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.