Wiki

Installer sur Ubuntu / Debian

Paquet .deb : les trois questions, le dossier de données, l'installation hors ligne, la sauvegarde et la désinstallation.

Ubuntu 24.04+, Debian 13+ (x86_64). Deux commandes, trois questions.

Installer

1. Télécharger le paquet

Depuis la machine qui hébergera le serveur, en session ordinaire :

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

L'URL _latest_ pointe toujours vers la dernière version publiée. Le drapeau -N dit à wget de ne re-télécharger que si le fichier distant est plus récent : utile pour mettre à jour sans accumuler des copies .deb.1, .deb.2, etc. cd /tmp évite un avertissement apt cosmétique (« unsandboxed as root ») quand le .deb est dans votre dossier personnel.

2. Lancer l'installation

Une seule commande, dans le dossier où vous venez de télécharger le paquet :

sudo apt install ./uversion-server_latest_amd64.deb

L'installateur pose alors trois questions, dans l'ordre des trois étapes suivantes. Elles s'affichent dans un dialogue bleu en plein écran : vous vous déplacez avec Tab et validez avec Entrée.

3. Répondre : le dossier de données

Défaut : /var/lib/uversion. C'est là qu'atterrit le contenu de vos fichiers versionnés, donc le dossier qui grossit, donc celui que vous voulez sur votre grand disque. Tous les chemins ne sont pas acceptés : la section Choisir un dossier de données donne les quatre règles, et l'installateur refuse en nommant la règle enfreinte.

La premiere question de l installateur Debian, dans un dialogue bleu plein ecran : le chemin du dossier de donnees, prerempli avec /var/lib/uversion.

4. Répondre : mettre aussi la base sur le dossier de données ?

Défaut : non. C'est la question la plus lourde de conséquences de l'installation, et ce défaut a un coût qu'il faut connaître avant de le laisser tel quel.

Cette réponse décide si un seul disque suffit à remonter votre serveur.

Non (défaut) : la base PostgreSQL reste dans le dossier système (/var/lib/postgresql), séparée de vos données. Si la machine meurt, le disque de données survivant contient le contenu des fichiers, mais plus aucune révision, aucun compte, aucun verrou et aucune permission. Ce n'est pas un serveur que l'on redémarre : c'est un tas d'octets.
Oui : l'installateur crée une base dédiée à l'intérieur du dossier de données, et y écrit une procédure de récupération. Un seul disque survivant, plus PostgreSQL et ce paquet, suffisent alors à reconstruire le serveur sur une autre machine.

Deux contreparties à connaître avant de répondre oui. Ce dossier de base ne peut être rouvert que par la version majeure de PostgreSQL qui l'a créé, donc une reconstruction dans plusieurs années peut demander d'installer explicitement cette version. Et le disque porte alors aussi la clé de licence, le secret JWT et le mot de passe de la base : traitez-le comme un secret. Cette réponse se change plus tard avec sudo dpkg-reconfigure uversion-server.

5. Répondre : le code d'activation

Obligatoire, sauf si une licence est déjà présente sur la machine ou sur le disque choisi à l'étape 3 : dans ce cas l'installateur vous l'annonce dans un message dédié et ne pose pas la question, parce qu'un code d'activation est à usage unique et que le vôtre a déjà été consommé par la machine d'où vient ce disque.

Le champ accepte trois formes, ce qui est votre porte de sortie si la machine n'a pas Internet : le code court UV-XXXX-XXXX-XXXX, un chemin absolu vers un fichier contenant votre clé de licence complète, ou cette clé complète collée directement (une longue chaîne commençant par eyJ). Avec la première forme seulement, l'installateur contacte licence.uversion.io pour échanger le code contre la clé complète.

6. Noter ce qui s'affiche à la fin

L'installation se termine sur un encadré coloré : identifiant admin, mot de passe temporaire, adresse du serveur et empreinte du certificat. Notez-les : le fichier qui contient ce mot de passe est supprimé dès que vous le changez.

Le récapitulatif affiché en fin d'installation : identifiant admin, mot de passe temporaire et adresse du serveur.

Vous pouvez ensuite suivre Premier login.

Une installation interrompue se relance sans risque. Si vous coupez la fenêtre, si le réseau tombe ou si l'installateur s'arrête sur une erreur, relancez simplement la même commande apt install. Votre code d'activation n'est pas reperdu : dès qu'il a été échangé, la clé obtenue est écrite sur le disque et réutilisée aux tentatives suivantes. Et pour revenir sur n'importe quelle réponse après coup, sans réinstaller : sudo dpkg-reconfigure uversion-server. C'est la commande de rattrapage universelle de cette page.

Choisir un dossier de données que l'installateur acceptera

Quatre règles. Les trois premières sont vérifiées avant que votre code d'activation ne soit consommé, donc un refus ne vous coûte rien : vous corrigez et vous recommencez.

Ni sous /home, ni sous /root. Le serveur tourne sous un compte système volontairement privé de tout accès aux dossiers personnels : il ne pourrait jamais lire ni écrire là, et ne démarrerait pas.
Aucun espace dans le chemin. Le chemin est recopié tel quel dans les réglages du service, où un espace sépare deux valeurs. Un disque externe monté automatiquement sous un nom comme /media/jean/My Book tombe exactement là-dessus.
Un chemin absolu, c'est-à-dire commençant par /.
Chaque dossier parent doit laisser passer les comptes uversion et postgres. C'est le piège le moins évident, et il ne se voit pas quand on installe en tant que root : un dossier parent créé à la main et fermé (par exemple un /perforce en root:root 0750, hérité d'un dépôt Helix) laisse passer toute l'installation, puis bloque le service au premier accès. Le symptôme est un service qui refuse de démarrer avec status=200/CHDIR, ou un « Permission denied » à la première écriture.

Pour vérifier ce dernier point avant de lancer l'installation, affichez les permissions de toute la chaîne de dossiers menant à votre choix :

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

Chaque ligne doit porter un x dans la dernière colonne de permissions (celle des « autres »). S'il en manque un, l'installateur vous nomme le dossier fautif et la commande exacte à passer, du type sudo chmod o+x /le/dossier. Il ne modifie jamais lui-même un dossier qui ne lui appartient pas : ouvrir un accès sur votre arborescence est votre décision, pas la sienne.

Où vont les fichiers

Deux emplacements, et un seul des deux vous suit si vous changez le dossier de données.

Dans le dossier de données (celui de la question 1) : le contenu de vos fichiers versionnés (sous data/chunks), le certificat TLS et son empreinte (sous data/tls), l'identité du serveur (server-id, last-validated-at), le mot de passe administrateur initial (initial-admin-password, effacé dès que vous le changez), la base PostgreSQL (pgdata) et le kit de récupération (recovery) si vous avez répondu oui à la question 2.

Dans /etc/uversion/, qui ne bouge jamais : le fichier de configuration config.toml, la copie nue de la clé de licence (licence-key) et le mot de passe de la base (db-password).

Toutes les commandes de cette page utilisent <data-dir> à la place d'un chemin en dur, parce que ce chemin est celui que vous avez choisi. Pour lire la vraie valeur sur une machine déjà installée :

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

Vérifier l'installation

Trois contrôles indépendants, à passer dans cet ordre : le service tourne, il écoute, et il n'a rien signalé.

1. Le service tourne

systemctl status uversion-server

Attendu : active (running). Toute autre valeur renvoie au dépannage.

2. Le serveur écoute en HTTPS sur 8443

ss -tlnp | grep 8443

Une ligne doit apparaître. Si rien ne sort alors que le service tourne, c'est en général que TLS a été désactivé dans la configuration : le serveur passe alors en HTTP simple et 8443 n'écoute plus du tout.

3. Les journaux ne montrent pas d'erreur

sudo journalctl -u uversion-server -n 50

journalctl est le lecteur de journaux du système : c'est là que le serveur écrit ce qu'il fait, et le premier endroit à regarder quand quelque chose ne démarre pas.

Réafficher l'empreinte du certificat

En remplaçant <data-dir> par la valeur lue plus haut :

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

Réafficher le mot de passe administrateur initial

Tant qu'il n'a pas été changé, il est encore sur le disque :

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

« No such file or directory » ici veut dire que le mot de passe a déjà été changé : c'est le comportement attendu, le fichier est supprimé à ce moment-là.

Installation non interactive et hors ligne

Deux besoins différents, une même mécanique : préremplir les réponses avant de lancer apt, de sorte qu'aucune question ne s'affiche. Le système qui stocke ces réponses s'appelle debconf, et il se pilote en ligne de commande.

1. Préremplir les trois réponses

Une ligne par question, exactement les trois de l'installation interactive :

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. Installer sans dialogue

Les réponses étant déjà en place, l'installation ne pose plus rien :

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

Variante hors ligne : donner la clé au lieu du code

Sur un réseau sans accès à Internet, le code d'activation ne peut pas être échangé : il n'y a personne à joindre. Récupérez alors votre clé de licence complète depuis votre espace compte sur un poste connecté, déposez-la sur la machine, et donnez le chemin du fichier à la place du code, à l'étape 1 ci-dessus. C'est la seule porte de sortie, et elle est prévue :

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

Le fichier doit contenir la clé seule, sur une ligne, sans guillemets ni autre contenu autour. Un config.toml entier pointé par erreur est refusé explicitement. Troisième forme possible, si vous préférez ne pas déposer de fichier : coller la clé complète directement dans la valeur, à la place du chemin.

Sauvegarder avant toute opération risquée

Trois choses à copier, et elles ne se sauvegardent pas de la même façon : la base de données (comptes, révisions, verrous, permissions), le dossier de données (le contenu des fichiers) et la configuration, qui vit ailleurs et qui est celle qu'on oublie.

1. La base de données

Elle se sauvegarde en tant que compte postgres, jamais en tant que root : PostgreSQL n'a pas de « rôle » (son mot pour un compte de base de données) nommé root, donc la commande lancée directement en root échoue avec un message qui ressemble à une panne alors que c'est une question d'identité.

Si vous avez répondu non à la question sur la base (le défaut), elle vit dans le cluster système :

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

Si vous avez répondu oui, elle vit dans un cluster séparé, qu'il faut nommer explicitement, sinon vous sauvegardez le mauvais :

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

2. Le dossier de données

Service arrêté, pour une copie cohérente :

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

3. La configuration

/etc/uversion/ ne suit pas le dossier de données et n'est pas dans la base : il porte la clé de licence, le secret qui signe les sessions et le mot de passe de la base. Sans lui, une restauration sur machine neuve repart avec un secret neuf, donc toute l'équipe est déconnectée d'un coup, et il faut redemander une licence.

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

Désinstaller

Attention : ces commandes suppriment vos dépôts, l'historique, les comptes utilisateurs et les configurations. Faites d'abord la sauvegarde de la section précédente si vous voulez pouvoir revenir en arrière.

1. Purger le paquet

La purge retire le binaire, le service, les réponses de configuration, /etc/uversion/ et le compte système uversion. Elle préserve volontairement la base de données et le dossier de données : ce sont vos fichiers, un gestionnaire de paquets ne les efface pas dans votre dos.

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

Ne lancez pas sudo apt autoremove --purge derrière cette désinstallation. PostgreSQL est arrivé comme dépendance de ce paquet, apt va donc proposer de le retirer, et sa propre purge efface toutes les bases de la machine, y compris celles qui n'ont rien à voir avec uVersion. Le paquet pose des garde-fous à l'installation, mais la commande reste à éviter.

2. Suivre la séquence que la purge vient d'afficher

La base et le dossier de données sont toujours là, et les commandes pour les retirer dépendent de votre machine : c'est pourquoi elles sont calculées et imprimées à l'écran plutôt qu'écrites ici.

Lisez ce que la purge affiche : la suite dépend de votre machine. Le script de désinstallation regarde où se trouve réellement votre base, puis imprime à l'écran la séquence de commandes exacte pour votre cas, chemins et numéro de version compris. Suivez celle-là plutôt qu'une recette générique : une commande approximative détruit soit la mauvaise base, soit rien du tout.

Deux pièges que cette séquence évite, et qui expliquent pourquoi elle est calculée pour vous plutôt que copiée d'un guide :

Un DROP DATABASE sans nommer le cluster vise le mauvais serveur de base. Si vous avez répondu oui à la question sur la base, la vôtre vit dans un cluster dédié : la commande par défaut s'adresse au cluster système, ne trouve rien à supprimer, et vous laisse croire que c'est fait.
Un rm -rf du dossier de données sans avoir d'abord retiré le cluster laisse une base fantôme toujours déclarée auprès du système, qui échoue à chaque démarrage de la machine en réclamant un dossier qui n'existe plus. L'ordre compte : pg_dropcluster --stop, puis la suppression du dossier.

3. Supprimer le kit de récupération

À faire si le disque doit quitter votre contrôle (revente, retour de location, mise au rebut) : ce dossier contient votre clé de licence, le secret JWT et le mot de passe de la base, et il survit à la purge par construction.

sudo rm -rf <data-dir>/recovery

4. S'assurer que le compte système est parti

Il est normalement déjà retiré par la purge. La commande est sans effet s'il a disparu :

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

5. Vérifier qu'il ne reste rien

Quatre contrôles, chacun avec ce que vous devez lire en face :

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)