MiniArch

Instaladores automatizados para crear kioskos de Arch Linux orientados a YARG (Yet Another Rhythm Game).

Caminos De Instalacion

MiniArch mantiene tres caminos basados en Cage:

install-cage-yarg.sh: camino recomendado para YARG. Instala Arch Linux, Cage, Wayland/XWayland, YARG, audio, Samba y la carpeta de canciones en un solo flujo.
install-cage-clonehero.sh: camino equivalente para Clone Hero. Instala Arch Linux, Cage, Wayland/XWayland, Clone Hero, audio, Samba y la carpeta de canciones en un solo flujo.
install-cage-kiosk.sh: camino minimalista. Instala Arch Linux, Cage y foot solamente, util como base de kiosko o terminal de mantenimiento.

En corto:

Recomendado: install-cage-yarg.sh
Clone Hero:  install-cage-clonehero.sh
Minimal:     install-cage-kiosk.sh

Cage es ideal para un equipo dedicado: ejecuta una sola aplicacion fullscreen y reduce la superficie de escritorio. El instalador tambien habilita XWayland para compatibilidad con builds de YARG que lo necesiten.

Estado Actual

install-cage-yarg.sh es un orquestador modular. Reutiliza los modulos compartidos de lib/ y mueve lo especifico a:

lib/cage.sh: sistema base Cage, usuario, servicio systemd y wrapper /usr/local/bin/run-yarg.sh.
lib/yarg.sh: descarga de YARG stable, stable-latest o nightly, settings iniciales, Samba, rendimiento y updater.
lib/clonehero.sh: descarga de Clone Hero desde GitHub, carpeta compartida de canciones, Samba, updater y wrapper /usr/local/bin/run-clonehero.sh.

install-cage-kiosk.sh conserva el particionado, GRUB, Plymouth opcional, red y limpieza del instalador, pero arranca directamente foot dentro de Cage.

Caracteristicas

Compartidas

Instalacion automatizada desde el live ISO de Arch Linux.
Validacion de entorno, red, disco y passwords.
Confirmacion antes de destruir particiones existentes.
Particionado GPT/UEFI:
- ESP FAT32 en /boot.
- Root ext4 en /.
- Swap.
- Home ext4 en /home.
GRUB UEFI con arranque silencioso.
Plymouth opcional.
PipeWire, WirePlumber, PipeWire Pulse, PipeWire ALSA, codecs y Bluetooth.
/etc/asound.conf apuntando ALSA default a PipeWire.
Limpieza automatica de montajes y swap si la instalacion falla.

Cage/YARG

install-cage-yarg.sh instala y configura:

Cage como compositor de kiosko.
Wayland y XWayland.
Mesa, Vulkan Intel/AMD y NVIDIA opcional.
DBus de sesion para el wrapper de YARG.
PipeWire iniciado en orden: pipewire, wireplumber, pipewire-pulse.
YARG en /opt/YARG.
Perfil persistente en YARG_PERSISTENT_DATA_DIR.
Carpeta de canciones fija en YARG_SONGS_DIR.
Enlace /opt/YARG/Songs apuntando a YARG_SONGS_DIR.
Share Samba YARG-Songs.
Usuario Samba para el usuario kiosko.
Reglas HID para instrumentos hidraw.
Dependencias multilib de YARG.
Limites de tiempo real, vm.swappiness=10 y cpupower en performance.
Updater /usr/local/bin/update-yarg.
Servicio cage-kiosk.service.

Cage/Clone Hero

install-cage-clonehero.sh instala y configura:

Cage como compositor de kiosko.
Wayland y XWayland.
Mesa, Vulkan Intel/AMD y NVIDIA opcional.
DBus de sesion para el wrapper de Clone Hero.
PipeWire iniciado en orden: pipewire, wireplumber, pipewire-pulse.
Clone Hero en /opt/CloneHero.
Perfil persistente en CLONEHERO_DATA_DIR.
Carpeta de canciones fija en CLONEHERO_SONGS_DIR.
Enlace /home/kiosk/Songs apuntando a la carpeta de canciones.
Share Samba CloneHero-Songs.
Usuario Samba para el usuario kiosko.
Reglas HID para instrumentos hidraw.
Updater /usr/local/bin/update-clonehero.
Descargador /home/kiosk/download-clonehero-songs.sh usando links.csv.
Servicio cage-kiosk.service.

Cage/foot

install-cage-kiosk.sh instala:

Cage como compositor de kiosko.
foot como aplicacion unica.
Servicio cage-kiosk.service.
SSH opcional.

Requisitos

Arch Linux ISO actual.
Maquina fisica o VM con UEFI habilitado.
Disco de al menos 16 GB.
2 GB de RAM o mas.
Conexion a internet durante la instalacion.
ImageMagick en el entorno live si vas a usar imagen personalizada de Plymouth.

En VM, habilita EFI/UEFI. En VirtualBox:

Sistema -> Placa base -> Habilitar EFI

En Proxmox, SPICE puede servir para probar audio virtual. En hardware real, PipeWire deberia usar la salida detectada por ALSA/WirePlumber.

Instalacion

Arranca desde el ISO de Arch Linux y verifica red:

ping -c 3 archlinux.org

Instalacion Manual

Clona el repositorio:

pacman -Sy git imagemagick
git clone https://github.com/Xalcker/MiniArch.git
cd MiniArch

Copia el ejemplo de configuracion si quieres una instalacion repetible:

cp .env.example .env
nano .env

Para Cage/YARG, .env es opcional. Si no existe, install-cage-yarg.sh pregunta lo necesario en modo asistido: usuario, passwords, hostname, timezone, red, disco, NVIDIA, canal/resolucion de YARG y menu de salida.

Si usas .env, define al menos:

DISK_DEVICE=ask
KIOSK_USER=kiosk
KIOSK_PASSWORD=una-contrasena-real
ROOT_PASSWORD=otra-contrasena-real
KIOSK_HOSTNAME=minikiosk
TIMEZONE=America/Phoenix
ENABLE_SSH=false
INSTALL_NVIDIA=false
ALLOW_INSECURE_DEFAULT_PASSWORD=false
ENABLE_PLYMOUTH=true
YARG_RELEASE_CHANNEL=ask
YARG_SONGS_DIR=/home/${KIOSK_USER}/Songs
YARG_PERSISTENT_DATA_DIR=/home/${KIOSK_USER}/.config/yarg-kiosk
YARG_RESOLUTION=ask
YARG_FORCE_SOFTWARE_RENDER=false
YARG_EXIT_MENU=always

Ejecuta el camino recomendado:

chmod +x install-cage-yarg.sh
./install-cage-yarg.sh

Clone Hero:

chmod +x install-cage-clonehero.sh
./install-cage-clonehero.sh

Cage/foot minimal:

chmod +x install-cage-kiosk.sh
./install-cage-kiosk.sh

Advertencia: ambos instaladores destruyen el disco seleccionado. Con DISK_DEVICE=ask, el instalador muestra un selector interactivo con los discos detectados, marca USB/removibles y pide confirmar escribiendo INSTALAR. Tambien acepta instalar. Tambien puedes fijar DISK_DEVICE manualmente, por ejemplo /dev/sda, /dev/nvme0n1 o /dev/vda; aun asi el instalador mostrara el selector para evitar errores antes de particionar.

Flujo De Cage/YARG

install-cage-yarg.sh ejecuta, en orden:

Carga .env si existe; si no existe, entra en modo asistido.
Pregunta valores faltantes o interactivos de la configuracion.
Muestra el selector de disco y confirma el destino.
Pregunta por NVIDIA si INSTALL_NVIDIA esta vacio.
Pregunta por canal de YARG si YARG_RELEASE_CHANNEL=ask.
Pregunta por resolucion de YARG si YARG_RESOLUTION=ask.
Valida entorno live, passwords, assets opcionales, red y disco.
Resuelve el release mas reciente si se eligio stable-latest o nightly.
Particiona, formatea y monta el disco.
Instala Arch base, Cage, Wayland/XWayland, Samba, dbus y stack grafico.
Genera fstab.
Configura hostname, locale, root, GRUB, Plymouth y NVIDIA si aplica.
Instala audio, codecs y Bluetooth desde lib/drivers.sh.
Crea usuario kiosko y sudoers.
Habilita multilib y dependencias 32-bit de YARG.
Configura HID.
Descarga e instala YARG.
Crea settings.json con la carpeta fija de canciones.
Configura Samba.
Aplica optimizaciones de rendimiento.
Crea update-yarg, run-yarg.sh y cage-kiosk.service.
Configura red, target grafico y limpieza visual.
Desmonta particiones y desactiva swap.

YARG Stable Y Nightly

YARG_RELEASE_CHANNEL acepta:

stable: usa exactamente YARG_URL.
stable-latest: consulta el ultimo release estable de YARC-Official/YARG.
nightly: consulta el ultimo release de YARC-Official/YARG-BleedingEdge.
ask: pregunta durante la instalacion.

El prompt actual es:

Canal de YARG: stable fijo, stable-latest o nightly? [stable/stable-latest/nightly] (stable):

sudo update-yarg respeta el canal instalado. En stable usa YARG_URL; en stable-latest consulta el latest estable; en nightly consulta el latest de YARG-BleedingEdge antes de descargar.

Uso Despues De Instalar Cage/YARG

Despues de reiniciar, systemd inicia:

cage-kiosk.service

El servicio ejecuta:

/usr/bin/dbus-run-session -- /usr/local/bin/run-yarg.sh

El wrapper:

Aplica ajustes de render software si detecta VM.
Valida DBus de sesion; normalmente ya viene creado por systemd mediante dbus-run-session.
Exporta variables Wayland/Cage.
Arranca PipeWire, WirePlumber y PipeWire Pulse en orden.
Espera unos segundos a que exista un sink Pulse/PipeWire; si no aparece, lanza YARG de todos modos y deja el aviso en journal.
Busca un binario ejecutable YARG* en /opt/YARG.
Lanza YARG con -persistent-data-path.
Al salir de YARG, abre un menu de mantenimiento en foot.
Abre el menu de mantenimiento como fallback si no encuentra YARG.

El menu de mantenimiento permite:

Configurar sonido con pulsemixer.
Configurar WiFi con nmtui o nmcli.
Ver direccion IP.
Salir a una shell temporal.
Volver a YARG.
Actualizar YARG Stable o YARG Nightly, segun el canal instalado.
Reiniciar cage-kiosk.service.
Apagar el kiosko.

YARG_EXIT_MENU controla que pasa al cerrar YARG:

always: muestra el menu de mantenimiento.
restart: vuelve a lanzar YARG sin mostrar menu.
never: sale del wrapper.

El perfil fijo se crea en:

/home/kiosk/.config/yarg-kiosk/settings.json

Con contenido equivalente a:

{
  "SongFolders": [
    "/home/kiosk/Songs"
  ],
  "ShowAntiPiracyDialog": false,
  "ShowEngineInconsistencyDialog": false,
  "ShowExperimentalWarningDialog": false
}

Esto evita depender del selector de archivos para la operacion normal del kiosko. El boton Browse puede funcionar en builds nightly recientes, pero el flujo recomendado sigue siendo subir canciones por Samba y escanear desde YARG.

Share Samba:

\\<hostname>\YARG-Songs

Con hostname por defecto:

\\minikiosk\YARG-Songs

Ruta local:

/home/kiosk/Songs

Ruta de compatibilidad dentro de YARG:

/opt/YARG/Songs -> /home/kiosk/Songs

Actualizar YARG:

sudo update-yarg

Uso Despues De Instalar Cage/Clone Hero

Despues de reiniciar, systemd inicia:

cage-kiosk.service

El servicio ejecuta:

/usr/bin/dbus-run-session -- /usr/local/bin/run-clonehero.sh

El wrapper busca Clone Hero en /opt/CloneHero, lo lanza fullscreen dentro de Cage y abre el menu de mantenimiento al salir, salvo que CLONEHERO_EXIT_MENU este en restart o never.

Share Samba:

\\<hostname>\CloneHero-Songs

Con hostname por defecto del camino Clone Hero:

\\miniclonehero\CloneHero-Songs

Ruta local:

/home/kiosk/Songs

Actualizar Clone Hero:

sudo update-clonehero

Tambien se puede actualizar desde el menu de mantenimiento con la opcion Actualizar Clone Hero.

Descargar canciones desde CSV:

~/download-clonehero-songs.sh

El instalador crea o copia ~/links.csv. Cada linea puede ser nombre,url o solo una URL. Los ZIP pueden extraerse directamente en la carpeta Songs.

Uso Despues De Instalar Cage/foot

El camino minimal install-cage-kiosk.sh inicia el mismo servicio cage-kiosk.service, pero ejecuta:

/usr/bin/dbus-run-session -- /usr/local/bin/run-cage-foot.sh

El wrapper abre foot como aplicacion unica dentro de Cage. Es util para un kiosko base, diagnostico o para instalar tu propia aplicacion despues.

Configuracion

Variables comunes:

DISK_DEVICE: disco destino. Por defecto ask, muestra selector interactivo.
KIOSK_USER: usuario kiosko.
KIOSK_PASSWORD: password del usuario kiosko.
TIMEZONE: zona horaria.
ENABLE_SSH: habilita OpenSSH si esta en true.
ALLOW_INSECURE_DEFAULT_PASSWORD: permite passwords de ejemplo solo para laboratorio.
ENABLE_PLYMOUTH: habilita/deshabilita Plymouth.
PLYMOUTH_THEME_NAME: nombre del tema Plymouth.
PLYMOUTH_IMAGE_PATH: imagen PNG opcional para Plymouth. En Cage/YARG y Cage/Clone Hero, si se deja el valor por defecto, el instalador elige primero un asset por camino y resolucion.
PLYMOUTH_TARGET_RESOLUTION: resolucion final usada para preparar la imagen de Plymouth. En Cage/YARG y Cage/Clone Hero se calcula desde la resolucion elegida.
CURSOR_PATH: ruta opcional usada solo por validaciones/assets heredados.
LOG_FILE: archivo donde se guarda la salida detallada de la instalacion.
VERBOSE_INSTALL: si es true, muestra en consola la salida completa de pacman, pacstrap, unzip, grub-mkconfig, etc. Por defecto es false.

Variables de Cage/YARG:

ROOT_PASSWORD: password de root. Cage lo exige con valor real.
KIOSK_HOSTNAME: hostname. Por defecto minikiosk.
INSTALL_NVIDIA: true, false o vacio para preguntar.
YARG_RELEASE_CHANNEL: stable, stable-latest, nightly o ask.
YARG_URL: ZIP estable de YARG.
YARG_STABLE_API_URL: endpoint del ultimo release estable.
YARG_STABLE_ASSET_REGEX: patron usado para elegir el ZIP Linux estable.
YARG_NIGHTLY_API_URL: endpoint del ultimo nightly.
YARG_NIGHTLY_ASSET_REGEX: patron para elegir el ZIP Linux del nightly.
YARG_SONGS_DIR: carpeta local de canciones. Por defecto /home/${KIOSK_USER}/Songs; /opt/YARG/Songs se crea como enlace hacia esta ruta para compatibilidad.
YARG_PERSISTENT_DATA_DIR: perfil persistente de YARG.
YARG_RESOLUTION: 4k, 2k, 1080p, 720p o ask.
YARG_FORCE_SOFTWARE_RENDER: true fuerza llvmpipe/software render; false permite usar la GPU disponible, recomendado para GPU passthrough.
YARG_EXIT_MENU: always muestra menu al salir de YARG; restart relanza YARG directo; never sale del wrapper.

Variables de Cage/Clone Hero:

CLONEHERO_RELEASE_CHANNEL: latest, url o ask.
CLONEHERO_URL: descarga fija de Clone Hero cuando se usa url.
CLONEHERO_API_URL: endpoint del ultimo release.
CLONEHERO_ASSET_REGEX: patron usado para elegir el asset Linux.
CLONEHERO_SONGS_DIR: carpeta local de canciones. Por defecto /home/${KIOSK_USER}/Songs; el perfil de Clone Hero enlaza su carpeta Songs hacia esta ruta.
CLONEHERO_DATA_DIR: perfil persistente de Clone Hero.
CLONEHERO_RESOLUTION: 4k, 2k, 1080p, 720p o ask.
CLONEHERO_FORCE_SOFTWARE_RENDER: true fuerza llvmpipe/software render.
CLONEHERO_EXIT_MENU: always muestra menu al salir de Clone Hero; restart relanza Clone Hero directo; never sale del wrapper.

Nota: REQUIRE_ROOT_PASSWORD existe como control interno. Los caminos Cage lo activan por defecto.

Estructura Del Proyecto

MiniArch/
|-- install-cage-kiosk.sh      # Orquestador Cage/foot minimal
|-- install-cage-clonehero.sh  # Orquestador Cage/Clone Hero integrado
|-- install-cage-yarg.sh       # Orquestador Cage/YARG integrado
|-- scripts/
|   |-- clone-miniarch.sh       # Clona disco, cambia UUIDs y puede expandir /home
|   `-- expand-home.sh          # Expande /home despues de clonar
|-- lib/
|   |-- validation.sh          # Validacion de entorno, seguridad, red y disco
|   |-- partitioning.sh        # GPT/UEFI, formateo, montaje y swap
|   |-- base_install.sh        # Pacstrap base y fstab
|   |-- bootloader.sh          # GRUB UEFI y arranque silencioso
|   |-- plymouth.sh            # Plymouth compartido
|   |-- drivers.sh             # Drivers, PipeWire, codecs y Bluetooth
|   |-- cage.sh                # Cage, usuario, servicio y wrapper
|   |-- clonehero.sh           # Clone Hero, Samba, updater y CSV
|   |-- yarg.sh                # YARG, settings, Samba, rendimiento y updater
|   |-- customization.sh       # Mensajes, cursor, assets y scripts extra
|   `-- finalization.sh        # Red, SSH opcional, limpieza y desmontaje
|-- assets/
|   |-- README.md
|   |-- yarg_720p.png
|   |-- yarg_1080p.png
|   |-- clonehero_720p.png       # opcional/futuro
|   |-- clonehero_1080p.png      # opcional/futuro
|   |-- plymouth-image.png.example
|   `-- cursor/
|-- tests/
|   |-- test_validation.bats
|   |-- test_partitioning.bats
|   |-- test_base_install.bats
|   |-- test_bootloader.bats
|   |-- test_plymouth.bats
|   |-- test_drivers.bats
|   |-- test_gui.bats
|   |-- test_customization.bats
|   |-- test_finalization.bats
|   `-- test_integration.bats

La suite BATS cubre principalmente modulos compartidos. Los modulos lib/cage.sh y lib/yarg.sh todavia no tienen suite dedicada.

Desarrollo Y Pruebas

Instala BATS en Linux/WSL:

sudo apt-get update
sudo apt-get install bats

Ejecuta pruebas:

bats tests/*.bats

Valida sintaxis:

bash -n install-cage-kiosk.sh
bash -n install-cage-yarg.sh
bash -n scripts/clone-miniarch.sh scripts/expand-home.sh
for file in lib/*.sh; do bash -n "$file"; done

Troubleshooting

No se detecta Arch Linux

Ejecuta los instaladores desde el live ISO de Arch Linux. Deben existir /etc/arch-release y pacstrap.

No hay red

ip link
ping -c 3 archlinux.org

Levanta la interfaz si hace falta:

ip link set <interfaz> up
dhcpcd

El disco no existe

lsblk

Configura DISK_DEVICE en .env, por ejemplo:

DISK_DEVICE=/dev/vda

Plymouth falla

Plymouth es opcional en el camino Cage. Si el paquete, tema o asset falla, el instalador debe continuar sin pantalla personalizada.

Si ImageMagick no esta disponible, el instalador intenta copiar el PNG sin redimensionarlo en vez de fallar por el escalado.

Cage no arranca YARG

systemctl status cage-kiosk.service
journalctl -u cage-kiosk.service -b
ls -la /opt/YARG

Necesito ver la salida completa del instalador

Por defecto, MiniArch oculta la salida ruidosa de pacman, pacstrap, mkfs, grub-mkconfig, mkinitcpio, curl y unzip, pero la conserva en LOG_FILE.

Para modo detallado:

VERBOSE_INSTALL=true ./install-cage-yarg.sh

O define en .env:

VERBOSE_INSTALL=true

Si el binario no existe, el wrapper abre foot. Puedes reinstalar con:

sudo update-yarg

Audio no funciona

Revisa hardware ALSA:

aplay -l
aplay -L | grep -i pipewire

Revisa PipeWire/Pulse:

pactl info
pactl list short sinks
journalctl -u cage-kiosk.service -b | grep -Ei 'pipewire|wireplumber|dbus|alsa|bass'

Si pactl info falla, revisa que el wrapper este arrancando con DBus de sesion y que no haya procesos PipeWire stale del usuario.

Samba no aparece

sudo systemctl status smb nmb
testparm
grep -A10 "\[YARG-Songs\]" /etc/samba/smb.conf
ls -la /home/kiosk/Songs

Instrumentos no funcionan

ls -l /etc/udev/rules.d/69-hid.rules

Reconecta el dispositivo despues de instalar para que udev aplique la regla.

Seguridad

No versiones .env.
Cambia KIOSK_PASSWORD y ROOT_PASSWORD.
El usuario kiosko tiene sudo sin password para mantenimiento.
Samba permite guest en YARG-Songs; no lo expongas a redes no confiables.
ENABLE_SSH=false es el valor recomendado para Cage.

Consulta SECURITY.md para mas detalles.

Clonado A Discos Mas Grandes

Si clonas una instalacion a un disco mas grande, revisa CLONING.md para expandir /home.

Contribuir

Lee CONTRIBUTING.md, ejecuta las pruebas disponibles y abre un pull request con cambios acotados.

Licencia

Este proyecto esta bajo licencia MIT. Consulta LICENSE.

Creditos

Arch Linux.
YARG.
Cage.
foot.
Plymouth.
PipeWire.
Samba.
BATS.

Name		Name	Last commit message	Last commit date
Latest commit History 66 Commits
.kiro/specs/arch-kiosk-installer		.kiro/specs/arch-kiosk-installer
assets		assets
lib		lib
scripts		scripts
tests		tests
.env.example		.env.example
.gitignore		.gitignore
CHANGELOG.md		CHANGELOG.md
CLONING.md		CLONING.md
CONTRIBUTING.md		CONTRIBUTING.md
LICENSE		LICENSE
README.md		README.md
SECURITY.md		SECURITY.md
TODO.md		TODO.md
install-cage-clonehero.sh		install-cage-clonehero.sh
install-cage-kiosk.sh		install-cage-kiosk.sh
install-cage-yarg.sh		install-cage-yarg.sh
links.csv		links.csv

Folders and files

Latest commit

History

Repository files navigation

MiniArch

Caminos De Instalacion

Estado Actual

Caracteristicas

Compartidas

Cage/YARG

Cage/Clone Hero

Cage/foot

Requisitos

Instalacion

Instalacion Manual

Flujo De Cage/YARG

YARG Stable Y Nightly

Uso Despues De Instalar Cage/YARG

Uso Despues De Instalar Cage/Clone Hero

Uso Despues De Instalar Cage/foot

Configuracion

Estructura Del Proyecto

Desarrollo Y Pruebas

Troubleshooting

No se detecta Arch Linux

No hay red

El disco no existe

Plymouth falla

Cage no arranca YARG

Necesito ver la salida completa del instalador

Audio no funciona

Samba no aparece

Instrumentos no funcionan

Seguridad

Clonado A Discos Mas Grandes

Contribuir

Licencia

Creditos

About

Resources

License

Contributing

Security policy

Uh oh!

Stars

Watchers

Forks

Releases

Packages 0

Uh oh!

Contributors

Uh oh!

Languages

Packages