Instalar

Ejecuta HolyArrs en Docker y ábrelo en tu navegador. Lleva unos minutos.

Antes de empezar

• Un equipo con Docker y Docker Compose.
• Tus carpetas multimedia, o un lugar donde crearlas. Lee primero Carpetas si quieres movimientos instantáneos en lugar de copias.
• En un NAS, Unraid o Synology, consulta NAS, Synology y Unraid. Sin Docker, consulta Archivos portables.

Pasos

1. Crea una carpeta para la configuración en un disco local, por ejemplo /srv/holyarrs/config. No en una carpeta compartida de red. En Docker Desktop, usa un volumen con nombre. Consulta Docker Desktop.

2. Busca el usuario y el grupo propietarios de tus carpetas multimedia:

   id youruser
   # uid=1000(youruser) gid=1000(youruser)

   Usa el uid como PUID y el gid como PGID.

3. Guarda esto como docker-compose.yml y cambia las rutas:

   name: HolyArrs
   services:
     holyarrs:
       image: holyarrs/holyarrs:latest
       container_name: holyarrs
       environment:
         - PUID=1000
         - PGID=1000
         - TZ=Etc/UTC
       volumes:
         - /srv/holyarrs/config:/config
         - /path/to/movies:/movies #optional
         - /path/to/tv:/tv #optional
         - /path/to/music:/music #optional
         - /path/to/downloads:/downloads #optional
       ports:
         - 6262:6262
       restart: unless-stopped

4. Inícialo:

   docker compose up -d
   docker compose ps

   El contenedor aparece como healthy en cuanto HolyArrs responde.

5. Abre http://your-server:6262 y crea la cuenta de propietario enseguida. No hay contraseña predeterminada. Hasta que la crees, quien abra HolyArrs primero se convierte en el propietario.

6. Sigue la configuración que se abre a continuación. Consulta Primer inicio.

Precaución

No hay contraseña predeterminada. Quien abra primero un HolyArrs nuevo se convierte en el propietario. Crea la cuenta ahora.

Si prefieres docker run:

docker run -d \
  --name=holyarrs \
  -e PUID=1000 \
  -e PGID=1000 \
  -e TZ=Etc/UTC \
  -p 6262:6262 \
  -v /srv/holyarrs/config:/config \
  -v /path/to/movies:/movies `#optional`   -v /path/to/tv:/tv `#optional`   -v /path/to/music:/music `#optional`   -v /path/to/downloads:/downloads `#optional` \
  --restart unless-stopped \
  holyarrs/holyarrs:latest

Etiqueta de la imagen

Etiqueta	Qué obtienes
latest	La versión más reciente
1.0.2 (cualquier versión)	Esa versión exacta, nunca cambia

Los ajustes, explicados

Puertos y carpetas

Ajuste	Qué hace
-p 6262:6262	La app web.
-v /config	Bases de datos, ajustes, la clave maestra, copias de seguridad y registros. Solo disco local.
-v /movies	Opcional. Una carpeta de la Biblioteca de películas.
-v /tv	Opcional. Una carpeta de la Biblioteca de series.
-v /music	Opcional. Una carpeta de la Biblioteca de música.
-v /downloads	Opcional. La carpeta de descargas del Gestor de descargas. Consulta Carpetas multimedia.
--read-only=true	Opcional. Consulta Sistema de archivos raíz de solo lectura.
--user=1000:1000	Opcional. Consulta Iniciar con un usuario fijo.

Variables de entorno

Variable	Qué hace
PUID, PGID	El usuario y el grupo con los que se ejecuta HolyArrs. 1000 y 1000 si no los indicas.
TZ	Zona horaria, por ejemplo Europe/Amsterdam.
UMASK	Opcional. Qué bits de permiso se quitan a los archivos nuevos, por ejemplo 022 o 002.
HOLYARRS_SAVE_PATH	Opcional. La carpeta donde guarda el Gestor de descargas, tal como él la ve.
HOLYARRS_ALLOWED_HOSTS	Opcional. Otros nombres de host con los que se accede a HolyArrs, separados por comas.
HOLYARRS_TRUSTED_PROXIES	Opcional. La dirección o la red de tu proxy inverso.
HOLYARRS_URL_BASE	Opcional. Sirve HolyArrs bajo una ruta. Consulta URL base y proxies inversos.
HOLYARRS_MASTER_KEY_FILE	Opcional. Lee la clave maestra desde un archivo propio.

Cualquier variable puede venir de un archivo. Pon FILE__ delante del nombre y da la ruta del archivo como valor:

environment:
  - FILE__HOLYARRS_ALLOWED_HOSTS=/run/secrets/holyarrs_hosts

Se descarta un salto de línea al final del archivo. Esto también funciona con PUID, PGID, UMASK y TZ. Si falta el archivo, HolyArrs se detiene y nombra la variable en el registro (log). Nunca muestra el valor.

La imagen

La imagen contiene HolyArrs y poco más. No tiene shell, así que no puedes entrar con docker exec a mirar. Lee el registro con docker logs holyarrs, o abre logs/holyarrs.log en la carpeta de configuración.

Los comandos propios de HolyArrs sí funcionan con docker exec:

docker exec holyarrs /holyarrs doctor
docker exec -i holyarrs /holyarrs reset-owner
docker exec holyarrs /holyarrs restore --pre-update

Las imágenes se compilan para amd64, ARM de 64 bits y ARM de 32 bits. En un equipo con unos 2.5 GiB de memoria o menos, HolyArrs activa por sí solo el modo de poca memoria. La primera línea del registro lo indica.

Usuario y grupo

El contenedor se inicia como root solo para prepararse. Entrega la carpeta de configuración a PUID:PGID cuando hace falta y luego cambia a ese usuario de forma definitiva. La primera línea del registro muestra el usuario, el grupo y el umask.

HolyArrs nunca cambia el propietario de tus carpetas multimedia ni de descargas. Dale tú mismo permiso de escritura sobre ellas al usuario PUID. El permiso de lectura no basta, porque HolyArrs crea carpetas y mueve archivos.

Algunos almacenamientos no permiten cambiar propietarios, como NFS con root squash, SMB o un montaje de solo lectura. En ese caso HolyArrs escribe una advertencia en el registro y sigue adelante. Haz a mano que PUID:PGID pueda escribir en la carpeta de configuración.

Cambiar de usuario requiere las capacidades CHOWN, DAC_OVERRIDE, SETUID y SETGID. Docker las da de forma predeterminada. Si las quitas, HolyArrs se detiene con un mensaje. No recurre a root. Para ejecutarlo de verdad como root, define PUID=0 y PGID=0.

Los grupos adicionales de group_add: se conservan cuando HolyArrs cambia de usuario.

UMASK solo afecta a los archivos nuevos. No lo indiques para mantener 022, con el que tú escribes y los demás leen. Usa 002 cuando un grupo también deba escribir.

Carpetas multimedia

Monta solo las carpetas que uses: /movies, /tv y /music como carpetas de la Biblioteca y /downloads como carpeta de descargas.

Consejo para los hardlinks (enlaces duros): cada carpeta que montas por separado es un montaje distinto dentro del contenedor, y no se puede crear un hardlink de un archivo entre montajes, así que las importaciones se convierten en copias completas. Si quieres hardlinks, puedes montar una sola carpeta principal compartida (con las descargas y las carpetas de la Biblioteca dentro) en lugar de los cuatro montajes opcionales, y dar al Gestor de descargas el mismo montaje en la misma ruta. La carpeta principal también debe ser un solo sistema de archivos. Las carpetas compartidas o los datasets separados de un NAS que estén dentro de ella se siguen copiando. Settings > Library folders (Ajustes > Carpetas de la Biblioteca) te advierte cuando HolyArrs tiene que copiar.

HOLYARRS_SAVE_PATH se envía al Gestor de descargas con cada descarga, así que también cambia dónde guarda el Gestor de descargas. No lo indiques para mantener el ajuste propio del Gestor de descargas. Si no lo indicas, añade la carpeta de descargas en Settings > Library folders > Extra import folders (carpetas de importación adicionales) para poder importar a mano desde ella.

Guarda la clave maestra

HolyArrs cifra las contraseñas, claves y tokens guardados con una clave maestra. El primer inicio crea /config/holyarrs.key.

Las copias de seguridad nunca contienen esta clave. Guarda una copia en otro lugar. La forma fácil: como propietario, abre Settings > Backups (Ajustes > Copias de seguridad) y elige Download key kit (descargar el kit de la clave). Para recuperarla, llama al archivo holyarrs.key y colócalo en la carpeta de configuración con HolyArrs detenido. Una restauración con una clave distinta se rechaza. Con un volumen con nombre no hay carpeta que abrir: cópiala dentro con docker cp holyarrs.key hx:/config/ como en Docker Desktop. ¿Te mudas a un equipo nuevo? Recupera primero la clave y luego restaura la copia de seguridad. Consulta Copias de seguridad.

También puedes guardar la clave en un archivo propio de solo lectura:

environment:
  - HOLYARRS_MASTER_KEY_FILE=/keys/holyarrs.key
volumes:
  - /srv/holyarrs/keys:/keys:ro

El archivo debe existir y contener 32 bytes sin formato, 64 dígitos hexadecimales o base64 de 32 bytes. El usuario PUID debe poder leerlo.

Reinicio y restauración

Mantén una política de reinicio. Una restauración se comprueba y se deja preparada; luego HolyArrs sale con el estado 75 para que Docker lo inicie de nuevo y la aplique. unless-stopped se encarga de eso.

Para actualizar una compilación local, vuelve a compilar y recrea el contenedor sin tocar los montajes:

docker build --file deploy/Dockerfile --tag holyarrs:local .
docker compose up -d --force-recreate

Nunca elimines /config durante una actualización. Consulta Actualizaciones y Copias de seguridad.

Nombres de host y proxies inversos

Las direcciones IP y localhost funcionan sin hacer nada. Un nombre de casa como tower.local que uses durante la primera configuración se guarda solo. Añade otros nombres en Allowed host names (nombres de host permitidos) en Settings > Sign-in and security (Ajustes > Inicio de sesión y seguridad), o en HOLYARRS_ALLOWED_HOSTS.

Cuando un proxy inverso añade X-Forwarded-For, pon solo la dirección o la red del proxy en HOLYARRS_TRUSTED_PROXIES. Sin eso, el inicio de sesión único (SSO), las direcciones reales de los clientes y la cookie Secure no funcionan, y todos los que están detrás del proxy comparten un mismo límite de inicio de sesión. El registro indica la dirección del proxy que hay que añadir. Si hay otro proxy delante, como Cloudflare, añade también sus rangos.

Con nginx, envía las dos cabeceras:

proxy_set_header X-Real-IP $remote_addr;
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;

Si las dos no coinciden, HolyArrs trata al visitante como alguien de fuera de tu red.

Seguridad básica

• No abras el puerto 6262 en tu router. Usa una VPN como Tailscale, o un proxy inverso con HTTPS.
• Crea la cuenta de propietario justo después del primer inicio.
• Guarda una copia de la clave maestra lejos de la carpeta de configuración.
• Mantén la imagen actualizada.

Configuraciones especiales

Docker Desktop (Windows y Mac)

Docker Desktop comparte las carpetas del host a través de una capa en la que los bloqueos de archivos de las bases de datos no son seguros. HolyArrs rechaza un /config ahí y muestra la solución en el puerto 6262. Usa un volumen con nombre para /config. Las carpetas multimedia pueden seguir siendo carpetas del host.

name: HolyArrs
services:
  holyarrs:
    image: holyarrs/holyarrs:latest
    container_name: holyarrs
    environment:
      - TZ=Etc/UTC
    volumes:
      - holyarrs-config:/config
      - C:/Media/movies:/movies
    ports:
      - 6262:6262
    restart: unless-stopped

volumes:
  holyarrs-config:

Para pasar una carpeta de configuración antigua al volumen, detén HolyArrs y ejecuta:

docker create --name hx -v holyarrs-config:/config holyarrs/holyarrs:latest
docker cp C:\old\config\. hx:/config/
docker rm hx

Para sacar las copias de seguridad: docker cp holyarrs:/config/backups .

En un Mac, si comprobaste que los bloqueos de archivos funcionan en tu carpeta, define HOLYARRS_ALLOW_DESKTOP_FOLDER=1 para iniciar de todos modos. HolyArrs advierte en cada inicio. Esto nunca quita el rechazo a las carpetas compartidas de red.

Sistema de archivos raíz de solo lectura

Solo /config y /tmp necesitan permiso de escritura:

services:
  holyarrs:
    read_only: true
    tmpfs:
      - /tmp

PUID, PGID y UMASK siguen funcionando.

Iniciar con un usuario fijo

services:
  holyarrs:
    user: "1000:1000"

En ese caso HolyArrs no cambia ningún propietario, así que ese usuario ya debe poder escribir en la carpeta de configuración. PUID y PGID se ignoran y el registro lo indica. Esto también cubre runAsUser de Kubernetes.

Docker y Podman rootless

En modo rootless, root dentro del contenedor es tu propio usuario, y los demás ids se asignan a números altos en el host. Con PUID=1000, la carpeta de configuración acaba siendo propiedad de un desconocido en el host.

Qué ejecutas	docker info o podman info muestra	Usa
Docker normal	sin rootless	PUID y PGID como siempre
Docker rootless	rootless en Security Options	Opción 1
Podman rootless	rootless: true	Opción 1 o 2

Opción 1. Define PUID=0 y PGID=0. Esto solo es seguro en modo rootless. Nunca lo hagas con Docker normal ni en un NAS.

Opción 2. Podman con keep-id, como un Quadlet en ~/.config/containers/systemd/holyarrs.container:

[Container]
Image=holyarrs/holyarrs:latest
UserNS=keep-id
User=%U:%G
Volume=%h/holyarrs/config:/config:Z
PublishPort=6262:6262
HealthCmd=["/holyarrs","-healthcheck"]
HealthInterval=30s

[Service]
Restart=always

[Install]
WantedBy=default.target

O como un solo comando:

podman run -d --name holyarrs --userns=keep-id --user "$(id -u):$(id -g)" -v ~/holyarrs/config:/config:Z -p 6262:6262 --health-cmd '["/holyarrs","-healthcheck"]' --health-interval 30s --restart always holyarrs/holyarrs:latest

• :Z es para sistemas con SELinux. Usa :z en las carpetas que comparte el Gestor de descargas. No uses ninguno de los dos en una carpeta compartida de red (NFS o SMB): no se puede reetiquetar y el contenedor no se iniciaría.
• Da la comprobación de salud como una lista. La imagen no tiene shell.
• Mantén la política de reinicio always. El servicio de Podman que inicia los contenedores tras un reinicio solo inicia los que tienen always.
• Para que se inicie tras un reinicio sin iniciar sesión, ejecuta loginctl enable-linger $USER una vez. Después usa el archivo Quadlet o, con podman run, ejecuta systemctl --user enable podman-restart.service.

Si la carpeta ya pertenece a un id alto, detén primero el contenedor y luego:

• Podman rootless: podman unshare chown -R 0:0 ~/holyarrs/config (Opción 1) o podman unshare chown -R 1000:1000 ~/holyarrs/config.
• Docker rootless: rootlesskit chown -R 0:0 ~/holyarrs/config, ejecutado con nsenter dentro del daemon rootless (nsenter -U --preserve-credentials -n -m -t $(cat $XDG_RUNTIME_DIR/docker.pid)).

Compila tu propia imagen

Desde tu copia del código de HolyArrs:

docker build --file deploy/Dockerfile --tag holyarrs:local .

Después usa holyarrs:local como imagen.

Solución de problemas

Ejecuta primero el doctor. Comprueba la configuración, las carpetas, la red y el reloj, y te dice cómo arreglar cada problema.

• Contenedor en marcha: docker exec holyarrs /holyarrs doctor
• El contenedor se reinicia sin parar: docker compose run --rm holyarrs doctor

Consulta Solución de problemas para el registro y el paquete de soporte.

Qué ves	Haz esto
La carpeta de configuración está en una carpeta compartida o de red	Usa un disco local, o un volumen con nombre en Docker Desktop. En Unraid usa /mnt/<pool>/appdata/holyarrs.
La carpeta de configuración está en memoria	Pon /config en un disco. En Unraid, comprueba que la ruta del pool existe. Para un equipo de pruebas, HOLYARRS_CONFIG_IN_MEMORY=yes lo permite.
No se puede escribir en la carpeta de configuración	Quita :ro y comprueba que PUID:PGID son propietarios de la carpeta.
El disco está lleno	Libera espacio en el disco que contiene /config y reinicia.
/config no está mapeado	Mira más abajo.
No se puede cambiar de usuario	Vuelve a añadir las cuatro capacidades, o usa user: "<uid>:<gid>".
PUID/PGID no existe dentro de este contenedor	Los ids están fuera del rango mapeado. Consulta Docker y Podman rootless.
No se puede leer una variable FILE__	Comprueba la ruta y que el archivo está montado.
Permiso denegado	Comprueba PUID, PGID y el permiso de escritura en todas las carpetas.
Nombre de host desconocido	Abre HolyArrs por IP y añade el nombre en Allowed host names.
Las importaciones se copian	Monta una sola carpeta compartida. Consulta Carpetas multimedia.
La clave maestra no coincide	Recupera la clave que corresponde a esas bases de datos.
Restauración preparada, pero la app sigue caída	Añade una política de reinicio e inicia el contenedor.

¿Olvidaste mapear /config?

HolyArrs se inicia igual, pero advierte en todas partes. Todo se pierde cuando se elimina el contenedor. Guárdalo primero:

docker stop holyarrs
docker cp holyarrs:/config ./holyarrs-config

Después mapea ./holyarrs-config:/config (o un volumen con nombre) y recrea el contenedor. En Docker Desktop (Windows y Mac), usa un volumen con nombre, no una carpeta del host, y copia los datos dentro como se muestra en Docker Desktop. Una configuración más antigua puede seguir en un volumen sin nombre. Míralos con docker volume ls.

Relacionado

• Carpetas
• Primer inicio
• NAS, Synology y Unraid
• Actualizaciones