Wiki

Instalar en Ubuntu / Debian

El paquete .deb: las tres preguntas, el directorio de datos, la instalación sin conexión, la copia de seguridad y la desinstalación.

Ubuntu 24.04+, Debian 13+ (x86_64). Dos comandos, tres preguntas.

Instalar

1. Descargar el paquete

Desde la máquina que alojará el servidor, en una sesión normal:

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

La URL _latest_ siempre apunta a la versión publicada más reciente. El flag -N le indica a wget que vuelva a descargar solo si el archivo remoto es más nuevo: útil para actualizar sin acumular copias .deb.1, .deb.2, etc. cd /tmp evita una advertencia cosmética de apt ("unsandboxed as root") cuando el .deb está en tu directorio home.

2. Iniciar la instalación

Un solo comando, en el directorio donde acabas de descargar el paquete:

sudo apt install ./uversion-server_latest_amd64.deb

El instalador plantea entonces tres preguntas, en el orden de los tres pasos siguientes. Aparecen en un diálogo azul a pantalla completa: te desplazas con Tab y confirmas con Intro.

3. Responder: el directorio de datos

Predeterminado: /var/lib/uversion. Aquí es donde aterriza el contenido de tus archivos versionados, así que es el directorio que crece, y por tanto el que quieres en tu disco grande. No se aceptan todas las rutas: la sección Elegir un directorio de datos da las cuatro reglas, y el instalador rechaza nombrando la regla infringida.

La primera pregunta del instalador de Debian, en un diálogo azul a pantalla completa: la ruta del directorio de datos, precargada con /var/lib/uversion.

4. Responder: ¿poner también la base de datos en el directorio de datos?

Predeterminado: no. Es la pregunta de mayor calado de la instalación, y este valor por defecto tiene un coste que conviene conocer antes de dejarlo tal cual.

Esta respuesta decide si un solo disco basta para reconstruir tu servidor.

No (predeterminado): la base de datos PostgreSQL se queda en el directorio del sistema (/var/lib/postgresql), separada de tus datos. Si la máquina muere, el disco de datos que sobrevive contiene el contenido de los archivos, pero ninguna revisión, ninguna cuenta, ningún bloqueo y ningún permiso. No es un servidor que se reinicie: es un montón de bytes.
Sí: el instalador crea una base de datos dedicada dentro del directorio de datos y escribe allí un procedimiento de recuperación. Un solo disco superviviente, más PostgreSQL y este paquete, bastan entonces para reconstruir el servidor en otra máquina.

Dos contrapartidas que conocer antes de responder sí. Este directorio de base de datos solo puede reabrirse con la versión mayor de PostgreSQL que lo creó, de modo que una reconstrucción dentro de varios años puede exigir instalar explícitamente esa versión. Y el disco lleva entonces también la clave de licencia, el secreto JWT y la contraseña de la base de datos: trátalo como un secreto. Esta respuesta se cambia más tarde con sudo dpkg-reconfigure uversion-server.

5. Responder: el código de activación

Obligatorio, salvo que ya haya una licencia en la máquina o en el disco elegido en el paso 3: en ese caso el instalador te lo anuncia en un mensaje específico y no plantea la pregunta, porque un código de activación es de un solo uso y el tuyo ya ha sido consumido por la máquina de la que proviene ese disco.

El campo acepta tres formas, que es tu salida si la máquina no tiene Internet: el código corto UV-XXXX-XXXX-XXXX, una ruta absoluta a un archivo que contenga tu clave de licencia completa, o esa clave completa pegada directamente (una cadena larga que empieza por eyJ). Solo con la primera forma, el instalador contacta con licence.uversion.io para canjear el código por la clave completa.

6. Anotar lo que aparece al final

La instalación termina con un recuadro de color: usuario admin, contraseña temporal, dirección del servidor y huella del certificado. Anótalos: el archivo que contiene esta contraseña se elimina en cuanto la cambias.

El resumen que se muestra al final de la instalación: usuario admin, contraseña temporal y dirección del servidor.

Después puedes seguir Primer inicio de sesión.

Una instalación interrumpida se reanuda sin riesgo. Si cierras la ventana, si se cae la red o si el instalador se detiene en un error, simplemente vuelve a lanzar el mismo comando apt install. Tu código de activación no se vuelve a perder: en cuanto ha sido canjeado, la clave obtenida se escribe en el disco y se reutiliza en los intentos siguientes. Y para volver sobre cualquier respuesta después, sin reinstalar: sudo dpkg-reconfigure uversion-server. Es el comando de rescate universal de esta página.

Elegir un directorio de datos que el instalador acepte

Cuatro reglas. Las tres primeras se comprueban antes de que se consuma tu código de activación, así que un rechazo no te cuesta nada: corriges y vuelves a empezar.

Ni bajo /home, ni bajo /root. El servidor se ejecuta con una cuenta de sistema privada deliberadamente de todo acceso a los directorios personales: no podría nunca leer ni escribir ahí, y no arrancaría.
Ningún espacio en la ruta. La ruta se copia tal cual en los ajustes del servicio, donde un espacio separa dos valores. Un disco externo montado automáticamente con un nombre como /media/jean/My Book cae exactamente en esto.
Una ruta absoluta, es decir, que empiece por /.
Cada directorio padre debe dejar pasar a las cuentas uversion y postgres. Es la trampa menos evidente, y no se ve cuando se instala como root: un directorio padre creado a mano y cerrado (por ejemplo un /perforce en root:root 0750, heredado de un depósito Helix) deja pasar toda la instalación y luego bloquea el servicio en el primer acceso. El síntoma es un servicio que se niega a arrancar con status=200/CHDIR, o un "Permission denied" en la primera escritura.

Para comprobar este último punto antes de lanzar la instalación, muestra los permisos de toda la cadena de directorios que lleva a tu elección:

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

Cada línea debe llevar una x en la última columna de permisos (la de los "otros"). Si falta alguna, el instalador te nombra el directorio culpable y el comando exacto que ejecutar, del tipo sudo chmod o+x /le/dossier. Nunca modifica él mismo un directorio que no le pertenece: abrir un acceso en tu árbol es tu decisión, no la suya.

Dónde van los archivos

Dos ubicaciones, y solo una de las dos te sigue si cambias el directorio de datos.

En el directorio de datos (el de la pregunta 1): el contenido de tus archivos versionados (bajo data/chunks), el certificado TLS y su huella (bajo data/tls), la identidad del servidor (server-id, last-validated-at), la contraseña inicial de administrador (initial-admin-password, borrada en cuanto la cambias), la base de datos PostgreSQL (pgdata) y el kit de recuperación (recovery) si respondiste sí a la pregunta 2.

En /etc/uversion/, que no se mueve nunca: el archivo de configuración config.toml, la copia desnuda de la clave de licencia (licence-key) y la contraseña de la base de datos (db-password).

Todos los comandos de esta página usan <data-dir> en lugar de una ruta fija, porque esa ruta es la que tú elegiste. Para leer el valor real en una máquina ya instalada:

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

Verificar la instalación

Tres comprobaciones independientes, a pasar en este orden: el servicio funciona, escucha, y no ha señalado nada.

1. El servicio funciona

systemctl status uversion-server

Esperado: active (running). Cualquier otro valor remite a la resolución de problemas.

2. El servidor escucha en HTTPS en 8443

ss -tlnp | grep 8443

Debe aparecer una línea. Si no sale nada mientras el servicio funciona, suele ser que TLS se ha desactivado en la configuración: el servidor pasa entonces a HTTP simple y 8443 deja de escuchar por completo.

3. Los registros no muestran ningún error

sudo journalctl -u uversion-server -n 50

journalctl es el lector de registros del sistema: es donde el servidor escribe lo que hace, y el primer lugar que mirar cuando algo no arranca.

Volver a mostrar la huella del certificado

Reemplazando <data-dir> por el valor leído más arriba:

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

Volver a mostrar la contraseña inicial de administrador

Mientras no se haya cambiado, sigue en el disco:

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

"No such file or directory" aquí significa que la contraseña ya se ha cambiado: es el comportamiento esperado, el archivo se elimina en ese momento.

Instalación no interactiva y sin conexión

Dos necesidades distintas, un mismo mecanismo: rellenar de antemano las respuestas antes de lanzar apt, de modo que no aparezca ninguna pregunta. El sistema que almacena esas respuestas se llama debconf, y se maneja desde la línea de comandos.

1. Rellenar de antemano las tres respuestas

Una línea por pregunta, exactamente las tres de la instalación interactiva:

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. Instalar sin diálogo

Como las respuestas ya están puestas, la instalación no pregunta nada más:

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

Variante sin conexión: dar la clave en lugar del código

En una red sin acceso a Internet, el código de activación no puede canjearse: no hay nadie a quien contactar. Recupera entonces tu clave de licencia completa desde tu área de cuenta en un puesto conectado, colócala en la máquina y da la ruta del archivo en lugar del código, en el paso 1 de arriba. Es la única salida, y está prevista:

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

El archivo debe contener la clave sola, en una línea, sin comillas ni otro contenido alrededor. Un config.toml entero apuntado por error se rechaza explícitamente. Tercera forma posible, si prefieres no colocar un archivo: pegar la clave completa directamente en el valor, en lugar de la ruta.

Hacer una copia de seguridad antes de cualquier operación arriesgada

Tres cosas que copiar, y no se respaldan de la misma manera: la base de datos (cuentas, revisiones, bloqueos, permisos), el directorio de datos (el contenido de los archivos) y la configuración, que vive en otro sitio y que es la que se olvida.

1. La base de datos

Se respalda como la cuenta postgres, nunca como root: PostgreSQL no tiene ningún "rol" (su palabra para una cuenta de base de datos) llamado root, así que el comando lanzado directamente como root falla con un mensaje que parece una avería cuando es una cuestión de identidad.

Si respondiste no a la pregunta sobre la base de datos (el valor por defecto), vive en el clúster del sistema:

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

Si respondiste sí, vive en un clúster separado, que hay que nombrar explícitamente, o si no respaldas el equivocado:

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

2. El directorio de datos

Servicio detenido, para una copia coherente:

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

3. La configuración

/etc/uversion/ no sigue al directorio de datos y no está en la base de datos: lleva la clave de licencia, el secreto que firma las sesiones y la contraseña de la base de datos. Sin él, una restauración en una máquina nueva vuelve a empezar con un secreto nuevo, así que todo el equipo queda desconectado de golpe, y hay que volver a pedir una licencia.

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

Desinstalar

Atención: estos comandos eliminan tus repositorios, el historial, las cuentas de usuario y las configuraciones. Haz primero la copia de seguridad de la sección anterior si quieres poder volver atrás.

1. Purgar el paquete

La purga retira el binario, el servicio, las respuestas de configuración, /etc/uversion/ y la cuenta de sistema uversion. Preserva a propósito la base de datos y el directorio de datos: son tus archivos, un gestor de paquetes no los borra a tus espaldas.

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

No lances sudo apt autoremove --purge después de esta desinstalación. PostgreSQL llegó como dependencia de este paquete, así que apt propondrá retirarlo, y su propia purga borra todas las bases de datos de la máquina, incluidas las que no tienen nada que ver con uVersion. El paquete pone salvaguardas en la instalación, pero el comando sigue siendo de evitar.

2. Seguir la secuencia que la purga acaba de mostrar

La base de datos y el directorio de datos siguen ahí, y los comandos para retirarlos dependen de tu máquina: por eso se calculan y se imprimen en pantalla en lugar de escribirse aquí.

Lee lo que la purga muestra: lo que sigue depende de tu máquina. El script de desinstalación mira dónde está realmente tu base de datos, y luego imprime en pantalla la secuencia exacta de comandos para tu caso, rutas y número de versión incluidos. Sigue esa en lugar de una receta genérica: un comando aproximado destruye o bien la base de datos equivocada, o bien nada en absoluto.

Dos trampas que esta secuencia evita, y que explican por qué se calcula para ti en lugar de copiarse de una guía:

Un DROP DATABASE sin nombrar el clúster apunta al servidor de base de datos equivocado. Si respondiste sí a la pregunta sobre la base de datos, la tuya vive en un clúster dedicado: el comando por defecto se dirige al clúster del sistema, no encuentra nada que eliminar, y te deja creer que está hecho.
Un rm -rf del directorio de datos sin haber retirado antes el clúster deja una base de datos fantasma todavía declarada ante el sistema, que falla en cada arranque de la máquina reclamando un directorio que ya no existe. El orden importa: pg_dropcluster --stop, y luego la eliminación del directorio.

3. Eliminar el kit de recuperación

A hacer si el disco debe salir de tu control (reventa, devolución de alquiler, desecho): este directorio contiene tu clave de licencia, el secreto JWT y la contraseña de la base de datos, y sobrevive a la purga por construcción.

sudo rm -rf <data-dir>/recovery

4. Asegurarse de que la cuenta de sistema se ha ido

Normalmente ya está retirada por la purga. El comando no tiene efecto si ha desaparecido:

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

5. Comprobar que no queda nada

Cuatro comprobaciones, cada una con lo que debes leer al lado:

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)