STP/README.md

STP — Sistema de Transferencia Personal

Automatiza la configuración completa de una máquina Ubuntu LTS nueva: paquetes, PPAs, dotfiles, claves SSH, audio, drivers de video, servicios systemd y configuraciones de aplicaciones.

Los archivos (documentos, fotos, etc.) los maneja Nextcloud por separado. El STP se ocupa del entorno del usuario.

---

Primeros pasos en una máquina nueva

Opción A — ejecución directa:

bash <(curl -fsSL https://gitea.mateosaldain.uy/mateo/stp/raw/branch/main/bootstrap.sh)

Opción B — manual:

curl -fsSLo bootstrap.sh https://gitea.mateosaldain.uy/mateo/stp/raw/branch/main/bootstrap.sh
bash bootstrap.sh

El bootstrap.sh instala git, curl y otras dependencias base si no están disponibles, clona el repo en ~/.stp (configurable con stpDir), y lanza stp.sh.

Durante la ejecución se pedirá la contraseña de las claves SSH cifradas por consola (módulo ssh) y permisos de administrador para restaurar impresoras (módulo cups).

Después de que termine, reiniciá el gestor de audio para que los auriculares Bluetooth queden como dispositivo por defecto:

systemctl --user restart wireplumber

---

Comandos principales

# Ejecutar todos los módulos en orden
bash stp.sh

# Ejecutar un solo módulo
bash stp.sh --module registry

# Saltear módulos específicos
bash stp.sh --skip ssh

# Ver módulos disponibles (en orden de ejecución)
bash stp.sh --list

# Salida detallada (muestra también los ítems ya instalados)
bash stp.sh --verbose

El STP es idempotente: verifica el estado antes de actuar. Ejecutarlo varias veces es seguro.

---

Orden de ejecución de módulos

El orden está definido en config/modules (un módulo por línea, # para comentarios).

Módulo	Qué hace
bootstrap	Instala yq y age (requeridos por los demás módulos)
ssh	Descifra e instala claves SSH en ~/.ssh
registry	Aplica todo lo declarado en config/registry.yaml
thunderbird	Instala Thunderbird (snap) y restaura el perfil
claudeCode	Configura el repositorio apt de Anthropic e instala claude-code
easyEffects	Restaura configuración y presets de EasyEffects
wireplumber	Restaura el estado de audio: dispositivo Bluetooth por defecto, perfiles, volúmenes por app
cups	Restaura las impresoras configuradas y sus drivers PPD

---

Configuraciones actualmente guardadas

Paquetes (via registro)

ID	Tipo	Paquete
curl, wget, git, vim, htop, tree, unzip	apt	igual al ID
buildEssential	apt	build-essential
virtualbox	apt	virtualbox
dbeaverCe	snap	dbeaver-ce
vscodium	flatpak	com.vscodium.codium
filezilla	flatpak	org.filezillaproject.Filezilla
angryIpScanner	flatpak	org.angryip.ipscan
anydesk	flatpak	com.anydesk.Anydesk
bitwarden	flatpak	com.bitwarden.desktop
bottles	flatpak	com.usebottles.bottles
bruno	flatpak	com.usebruno.Bruno
nextcloudDesktop	flatpak	com.nextcloud.desktopclient.nextcloud
easyEffects	flatpak	com.github.wwmm.easyeffects
flatseal	flatpak	com.github.tchx84.Flatseal
warehouse	flatpak	io.github.flattool.Warehouse
freecad	flatpak	org.freecad.FreeCAD
hidamari	flatpak	io.github.jeffshee.Hidamari
inkscape	flatpak	org.inkscape.Inkscape
libreoffice	flatpak	org.libreoffice.LibreOffice
logseq	flatpak	com.logseq.Logseq
obsStudio	flatpak	com.obsproject.Studio
openshot	flatpak	org.openshot.OpenShot

Configuraciones de aplicaciones (via módulos)

Módulo	Archivo	Qué se restaura
ssh	secrets/sshKeys.tar.gz.age	Claves SSH con permisos correctos
thunderbird	secrets/thunderbirdProfile.zip	Cuentas, filtros y extensiones (excluye emails)
claudeCode	config/keys/claude-code.asc	Repositorio apt de Anthropic + paquete claude-code
easyEffects	secrets/easyEffectsConfig.zip	Configuración y presets de salida (HB-Flat, HB-Lite, HB-Mid, Heavy Bass)
wireplumber	secrets/wireplumberState.zip	Auriculares Bluetooth como salida por defecto, perfil A2DP, volúmenes por app
cups	secrets/cupsConfig.zip	5 impresoras: Epson L8050 WiFi, Canon MP230, Samsung M2020, POS80, Cups PDF

---

Actualizar una configuración guardada

Volvé a ejecutar el script de captura correspondiente y commiteá el archivo generado:

bash scripts/encryptSsh.sh           && git add secrets/sshKeys.tar.gz.age
bash scripts/thunderbird/capture.sh  && git add secrets/thunderbirdProfile.zip
bash scripts/easyEffects/capture.sh  && git add secrets/easyEffectsConfig.zip
bash scripts/wireplumber/capture.sh  && git add secrets/wireplumberState.zip
bash scripts/cups/capture.sh         && git add secrets/cupsConfig.zip

---

Agregar un paquete nuevo

Basta con agregar una entrada a config/registry.yaml. La próxima vez que corra el STP, detectará la nueva entrada y la aplicará.

# Desde Claude Code — agrega la entrada correctamente formateada
/addEntry neovim apt
/addEntry gimp flatpak appId=org.gimp.GIMP
/addEntry bashrc dotfile

O editá directamente config/registry.yaml:

registry:
  - id: neovim
    type: apt

  - id: vscode
    type: snap
    package: code
    classic: true

  - id: gimp
    type: flatpak
    appId: org.gimp.GIMP

  - id: bash
    type: dotfile

  - id: networkManager
    type: service
    scope: system
    state: enable

Tipos disponibles en el registro

Tipo	Qué hace
ppa	Agrega un repositorio PPA a apt
apt	Instala un paquete con apt (soporta minVersion / maxVersion)
snap	Instala un paquete snap
flatpak	Instala una aplicación Flatpak
dotfile	Enlaza todos los archivos de dotfiles/<id>/ a sus rutas en $HOME/
service	Habilita, deshabilita o mask un servicio systemd
pipewire	Instala y configura PipeWire como sistema de audio
video	Detecta la GPU y instala los drivers correspondientes
docker	Despliega archivos de configuración Docker desde docker/<id>/

---

Agregar una nueva configuración de aplicación

Para guardar y restaurar la configuración de una app nueva:

1. Crear scripts/<appName>/capture.sh — lee desde el directorio de datos de la app y genera un ZIP en secrets/
2. Crear modules/<appName>.sh — verifica si la app está instalada y si ya hay config; si no, restaura desde el ZIP
3. Agregar <appName> en config/modules después de registry
4. Ejecutar bash scripts/<appName>/capture.sh en la máquina actual
5. Commitear el archivo generado en secrets/

La restauración es automática en el próximo stp.sh. Si la config ya existe en la máquina destino, el módulo la saltea.

# Desde Claude Code — genera la estructura completa
/new-module nombreApp

---

Dotfiles

Cada aplicación tiene su propia carpeta dentro de dotfiles/. Dentro de esa carpeta, los archivos respetan la misma ruta que tendrían en $HOME/:

dotfiles/
├── bash/
│   └── .bashrc
├── git/
│   ├── .gitconfig
│   └── .gitignore_global
└── neovim/
    └── .config/
        └── nvim/
            └── init.lua

Para activar una carpeta, basta con agregar una entrada en el registro:

- id: bash
  type: dotfile

- id: neovim
  type: dotfile

El STP recorre todos los archivos de dotfiles/bash/ y crea un enlace simbólico por cada uno en su ruta equivalente dentro de $HOME/. Si un archivo ya existe, guarda una copia con extensión .stpbackup antes de reemplazarlo.

---

Claves SSH

Las claves se almacenan cifradas en el repo como secrets/sshKeys.tar.gz.age. El archivo está cifrado con age usando una contraseña y es seguro hacer commit de él.

Cifrar las claves actuales (correr en la máquina con las claves):

bash scripts/encryptSsh.sh
# → genera secrets/sshKeys.tar.gz.age
git add secrets/sshKeys.tar.gz.age && git commit -m "update ssh keys"

Verificar el cifrado antes de hacer commit:

age --decrypt secrets/sshKeys.tar.gz.age | tar -tzv

Durante la ejecución del STP, el módulo ssh pide la contraseña, descifra el archivo e instala las claves en ~/.ssh con los permisos correctos. Las claves que ya existen se saltean sin sobrescribir.

---

Variables de entorno

Variable	Predeterminado	Efecto
stpDir	~/.stp	Directorio de clonado (bootstrap)
stpLogFile	/tmp/stp-<timestamp>.log	Ruta del log completo