Wiki

Configurazione e migrazione del server

Modificare config.toml, spostare la directory dei dati, usare un database PostgreSQL altrove, eseguire backup e ripristino.

Tutto si imposta in un unico file, /etc/uversion/config.toml. L'installer lo genera; in seguito potete modificarlo liberamente.

Il file di configurazione

Modificate, poi riavviate: il server legge la sua configurazione solo all'avvio.

sudo nano /etc/uversion/config.toml
sudo systemctl restart uversion-server

Ecco i campi che finirete per toccare. È un estratto parziale: il file ne contiene altri, e alcuni campi obbligatori non compaiono qui sotto. Non sovrascrivete mai il vostro file con questo blocco, modificate solo le righe interessate.

# EXTRAIT PARTIEL : le fichier contient d'autres sections.
# N'ecrasez jamais votre fichier avec ce bloc, editez les lignes concernees.

[server]
bind_address = "0.0.0.0"
port = 8080

[database]
# Ou toute base PostgreSQL accessible : autre disque, autre machine, service manage.
url = "postgres://uversion:MOTDEPASSE@127.0.0.1:5432/uversion"

[security]
# Le secret qui signe les sessions. Obligatoire et SANS valeur par defaut :
# absent ou plus court que 32 caracteres, le serveur refuse de demarrer.
# L'installateur en genere un. Le remplacer deconnecte tout le monde une fois.
jwt_secret = "..."

[storage]
# Le contenu des fichiers (les chunks, morceaux de fichiers). C'est ce qui grossit.
path = "/var/lib/uversion/data/chunks"

[tls]
disabled = false
https_port = 8443

[licence]
key = "..."

Permessi del file Contiene la chiave di licenza, il segreto che firma le sessioni e la password del database. È in 0640 root:uversion: mantenetelo così.

Dove vivono i dati

Tre posizioni distinte, ed è il punto che sorprende di più. La terza, la configurazione, è anche quella che si dimentica nei backup:

Che cosa	Dove
Contenuto dei file (i chunk, frammenti di file: è ciò che occupa spazio)	`/var/lib/uversion/data/chunks`
Certificato TLS, impronta del server	`/var/lib/uversion/data/tls`
Identità del server, ancoraggio della licenza	`/var/lib/uversion/server-id`, `last-validated-at`
Metadati (file, revisioni, utenti, blocchi, permessi, attività)	PostgreSQL: `/var/lib/postgresql/16/main`
Configurazione: chiave di licenza, segreto di firma delle sessioni, password del database	`/etc/uversion/config.toml`, `/etc/uversion/licence-key`

Il database non segue la directory dei dati Cambiare la directory dei dati sposta i chunk e i certificati, non il database. E il database referenzia i chunk tramite l'impronta: se spostate l'uno senza l'altro, il server cercherà chunk introvabili. Spostate entrambi, oppure nessuno.

Spostare la directory dei dati

È il caso comune: il contenuto cresce, la partizione di sistema è piccola. Il database, invece, resta piccolo (cresce con il numero di revisioni, non con la dimensione dei file).

1. Fermare il servizio

sudo systemctl stop uversion-server

2. Copiare la directory

È il -a che preserva permessi e proprietari. Copiare, anziché spostare, vi lascia un ritorno indietro possibile fino alla verifica finale.

sudo mkdir -p /srv/uversion
sudo rsync -a /var/lib/uversion/ /srv/uversion/
sudo chown -R uversion:uversion /srv/uversion
sudo chmod 0750 /srv/uversion

3. Puntare la configurazione sul nuovo percorso

Questo passaggio è obbligatorio e viene prima del successivo: vedete il riquadro «L'ordine conta» più in basso.

sudo sed -i 's#/var/lib/uversion#/srv/uversion#g' /etc/uversion/config.toml

4. Dichiarare il nuovo percorso all'installer

Rispondete il nuovo percorso alla domanda «Data directory». L'installer riscrive l'unità systemd a partire da questa risposta, poi riavvia il servizio.

sudo dpkg-reconfigure uversion-server
#   Data directory : /srv/uversion

5. Verificare che l'unità punti davvero lì

systemctl cat uversion-server | grep -E 'WorkingDirectory|ReadWritePaths'
systemctl status uversion-server

Passate per dpkg-reconfigure, non scrivete voi stessi l'unità systemd L'installer scrive esso stesso /etc/systemd/system/uversion-server.service.d/10-data-dir.conf, e la riscrive a ogni configurazione a partire dalla risposta che gli avete dato. Un file posato a mano vi sopravvive fino all'aggiornamento successivo, compreso quello attivato dal pulsante Update now: l'unità torna allora a puntare sulla vecchia cartella mentre la configurazione scrive nella nuova. Il servizio irrobustito (ProtectSystem=strict) si avvia normalmente, e si rompe al primo invio di file, settimane dopo.

L'ordine conta: modificate config.toml prima dpkg-reconfigure da solo non basta. L'installer corregge [storage].path solo se la cartella che vi trova non esiste più: un percorso personalizzato ancora presente è considerato una scelta deliberata e lasciato com'è. Poiché avete copiato anziché spostato, la vecchia cartella esiste ancora, e il passaggio 2 qui sopra è dunque obbligatorio. Una volta verificato tutto e con il server in servizio sul nuovo percorso, potete eliminare la vecchia cartella.

Mai sotto /home né /root Il servizio gira come utente di sistema irrobustito (ProtectHome=true, e una directory personale non è attraversabile da un account di sistema). Un percorso sotto /home o /root impedisce l'avvio (226/NAMESPACE o 200/CHDIR). Scegliete un percorso di sistema: /srv, /opt, o un disco montato.

Mettere il database altrove

L'installer crea un database locale, ma nulla vi obbliga a usarlo. Puntate url su qualsiasi database PostgreSQL raggiungibile: un altro disco montato come cluster separato, un'altra macchina, o un servizio gestito.

[database]
url = "postgres://UTILISATEUR:MOTDEPASSE@HOTE:5432/BASE"

Poi riavviate. Il server applica le sue migrazioni all'avvio: aggiorna da solo la struttura del suo database. Un database vuoto viene inizializzato, uno più vecchio viene aggiornato, non avete nulla da lanciare a mano.

Basta semplicemente che il ruolo indicato possa creare tabelle nel database di destinazione.

Database sul disco dati

La sezione precedente presuppone un database che amministrate altrove. Se il vostro obiettivo è diverso: che un solo disco superstite basti a rimettere in piedi il server quando la macchina muore, allora l'installer può collocare il database dentro la directory dei dati, sotto forma di un cluster PostgreSQL dedicato: un'istanza PostgreSQL a parte, con la propria cartella e la propria porta, indipendente da quella del sistema.

La domanda viene posta all'installazione. Per attivarla su un server Debian già presente:

sudo dpkg-reconfigure uversion-server
#   Data directory                     : /srv/uversion
#   Put the database on the data directory too?  Yes

Su Windows

Stessa promessa, meccanica diversa. Windows non ha cluster con nome: l'installer sposta l'istanza PostgreSQL stessa sulla directory dei dati, ripuntando il servizio. Questa scelta si fa al momento dell'installazione, aggiungendo -DbOnDataDir ai parametri dello script. Non viene proposta da una domanda: lo script chiede solo il codice di attivazione, quindi se non passate questo parametro, il database resterà nella sua posizione predefinita. Vedete Installare su Windows per la forma esatta del comando, tenendo presente che il one-liner non può ricevere alcun parametro.

# PowerShell en administrateur, installation en ligne de commande
& ([scriptblock]::Create((iwr https://uversion.io/downloads/server/install.ps1 -UseBasicParsing).Content)) `
    -LicenceKey "UV-XXXX-XXXX-XXXX" -DataDir "D:\uVersion" -DbOnDataDir

# verifier ensuite ou pointe le service PostgreSQL
(Get-CimInstance Win32_Service -Filter "Name='postgresql-x64-16'").PathName

Lo spostamento viene rifiutato, con il motivo visualizzato, se l'istanza ospita database diversi da quello di uVersion, o se la sua directory non è autonoma: presenza di un tablespace, un pg_wal spostato tramite una giunzione, o un percorso assoluto scritto in postgresql.conf. Nulla viene mai eliminato: l'installer copia, verifica, avvia il servizio sulla nuova copia, e solo dopo rinomina la vecchia directory.

Due differenze rispetto a Linux Windows non sa far attendere un servizio dietro un disco: non esiste alcun equivalente di RequiresMountsFor. Un disco esterno arrivato in ritardo è quindi recuperato dalle azioni di ripristino del servizio, non da una dipendenza. E PostgreSQL non verifica alcun permesso sulla sua directory sotto Windows: è l'installer a restringerli, non c'è rete di sicurezza dal lato del server.

Il disco contiene allora tutto:

/srv/uversion/
├── data/chunks       contenu des fichiers
├── data/tls          certificat, empreinte
├── pgdata/16         LA BASE (cluster PostgreSQL dedie)
└── recovery/         procedure + fichiers necessaires a la reprise
    ├── RESTORE.md
    ├── pgconf/       postgresql.conf, pg_hba.conf, pg_ident.conf
    ├── etc/          copie de config.toml et du mot de passe
    └── cluster.env

Il cluster riceve la propria porta, assegnata automaticamente (5433 se è libera), e config.toml viene aggiornato per puntarla. Il cluster di sistema non viene toccato: può continuare a ospitare altri database.

Due contropartite, da conoscere prima di dire sì Una directory dei dati PostgreSQL si apre solo con la versione maggiore che l'ha creata: un ripristino tra tre anni può richiedere di installare esplicitamente PostgreSQL 16. E il disco porta ormai la chiave di licenza, il segreto che firma le sessioni e la password del database, in una directory accessibile al solo root: trattate questo disco come una credenziale.

Database già riempito: l'installer rifiuta di spostarlo Se il vostro server gira già con dei dati, attivare l'opzione non sposta nulla: un trasloco interrotto a metà di un aggiornamento di pacchetto sarebbe peggio di nessun trasloco. L'installer vi lascia nello stato attuale e stampa la procedura manuale (arresto, pg_dump, creazione del cluster, ripristino, aggiornamento di url).

Rimettere in piedi il server su una macchina nuova

Il disco non contiene i software: prevedete PostgreSQL e il pacchetto uVersion, di cui una copia conservata accanto al disco evita una brutta sorpresa il giorno in cui serve.

# sur la machine neuve
sudo apt install postgresql-16
# montez le disque, par exemple sur /srv/uversion
sudo apt install ./uversion-server_*.deb
#   dossier de donnees : le point de montage du disque
#   base sur le dossier de donnees : oui

L'installer trova il database sul disco, rimette a posto i file di configurazione di PostgreSQL (che pg_createcluster aveva spostato fuori dalla directory, sul disco di sistema), registra il cluster, corregge i proprietari, poi riallinea la porta e il percorso dei chunk in config.toml. Se il disco viene rimontato su un punto di montaggio diverso da prima, basta indicare il nuovo percorso.

La procedura completa, compresa la variante senza reinstallazione, è scritta sul disco stesso: recovery/RESTORE.md.

Backup e ripristino

Un backup completo sono tre elementi: l'esportazione del database (il dump), la directory dei dati e la directory di configurazione.

Fare il backup del database

I metadati: file, revisioni, utenti, blocchi.

sudo -u postgres pg_dump uversion > uversion-$(date +%F).sql

Fare il backup della directory dei dati

Il contenuto dei file, cioè ciò che occupa spazio.

sudo tar -C /var/lib/uversion -czf uversion-data-$(date +%F).tar.gz .

Fare il backup della configurazione

Chiave di licenza, segreto di firma delle sessioni, password del database. Non vive nella directory dei dati.

sudo tar -C /etc -czf uversion-etc-$(date +%F).tar.gz uversion

Non dimenticate /etc/uversion È il terzo elemento, e il più facile da dimenticare: non vive nella directory dei dati. /etc/uversion/config.toml porta la chiave di licenza, il segreto che firma le sessioni e la password del database; /etc/uversion/licence-key porta la licenza stessa. Senza di essi, un ripristino su una macchina nuova riparte con un segreto nuovo, quindi tutta la squadra viene disconnessa in un colpo solo, e bisogna richiedere una licenza: il codice di attivazione ricevuto all'iscrizione è a uso unico e già consumato, solo la chiave di licenza che ha prodotto si riutilizza.

Per ripristinare su una macchina nuova: installate il pacchetto, poi rimettete a posto i tre elementi, in questo ordine.

1. Ripristinare il database

sudo -u postgres createdb -O uversion uversion      # seulement si elle n'existe pas
sudo -u postgres psql uversion < sauvegarde.sql

2. Ripristinare i dati

Rimettere i chunk, con i permessi corretti:

sudo rsync -a /mnt/backup/uversion/ /var/lib/uversion/
sudo chown -R uversion:uversion /var/lib/uversion
sudo chmod 0750 /var/lib/uversion

3. Riportare due righe di configurazione

Non il file intero: quello che l'installer ha appena scritto porta la password del database che ha ridefinito esso stesso.

# N'ECRASEZ PAS le fichier neuf : ouvrez l'ancien a cote et recopiez-en
# deux lignes, et deux seulement.
#   [security] jwt_secret  -> sinon toute l'equipe est deconnectee
#   [licence]  key         -> sinon il faut redemander une licence
# Gardez le [database] url que l'installateur vient d'ecrire : il porte le
# mot de passe qu'il a lui-meme redefini.
sudo nano /etc/uversion/config.toml

4. Riavviare

sudo systemctl restart uversion-server

Installare sopra un database esistente L'installer non distrugge nulla: se trova già il database uversion, lo riutilizza così com'è e si limita a reimpostare la password del ruolo. Potete quindi ripristinare il vostro dump prima, e installare dopo.

Spostare il cluster PostgreSQL

Raramente necessario: il database è piccolo. Se ci tenete, è un'operazione PostgreSQL standard, non qualcosa che gestisce l'installer di uVersion. Attenzione: questo cluster (l'istanza PostgreSQL del sistema, con la sua cartella e la sua porta) può ospitare database diversi da quello di uVersion.

sudo systemctl stop uversion-server
sudo pg_ctlcluster 16 main stop

sudo mkdir -p /srv/pgdata
sudo rsync -a /var/lib/postgresql/16/main/ /srv/pgdata/16/main/
sudo chown -R postgres:postgres /srv/pgdata

sudo sed -i "s#^data_directory =.*#data_directory = '/srv/pgdata/16/main'#" \
  /etc/postgresql/16/main/postgresql.conf

sudo pg_ctlcluster 16 main start
sudo systemctl start uversion-server

Verificate poi con pg_lsclusters che il cluster sia in linea sul nuovo percorso.