Onboarding de Máquinas

Esta guía detalla el procedimiento exacto para incorporar una máquina nueva (laptop, desktop o máquina virtual Arch Linux con Omarchy) al repositorio personal.

Una vez completado este proceso de 7 pasos, la máquina quedará vinculada permanentemente y recibirá todas las personalizaciones a través del comando estándar omarchy update.

Importante: No saltes pasos. Los pasos 5 y 6 son críticos: sin ellos la máquina queda con los paquetes instalados pero los launchers, stubs y configuraciones de usuario no se materializan en $HOME. omarchy update no re-provisiona un $HOME existente por diseño (ADR-009).

Procedimiento Manual en 7 Pasos

Paso 1: Importar y firmar localmente la clave GPG del repositorio

El repositorio personal firma criptográficamente cada paquete y la base de datos omarchy.db. Para que pacman confíe en el repositorio, descarga la clave pública e impórtala en el llavero del sistema:

# Descargar la clave pública oficial del repositorio
curl -fsSL https://robert-flo.github.io/omarchy-personal-repo/keys/omarchy-personal-repo.pub.asc -o /tmp/omarchy-personal-repo.pub.asc

# Importar y confiar localmente en la clave (ID: 76AFFCC217DB9FC4)
sudo pacman-key --add /tmp/omarchy-personal-repo.pub.asc
sudo pacman-key --lsign-key 76AFFCC217DB9FC4
rm -f /tmp/omarchy-personal-repo.pub.asc

Nota: La huella dactilar (fingerprint) canónica de la clave RSA 4096-bit es: CD92 AB07 B1D2 4DC9 A74E B60E 76AF FCC2 17DB 9FC4

Consulta el Estado Actual del Sistema para verificar que este ID es el vigente antes de importar.

Paso 2: Instalar el par personal por primera vez (bootstrap sin repo configurado)

Descarga e instala directamente el par personal desde el CDN antes de registrar el repositorio en pacman.conf. Esto garantiza que el par personal tenga prioridad desde el primer pacman -Syu:

REPO="https://robert-flo.github.io/omarchy-personal-repo/stable/x86_64"
# Consulta reference/historial-cambios para la versión actual del par
VER="<versión-actual>"

curl -O "$REPO/omarchy-${VER}-any.pkg.tar.zst"
curl -O "$REPO/omarchy-${VER}-any.pkg.tar.zst.sig"
curl -O "$REPO/omarchy-settings-${VER}-any.pkg.tar.zst"
curl -O "$REPO/omarchy-settings-${VER}-any.pkg.tar.zst.sig"

sudo pacman -U omarchy-${VER}-any.pkg.tar.zst \
               omarchy-settings-${VER}-any.pkg.tar.zst

Nota: Este paso garantiza que el par personal (pkgrel=99+) esté instalado antes de que pacman -Syu pueda instalar el par oficial (pkgrel=1). Sin este paso, el paso 3 podría instalar el par oficial primero.

Paso 3: Repositorio personal en pacman (fork con Omarchy instalado)

En máquinas que ya consumen el par del fork, no edites default/pacman/pacman-stable.conf ni pegues el bloque a mano salvo emergencia. El fork despliega la sección [omarchy-personal] con un hook en omarchy refresh pacman (ADR-003, PR #78):

  1. omarchy update — la migración 1791380000.sh instala pre-refresh-pacman.d/omarchy-personal-repo en ~/.config/omarchy/hooks/.
  2. sudo omarchy refresh pacman — copia la plantilla upstream y el hook inserta el snippet inmediatamente antes de [omarchy].

Comprueba:

grep -n '^\[omarchy' /etc/pacman.conf
# Debe verse [omarchy-personal] en la línea anterior a [omarchy]

Bootstrap sin sección [omarchy] aún (Arch puro, antes del paquete Omarchy): el script de bootstrap o un sed ante [core] registra el CDN para el pacman -U del paso 2; tras instalar Omarchy del fork, el paso 4 vuelve a ser la fuente de verdad.

Paso 4: Sincronizar la configuración de pacman

sudo omarchy refresh pacman

Reescribe /etc/pacman.conf desde la plantilla upstream y aplica el hook del repositorio personal; luego sincroniza bases de datos.

Paso 5: Actualizar vía omarchy update

Ejecuta la actualización completa para que todas las personalizaciones del par queden instaladas y sincronizadas:

omarchy update

Paso 6: Provisionar el entorno de usuario (CRÍTICO)

Este paso es obligatorio. omarchy update instala los paquetes en el sistema pero no materializa automáticamente launchers, stubs y configuraciones en el $HOME de usuarios existentes (por diseño, ADR-009).

Ejecuta el provisioning forzado para materializar todos los archivos del par en tu $HOME:

omarchy provision user --force

Esto crea:

  • Launchers .desktop en ~/.local/share/applications/
  • Stubs y wrappers de mise en ~/.local/bin/
  • Configuraciones de usuario en ~/.config/
  • El directorio de trabajo ~/src si algún launcher lo requiere

Luego, reconcilia el conjunto de paquetes del sistema para instalar todo lo declarado en el fork:

omarchy reinstall pkgs

Paso 7: Verificar la instalación

Comprueba que la máquina está consumiendo la versión personal correcta:

pacman -Q omarchy omarchy-settings

Resultado esperado: Ambos paquetes deben reportar una versión con sufijo -99 o superior (por ejemplo: omarchy 4.0.4-99 y omarchy-settings 4.0.4-99).

También puedes comprobar el empaquetador oficial:

pacman -Qi omarchy | grep "Packager"
# Salida esperada: Packager : Roberto Flores <25asab015@ujmd.edu.sv>

Script Automatizado de Bootstrap

Si prefieres aprovisionar una máquina con una sola línea de comandos desatendida, puedes ejecutar el script de bootstrap oficial:

curl -fsSL https://raw.githubusercontent.com/robert-flo/fork-docs/main/scripts/bootstrap-omarchy-machine.sh | bash

Este script realiza automáticamente todos los 7 pasos del procedimiento manual:

  1. Verificación de permisos de superusuario (sudo).
  2. Descarga e importación segura de la clave pública GPG con validación de huella.
  3. Instalación bootstrap del par personal directamente desde el CDN.
  4. Registro bootstrap de [omarchy-personal] en /etc/pacman.conf (ante [omarchy] si existe, si no ante [core]).
  5. Sincronización de pacman (pacman -Sy; en máquinas con Omarchy del fork, ejecuta además omarchy update + omarchy refresh pacman para el hook ADR-003).
  6. Ejecución de omarchy update.
  7. Provisioning del entorno de usuario (omarchy provision user --force + omarchy reinstall pkgs).

Configuración Especial para Estaciones de Desarrollo (Máquinas DEV)

Si la máquina que estás configurando es una estación de trabajo de desarrollo (como gracie) donde trabajarás sobre el código fuente de fo-omarchy y compilarás paquetes locales con omarchy dev pkg-test:

  1. Blindaje de pacman.conf:
    Debes proteger la estación para que las actualizaciones periódicas del sistema (pacman -Syu o yay) no sobrescriban tus paquetes de prueba dev.<sha> con las versiones oficiales de pkgs.omarchy.org/edge: 
    sudo sed -i '/^HoldPkg =/a IgnorePkg = omarchy-dev omarchy-settings-dev' /etc/pacman.conf
  2. Reempaquetado limpio en lockstep:
    Nunca modifiques /usr/share/omarchy/ a mano. Para instalar y validar tus cambios locales en el sistema, corre siempre: 
    omarchy dev pkg-test

    Esto compila e instala en lockstep los paquetes omarchy-dev y omarchy-settings-dev desde el commit local más reciente.

Last updated: