Wiki

Installare su Ubuntu / Debian

Il pacchetto .deb: le tre domande, la directory dei dati, l'installazione offline, il backup e la disinstallazione.

Ubuntu 24.04+, Debian 13+ (x86_64). Due comandi, tre domande.

Installare

1. Scaricare il pacchetto

Dalla macchina che ospiterà il server, in una sessione normale:

cd /tmp && wget -N https://uversion.io/downloads/server/uversion-server_latest_amd64.deb

L'URL _latest_ punta sempre alla versione pubblicata più recente. Il flag -N dice a wget di riscaricare solo se il file remoto è più recente: utile per aggiornare senza accumulare copie .deb.1, .deb.2, ecc. cd /tmp evita un avviso cosmetico di apt ("unsandboxed as root") quando il .deb si trova nella tua home directory.

2. Avviare l'installazione

Un solo comando, nella directory in cui hai appena scaricato il pacchetto:

sudo apt install ./uversion-server_latest_amd64.deb

Il programma di installazione pone allora tre domande, nell'ordine dei tre passaggi seguenti. Compaiono in una finestra di dialogo blu a schermo intero: ti sposti con Tab e confermi con Invio.

3. Rispondere: la directory dei dati

Predefinito: /var/lib/uversion. È qui che finisce il contenuto dei tuoi file versionati, quindi la directory che cresce, quindi quella che vuoi sul tuo disco grande. Non tutti i percorsi sono accettati: la sezione Scegliere una directory dei dati indica le quattro regole, e il programma di installazione rifiuta nominando la regola infranta.

La prima domanda del programma di installazione Debian, in una finestra di dialogo blu a schermo intero: il percorso della directory dei dati, precompilato con /var/lib/uversion.

4. Rispondere: mettere anche il database sulla directory dei dati?

Predefinito: no. È la domanda più gravida di conseguenze dell'installazione, e questo valore predefinito ha un costo che conviene conoscere prima di lasciarlo così com'è.

Questa risposta decide se un solo disco basta a rimettere in piedi il tuo server.

No (predefinito): il database PostgreSQL resta nella directory di sistema (/var/lib/postgresql), separato dai tuoi dati. Se la macchina muore, il disco dati superstite contiene il contenuto dei file, ma nessuna revisione, nessun account, nessun blocco e nessun permesso. Non è un server che si riavvia: è un mucchio di byte.
Sì: il programma di installazione crea un database dedicato all'interno della directory dei dati e vi scrive una procedura di ripristino. Un solo disco superstite, più PostgreSQL e questo pacchetto, bastano allora a ricostruire il server su un'altra macchina.

Due contropartite da conoscere prima di rispondere sì. Questa directory di database può essere riaperta solo dalla versione maggiore di PostgreSQL che l'ha creata, quindi una ricostruzione tra diversi anni può richiedere di installare esplicitamente quella versione. E il disco porta allora anche la chiave di licenza, il segreto JWT e la password del database: trattalo come un segreto. Questa risposta si cambia più tardi con sudo dpkg-reconfigure uversion-server.

5. Rispondere: il codice di attivazione

Obbligatorio, salvo che una licenza sia già presente sulla macchina o sul disco scelto al passaggio 3: in tal caso il programma di installazione te lo annuncia in un messaggio dedicato e non pone la domanda, perché un codice di attivazione è a uso singolo e il tuo è già stato consumato dalla macchina da cui proviene questo disco.

Il campo accetta tre forme, che è la tua via d'uscita se la macchina non ha Internet: il codice breve UV-XXXX-XXXX-XXXX, un percorso assoluto verso un file contenente la tua chiave di licenza completa, o quella chiave completa incollata direttamente (una lunga stringa che inizia con eyJ). Solo con la prima forma il programma di installazione contatta licence.uversion.io per scambiare il codice con la chiave completa.

6. Annotare ciò che appare alla fine

L'installazione termina con un riquadro colorato: nome utente admin, password temporanea, indirizzo del server e impronta del certificato. Annotali: il file che contiene questa password viene eliminato non appena la cambi.

Il riepilogo mostrato al termine dell'installazione: nome utente admin, password temporanea e indirizzo del server.

Puoi poi proseguire con Primo accesso.

Un'installazione interrotta si riavvia senza rischi. Se chiudi la finestra, se la rete cade o se il programma di installazione si ferma su un errore, rilancia semplicemente lo stesso comando apt install. Il tuo codice di attivazione non va perso di nuovo: non appena è stato scambiato, la chiave ottenuta viene scritta sul disco e riutilizzata ai tentativi successivi. E per tornare su qualsiasi risposta in seguito, senza reinstallare: sudo dpkg-reconfigure uversion-server. È il comando di recupero universale di questa pagina.

Scegliere una directory dei dati che il programma di installazione accetti

Quattro regole. Le prime tre vengono verificate prima che il tuo codice di attivazione venga consumato, quindi un rifiuto non ti costa nulla: correggi e ricominci.

Né sotto /home, né sotto /root. Il server gira con un account di sistema deliberatamente privato di ogni accesso alle directory personali: non potrebbe mai leggere né scrivere lì, e non si avvierebbe.
Nessuno spazio nel percorso. Il percorso viene ricopiato tale e quale nelle impostazioni del servizio, dove uno spazio separa due valori. Un disco esterno montato automaticamente con un nome come /media/jean/My Book ci casca esattamente.
Un percorso assoluto, cioè che inizia con /.
Ogni directory padre deve lasciar passare gli account uversion e postgres. È la trappola meno evidente, e non si vede quando si installa come root: una directory padre creata a mano e chiusa (per esempio un /perforce in root:root 0750, ereditato da un deposito Helix) lascia passare tutta l'installazione, poi blocca il servizio al primo accesso. Il sintomo è un servizio che si rifiuta di avviarsi con status=200/CHDIR, o un "Permission denied" alla prima scrittura.

Per verificare quest'ultimo punto prima di lanciare l'installazione, mostra i permessi dell'intera catena di directory che porta alla tua scelta:

namei -l /srv/uversion        # remplacez par le chemin que vous voulez utiliser

Ogni riga deve portare una x nell'ultima colonna dei permessi (quella degli "altri"). Se ne manca una, il programma di installazione ti nomina la directory colpevole e il comando esatto da eseguire, del tipo sudo chmod o+x /le/dossier. Non modifica mai da sé una directory che non gli appartiene: aprire un accesso sul tuo albero è una tua decisione, non la sua.

Dove vanno i file

Due posizioni, e solo una delle due ti segue se cambi la directory dei dati.

Nella directory dei dati (quella della domanda 1): il contenuto dei tuoi file versionati (sotto data/chunks), il certificato TLS e la sua impronta (sotto data/tls), l'identità del server (server-id, last-validated-at), la password iniziale dell'amministratore (initial-admin-password, cancellata non appena la cambi), il database PostgreSQL (pgdata) e il kit di ripristino (recovery) se hai risposto sì alla domanda 2.

In /etc/uversion/, che non si sposta mai: il file di configurazione config.toml, la copia nuda della chiave di licenza (licence-key) e la password del database (db-password).

Tutti i comandi di questa pagina usano <data-dir> al posto di un percorso fisso, perché quel percorso è quello che tu hai scelto. Per leggere il valore reale su una macchina già installata:

sudo sed -n 's/^WorkingDirectory=//p' /etc/systemd/system/uversion-server.service.d/10-data-dir.conf

Verificare l'installazione

Tre controlli indipendenti, da fare in questo ordine: il servizio gira, è in ascolto, e non ha segnalato nulla.

1. Il servizio gira

systemctl status uversion-server

Atteso: active (running). Qualsiasi altro valore rimanda alla risoluzione dei problemi.

2. Il server è in ascolto in HTTPS sulla 8443

ss -tlnp | grep 8443

Deve comparire una riga. Se non esce nulla mentre il servizio gira, di solito è perché TLS è stato disattivato nella configurazione: il server passa allora a HTTP semplice e la 8443 non è più affatto in ascolto.

3. I registri non mostrano errori

sudo journalctl -u uversion-server -n 50

journalctl è il lettore dei registri di sistema: è lì che il server scrive ciò che fa, ed è il primo posto da guardare quando qualcosa non parte.

Rimostrare l'impronta del certificato

Sostituendo <data-dir> con il valore letto sopra:

sudo cat <data-dir>/data/tls/fingerprint

Rimostrare la password iniziale dell'amministratore

Finché non è stata cambiata, è ancora sul disco:

sudo cat <data-dir>/initial-admin-password

"No such file or directory" qui significa che la password è già stata cambiata: è il comportamento atteso, il file viene eliminato in quel momento.

Installazione non interattiva e offline

Due esigenze diverse, uno stesso meccanismo: precompilare le risposte prima di lanciare apt, in modo che non compaia alcuna domanda. Il sistema che memorizza queste risposte si chiama debconf, e si pilota dalla riga di comando.

1. Precompilare le tre risposte

Una riga per domanda, esattamente le tre dell'installazione interattiva:

echo 'uversion-server uversion-server/data-dir string /srv/uversion' | sudo debconf-set-selections
echo 'uversion-server uversion-server/db-on-data-dir boolean true'   | sudo debconf-set-selections
echo 'uversion-server uversion-server/licence-key string UV-XXXX-XXXX-XXXX' | sudo debconf-set-selections

2. Installare senza finestra di dialogo

Poiché le risposte sono già a posto, l'installazione non chiede più nulla:

sudo DEBIAN_FRONTEND=noninteractive apt install -y ./uversion-server_latest_amd64.deb

Variante offline: dare la chiave invece del codice

Su una rete senza accesso a Internet, il codice di attivazione non può essere scambiato: non c'è nessuno da contattare. Recupera allora la tua chiave di licenza completa dalla tua area account su una postazione connessa, mettila sulla macchina e dai il percorso del file al posto del codice, al passaggio 1 qui sopra. È l'unica via d'uscita, ed è prevista:

echo 'uversion-server uversion-server/licence-key string /root/uversion-licence.key' | sudo debconf-set-selections

Il file deve contenere la chiave da sola, su una riga, senza virgolette né altro contenuto attorno. Un config.toml intero indicato per errore viene rifiutato esplicitamente. Terza forma possibile, se preferisci non mettere un file: incollare la chiave completa direttamente nel valore, al posto del percorso.

Fare un backup prima di ogni operazione rischiosa

Tre cose da copiare, e non si salvano nello stesso modo: il database (account, revisioni, blocchi, permessi), la directory dei dati (il contenuto dei file) e la configurazione, che vive altrove ed è quella che si dimentica.

1. Il database

Si salva come account postgres, mai come root: PostgreSQL non ha alcun "ruolo" (la sua parola per un account di database) chiamato root, quindi il comando lanciato direttamente da root fallisce con un messaggio che sembra un guasto mentre è una questione di identità.

Se hai risposto no alla domanda sul database (il valore predefinito), vive nel cluster di sistema:

sudo -u postgres pg_dump -Fc uversion > /tmp/uversion.dump

Se hai risposto sì, vive in un cluster separato, che va nominato esplicitamente, altrimenti salvi quello sbagliato:

pg_lsclusters                                    # repere la ligne "uversion" et sa version
sudo -u postgres pg_dump --cluster <major>/uversion -Fc uversion > /tmp/uversion.dump

2. La directory dei dati

Servizio fermato, per una copia coerente:

sudo systemctl stop uversion-server
sudo tar czf /tmp/uversion-data.tar.gz -C <data-dir> .
sudo systemctl start uversion-server

3. La configurazione

/etc/uversion/ non segue la directory dei dati e non è nel database: porta la chiave di licenza, il segreto che firma le sessioni e la password del database. Senza di essa, un ripristino su macchina nuova riparte con un segreto nuovo, quindi tutta la squadra viene disconnessa in un colpo solo, e bisogna richiedere una licenza.

sudo tar czf /tmp/uversion-etc.tar.gz -C /etc uversion

Disinstallare

Attenzione: questi comandi eliminano i tuoi repository, la cronologia, gli account utente e le configurazioni. Fai prima il backup della sezione precedente se vuoi poter tornare indietro.

1. Purgare il pacchetto

La purga rimuove il binario, il servizio, le risposte di configurazione, /etc/uversion/ e l'account di sistema uversion. Preserva di proposito il database e la directory dei dati: sono i tuoi file, un gestore di pacchetti non li cancella alle tue spalle.

sudo systemctl stop uversion-server 2>/dev/null
sudo apt purge -y uversion-server

Non lanciare sudo apt autoremove --purge dopo questa disinstallazione. PostgreSQL è arrivato come dipendenza di questo pacchetto, quindi apt proporrà di rimuoverlo, e la sua stessa purga cancella tutti i database della macchina, compresi quelli che non hanno nulla a che vedere con uVersion. Il pacchetto mette dei paletti all'installazione, ma il comando resta da evitare.

2. Seguire la sequenza che la purga ha appena mostrato

Il database e la directory dei dati sono ancora lì, e i comandi per rimuoverli dipendono dalla tua macchina: ecco perché vengono calcolati e stampati a schermo invece che scritti qui.

Leggi ciò che la purga mostra: il seguito dipende dalla tua macchina. Lo script di disinstallazione guarda dove si trova realmente il tuo database, poi stampa a schermo la sequenza esatta di comandi per il tuo caso, percorsi e numero di versione compresi. Segui quella invece di una ricetta generica: un comando approssimativo distrugge o il database sbagliato, o niente del tutto.

Due trappole che questa sequenza evita, e che spiegano perché viene calcolata per te invece di copiata da una guida:

Un DROP DATABASE senza nominare il cluster mira al server di database sbagliato. Se hai risposto sì alla domanda sul database, il tuo vive in un cluster dedicato: il comando predefinito si rivolge al cluster di sistema, non trova nulla da eliminare, e ti lascia credere che sia fatto.
Un rm -rf della directory dei dati senza aver prima rimosso il cluster lascia un database fantasma ancora dichiarato al sistema, che fallisce a ogni avvio della macchina reclamando una directory che non esiste più. L'ordine conta: pg_dropcluster --stop, poi l'eliminazione della directory.

3. Eliminare il kit di ripristino

Da fare se il disco deve uscire dal tuo controllo (rivendita, restituzione di un noleggio, rottamazione): questa directory contiene la tua chiave di licenza, il segreto JWT e la password del database, e sopravvive alla purga per costruzione.

sudo rm -rf <data-dir>/recovery

4. Assicurarsi che l'account di sistema sia sparito

Normalmente è già rimosso dalla purga. Il comando non ha effetto se è scomparso:

sudo deluser --system uversion 2>/dev/null || true

5. Verificare che non resti nulla

Quattro controlli, ognuno con ciò che devi leggere accanto:

systemctl status uversion-server         # "not-found" ou "inactive"
ls /etc/uversion 2>&1                    # "No such file"
id uversion                              # "no such user"
sudo -u postgres psql -tAc "SELECT 1 FROM pg_database WHERE datname='uversion';"   # (vide)