Instalar

Executa o HolyArrs no Docker e abre-o no navegador. Demora poucos minutos.

Antes de começares

• Um computador com Docker e Docker Compose.
• As tuas pastas de multimédia, ou um sítio para as criares. Lê primeiro Pastas se queres mover os ficheiros de imediato em vez de os copiar.
• Num NAS, Unraid ou Synology, vê NAS, Synology e Unraid. Sem Docker, vê Ficheiros comprimidos portáteis.

Passos

1. Cria uma pasta de configuração num disco local, por exemplo /srv/holyarrs/config. Não uma partilha de rede. No Docker Desktop, usa antes um volume com nome. Vê Docker Desktop.

2. Descobre o utilizador e o grupo que são donos das tuas pastas de multimédia:

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

   Usa o uid como PUID e o gid como PGID.

3. Guarda isto como docker-compose.yml e muda os caminhos:

   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. Inicia-o:

   docker compose up -d
   docker compose ps

   O contentor aparece como saudável quando o HolyArrs responde.

5. Abre http://your-server:6262 e cria já a conta do proprietário. Não há palavra-passe predefinida. Até a criares, quem abrir o HolyArrs primeiro fica proprietário.

6. Segue a configuração que se abre a seguir. Vê Primeira execução.

Cuidado

Não há palavra-passe predefinida. Quem abrir primeiro um HolyArrs novo fica proprietário. Cria a conta agora.

Se preferires 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 da imagem

Etiqueta	O que recebes
latest	A versão mais recente
1.0.0 (qualquer versão)	Essa versão exata, nunca muda

Definições explicadas

Portas e pastas

Definição	O que faz
-p 6262:6262	A app web.
-v /config	Bases de dados, definições, a chave mestra, cópias de segurança e registos. Só em disco local.
-v /movies	Opcional. Uma pasta da Biblioteca para filmes.
-v /tv	Opcional. Uma pasta da Biblioteca para séries.
-v /music	Opcional. Uma pasta da Biblioteca para música.
-v /downloads	Opcional. A pasta de transferências do gestor de transferências. Vê Pastas de multimédia.
--read-only=true	Opcional. Vê Sistema de ficheiros raiz só de leitura.
--user=1000:1000	Opcional. Vê Iniciar com um utilizador fixo.

Variáveis de ambiente

Variável	O que faz
PUID, PGID	O utilizador e o grupo com que o HolyArrs corre. 1000 e 1000 se as omitires.
TZ	Fuso horário, por exemplo Europe/Amsterdam.
UMASK	Opcional. Que bits de permissão os ficheiros novos deixam de fora, por exemplo 022 ou 002.
HOLYARRS_SAVE_PATH	Opcional. A pasta onde o gestor de transferências guarda, tal como ele a vê.
HOLYARRS_ALLOWED_HOSTS	Opcional. Nomes de host extra que as pessoas usam para chegar ao HolyArrs, separados por vírgulas.
HOLYARRS_TRUSTED_PROXIES	Opcional. O endereço ou a rede do teu proxy inverso.
HOLYARRS_URL_BASE	Opcional. Serve o HolyArrs sob um caminho. Vê URL base e proxies inversos.
HOLYARRS_MASTER_KEY_FILE	Opcional. Lê a chave mestra a partir de um ficheiro próprio.

Qualquer variável pode vir de um ficheiro. Põe FILE__ à frente do nome e dá o caminho do ficheiro como valor:

environment:
  - FILE__HOLYARRS_ALLOWED_HOSTS=/run/secrets/holyarrs_hosts

Uma quebra de linha no fim do ficheiro é ignorada. Isto também funciona com PUID, PGID, UMASK e TZ. Se o ficheiro não existir, o HolyArrs para e indica o nome da variável no registo (log). Nunca mostra o valor.

A imagem

A imagem tem o HolyArrs e pouco mais. Não tem shell, por isso não podes fazer docker exec lá para dentro para espreitar. Lê antes o registo com docker logs holyarrs, ou abre logs/holyarrs.log na pasta de configuração.

Os comandos do próprio HolyArrs continuam a funcionar com docker exec:

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

As imagens são feitas para amd64, ARM de 64 bits e ARM de 32 bits. Num computador com cerca de 2.5 GiB de memória ou menos, o HolyArrs ativa sozinho o modo de pouca memória. A primeira linha do registo diz isso.

Utilizador e grupo

O contentor arranca como root só para se preparar. Dá a pasta de configuração a PUID:PGID quando é preciso e depois muda de vez para esse utilizador. A primeira linha do registo mostra o utilizador, o grupo e o umask.

O HolyArrs nunca muda o dono das tuas pastas de multimédia ou de transferências. Dá tu ao utilizador PUID permissão de escrita nelas. Permissão de leitura não chega, porque o HolyArrs cria pastas e move ficheiros.

Há armazenamento que não deixa mudar donos, como NFS com root squash, SMB ou uma montagem só de leitura. O HolyArrs regista então um alerta e continua. Torna a pasta de configuração gravável para PUID:PGID à mão.

Mudar de utilizador precisa das capacidades CHOWN, DAC_OVERRIDE, SETUID e SETGID. O Docker dá-as por predefinição. Se as retirares, o HolyArrs para com uma mensagem. Não volta para root. Para correr mesmo como root, define PUID=0 e PGID=0.

Os grupos extra de group_add: mantêm-se quando o HolyArrs muda de utilizador.

UMASK só afeta ficheiros novos. Omite-o para ficar com 022, em que tu escreves e os outros leem. Usa 002 quando um grupo também tem de escrever.

Pastas de multimédia

Monta só as pastas que usas: /movies, /tv e /music como pastas da Biblioteca e /downloads como pasta de transferências.

Dica para hardlinks (ligação direta): cada pasta que montas separadamente é uma montagem à parte dentro do contentor, e um ficheiro não pode ter hardlink entre montagens, por isso as importações passam a cópias completas. Se queres hardlinks, podes montar em vez disso uma pasta-mãe partilhada (com as transferências e as pastas da Biblioteca lá dentro) no lugar das quatro montagens opcionais, e dar ao gestor de transferências a mesma montagem no mesmo caminho. A pasta-mãe também tem de ser um só sistema de ficheiros. Partilhas ou datasets de NAS separados lá dentro continuam a copiar. Settings > Library folders (Definições > pastas da Biblioteca) avisa-te quando o HolyArrs tem de copiar.

HOLYARRS_SAVE_PATH é enviado ao gestor de transferências com cada transferência, por isso também muda o sítio onde ele guarda. Omite-o para manter a definição do próprio gestor. Se o omitires, adiciona a pasta de transferências em Settings > Library folders > Extra import folders (pastas de importação extra) para poderes importar à mão a partir dela.

Guarda a chave mestra

O HolyArrs cifra as palavras-passe, chaves e tokens guardados com uma chave mestra. O primeiro arranque cria /config/holyarrs.key.

As cópias de segurança nunca contêm esta chave. Guarda uma cópia noutro lado. A forma fácil: como proprietário, abre Settings > Backups (Definições > cópias de segurança) e escolhe Download key kit (transferir o kit da chave). Para a repor, dá ao ficheiro o nome holyarrs.key e põe-no na pasta de configuração enquanto o HolyArrs está parado. Um restauro com uma chave diferente é recusado. Com um volume com nome não há pasta para abrir: copia-a para lá com docker cp holyarrs.key hx:/config/ como em Docker Desktop. Vais mudar para outro computador? Repõe primeiro a chave e depois restaura a cópia de segurança. Vê Cópias de segurança.

Também podes guardar a chave num ficheiro próprio só de leitura:

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

O ficheiro tem de existir e ter 32 bytes em bruto, 64 dígitos hexadecimais ou base64 de 32 bytes. O utilizador PUID tem de o conseguir ler.

Reiniciar e restaurar

Mantém uma política de reinício. Um restauro é verificado e preparado, e depois o HolyArrs sai com o estado 75 para o Docker o iniciar outra vez e o aplicar. unless-stopped trata disso.

Para atualizar uma build local, reconstrói e recria sem mexer nas montagens:

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

Nunca removas /config durante uma atualização. Vê Atualizações e Cópias de segurança.

Nomes de host e proxies inversos

Os endereços IP e localhost funcionam logo. Um nome de casa como tower.local que uses durante a primeira configuração é guardado automaticamente. Adiciona outros nomes em Allowed host names (nomes de host permitidos) em Settings > Sign-in and security (Definições > início de sessão e segurança), ou em HOLYARRS_ALLOWED_HOSTS.

Quando um proxy inverso acrescenta X-Forwarded-For, põe só o endereço ou a rede do proxy em HOLYARRS_TRUSTED_PROXIES. Sem isso, o início de sessão único, os endereços reais dos clientes e o cookie Secure não funcionam, e todos os que estão atrás do proxy partilham um só limite de inícios de sessão. O registo indica o endereço do proxy a adicionar. Se outro proxy estiver à frente, como a Cloudflare, adiciona também os intervalos dele.

Com nginx, envia os dois cabeçalhos:

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

Se os dois discordarem, o HolyArrs trata o visitante como estando fora da tua rede.

Segurança básica

• Não reencaminhes a porta 6262 no router. Usa uma VPN como o Tailscale, ou um proxy inverso com HTTPS.
• Cria a conta do proprietário logo a seguir ao primeiro arranque.
• Guarda uma cópia da chave mestra longe da pasta de configuração.
• Mantém a imagem atualizada.

Casos especiais

Docker Desktop (Windows e Mac)

O Docker Desktop partilha pastas do host através de uma camada onde os bloqueios de ficheiros das bases de dados não são seguros. O HolyArrs recusa um /config aí e mostra a solução na porta 6262. Usa um volume com nome para /config. As pastas de multimédia podem continuar a ser pastas do 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 levar uma pasta de configuração antiga para o volume, para o HolyArrs e executa:

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

Para copiar as cópias de segurança para fora: docker cp holyarrs:/config/backups .

Num Mac, se verificaste que os bloqueios de ficheiros funcionam na tua pasta, define HOLYARRS_ALLOW_DESKTOP_FOLDER=1 para arrancar mesmo assim. O HolyArrs avisa em cada arranque. Isto nunca levanta a recusa para partilhas de rede.

Sistema de ficheiros raiz só de leitura

Só /config e /tmp precisam de ser graváveis:

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

PUID, PGID e UMASK continuam a funcionar.

Iniciar com um utilizador fixo

services:
  holyarrs:
    user: "1000:1000"

O HolyArrs então não muda donos, por isso a pasta de configuração já tem de ser gravável por esse utilizador. PUID e PGID são ignorados e o registo diz isso. Isto cobre também o runAsUser do Kubernetes.

Docker rootless e Podman

No modo rootless, o root dentro do contentor é o teu próprio utilizador, e os outros ids são mapeados para números altos no host. Com PUID=1000, a pasta de configuração acaba com um dono desconhecido no host.

Tu usas	docker info ou podman info mostra	Usa
Docker normal	sem rootless	PUID e PGID como de costume
Docker rootless	rootless em Security Options	Opção 1
Podman rootless	rootless: true	Opção 1 ou 2

Opção 1. Define PUID=0 e PGID=0. Só é seguro no modo rootless. Nunca o faças com Docker normal nem num NAS.

Opção 2. Podman com keep-id, como um Quadlet em ~/.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

Ou como um só 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 é para sistemas com SELinux. Usa :z nas pastas que o gestor de transferências partilha. Não uses nenhum numa partilha de rede (NFS ou SMB): não pode ser reetiquetada e o contentor não arrancaria.
• Dá a verificação de saúde como lista. A imagem não tem shell.
• Mantém a política de reinício always. O serviço do Podman que arranca depois de um reinício só arranca contentores always.
• Para arrancar depois de um reinício sem iniciares sessão, executa loginctl enable-linger $USER uma vez. Depois usa o ficheiro Quadlet ou, para podman run, executa systemctl --user enable podman-restart.service.

Se a pasta já pertence a um id alto, para primeiro o contentor e depois:

• Podman rootless: podman unshare chown -R 0:0 ~/holyarrs/config (Opção 1) ou podman unshare chown -R 1000:1000 ~/holyarrs/config.
• Docker rootless: rootlesskit chown -R 0:0 ~/holyarrs/config, executado através de nsenter para dentro do daemon rootless (nsenter -U --preserve-credentials -n -m -t $(cat $XDG_RUNTIME_DIR/docker.pid)).

Constrói a tua própria imagem

A partir do checkout do HolyArrs:

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

Depois usa holyarrs:local como imagem.

Resolução de problemas

Executa primeiro o doctor. Verifica a configuração, as pastas, a rede e o relógio, e diz-te como resolver cada problema.

• Contentor a funcionar: docker exec holyarrs /holyarrs doctor
• Contentor que não para de reiniciar: docker compose run --rm holyarrs doctor

Vê Resolução de problemas para o registo e o pacote de suporte.

Vês	Faz isto
Config folder is on a shared or network folder	Usa um disco local, ou um volume com nome no Docker Desktop. No Unraid usa /mnt/<pool>/appdata/holyarrs.
Config folder is in memory	Põe /config num disco. No Unraid, verifica se o caminho do pool existe. Para uma máquina de teste, HOLYARRS_CONFIG_IN_MEMORY=yes permite-o.
Config folder cannot be written	Remove :ro e verifica se PUID:PGID são donos da pasta.
Disk is full	Liberta espaço no disco que tem /config e reinicia.
/config is not mapped	Vê abaixo.
Cannot switch user	Volta a adicionar as quatro capacidades, ou usa user: "<uid>:<gid>".
PUID/PGID does not exist inside this container	Os ids estão fora do intervalo mapeado. Vê Docker rootless e Podman.
A FILE__ variable cannot be read	Verifica o caminho e se o ficheiro está montado.
Permission denied	Verifica PUID, PGID e a permissão de escrita em todas as pastas.
Unknown host name	Abre o HolyArrs pelo IP e adiciona o nome em Allowed host names.
Imports are copied	Monta uma pasta partilhada. Vê Pastas de multimédia.
Master key does not match	Repõe a chave que pertence a essas bases de dados.
Restore staged but the app stays down	Adiciona uma política de reinício e inicia o contentor.

Esqueceste-te de mapear /config?

O HolyArrs arranca na mesma, mas avisa em todo o lado. Perde-se tudo quando o contentor é removido. Guarda primeiro:

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

Depois mapeia ./holyarrs-config:/config (ou um volume com nome) e recria o contentor. No Docker Desktop (Windows e Mac), usa um volume com nome, não uma pasta do host, e copia os dados para lá como mostrado em Docker Desktop. Uma configuração mais antiga pode ainda estar num volume sem nome. Lista-os com docker volume ls.

Relacionado

• Pastas
• Primeira execução
• NAS, Synology e Unraid
• Atualizações