Instalação

Execute o HolyArrs no Docker e abra no seu navegador. Leva poucos minutos.

Antes de começar

• Um computador com Docker e Docker Compose.
• Suas pastas de mídia, ou um lugar para criar essas pastas. Leia Pastas antes se você quer movimentações instantâneas em vez de cópias.
• Em um NAS, Unraid ou Synology, veja NAS, Synology e Unraid. Sem Docker, veja Arquivos portáteis.

Passos

1. Crie uma pasta para a configuração em um disco local, por exemplo /srv/holyarrs/config. Não use um compartilhamento de rede. No Docker Desktop, use um volume nomeado. Veja Docker Desktop.

2. Descubra o usuário e o grupo que são proprietários das suas pastas de mídia:

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

   Use o uid como PUID e o gid como PGID.

3. Salve isto como docker-compose.yml e troque 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. Inicie:

   docker compose up -d
   docker compose ps

   O container aparece como healthy assim que o HolyArrs responde.

5. Abra http://your-server:6262 e crie a conta de Dono na hora. Não existe senha padrão. Até você criar a conta, quem abrir o HolyArrs primeiro vira o Dono.

6. Siga a configuração inicial que abre em seguida. Veja Primeira execução.

Cuidado

Não existe senha padrão. Quem abrir um HolyArrs novo primeiro vira o Dono. Crie a conta agora.

Se você prefere 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

Tag da imagem

Tag	O que você recebe
latest	A versão mais nova
1.0.2 (qualquer versão)	Exatamente essa versão, nunca muda

As configurações explicadas

Portas e pastas

Configuração	O que faz
-p 6262:6262	O app web.
-v /config	Bancos de dados, configurações, a chave mestra, backups e logs. Só em disco local.
-v /movies	Opcional. Uma pasta da Biblioteca de filmes.
-v /tv	Opcional. Uma pasta da Biblioteca de séries.
-v /music	Opcional. Uma pasta da Biblioteca de música.
-v /downloads	Opcional. A pasta de downloads do gerenciador de downloads. Veja Pastas de mídia.
--read-only=true	Opcional. Veja Sistema de arquivos raiz somente leitura.
--user=1000:1000	Opcional. Veja Iniciar como um usuário fixo.

Variáveis de ambiente

Variável	O que faz
PUID, PGID	O usuário e o grupo com que o HolyArrs é executado. 1000 e 1000 quando você deixa de fora.
TZ	Fuso horário, por exemplo Europe/Amsterdam.
UMASK	Opcional. Quais bits de permissão os arquivos novos deixam de fora, por exemplo 022 ou 002.
HOLYARRS_SAVE_PATH	Opcional. A pasta onde o gerenciador de downloads salva, como o gerenciador de downloads enxerga essa pasta.
HOLYARRS_ALLOWED_HOSTS	Opcional. Nomes de host extras que as pessoas usam para chegar ao HolyArrs, separados por vírgula.
HOLYARRS_TRUSTED_PROXIES	Opcional. O endereço ou a rede do seu proxy reverso.
HOLYARRS_URL_BASE	Opcional. Serve o HolyArrs em um caminho. Veja URL base e proxies reversos.
HOLYARRS_MASTER_KEY_FILE	Opcional. Lê a chave mestra de um arquivo próprio.

Qualquer variável pode vir de um arquivo. Coloque FILE__ na frente do nome e use o caminho do arquivo como valor:

environment:
  - FILE__HOLYARRS_ALLOWED_HOSTS=/run/secrets/holyarrs_hosts

Uma quebra de linha no fim do arquivo é ignorada. Isso funciona também para PUID, PGID, UMASK e TZ. Se o arquivo não existir, o HolyArrs para e mostra o nome da variável no log. Ele nunca mostra o valor.

A imagem

A imagem tem o HolyArrs e quase mais nada. Ela não tem shell, então você não consegue entrar nela com docker exec para dar uma olhada. Leia o log com docker logs holyarrs, ou abra logs/holyarrs.log na pasta de configuração.

Os comandos do próprio HolyArrs continuam funcionando 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. Em um 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 log avisa isso.

Usuário e grupo

O container inicia como root só para se preparar. Ele entrega a pasta de configuração para PUID:PGID quando precisa e depois troca para esse usuário de vez. A primeira linha do log mostra o usuário, o grupo e o umask.

O HolyArrs nunca troca o proprietário das suas pastas de mídia ou de downloads. Dê você mesmo permissão de escrita nelas ao usuário do PUID. Permissão de leitura não é suficiente, porque o HolyArrs cria pastas e move arquivos.

Alguns armazenamentos não deixam trocar o proprietário, como NFS com root squash, SMB ou uma montagem somente leitura. Nesse caso o HolyArrs grava um aviso no log e segue em frente. Dê permissão de escrita na pasta de configuração para PUID:PGID à mão.

Trocar de usuário exige as capabilities CHOWN, DAC_OVERRIDE, SETUID e SETGID. O Docker dá essas capabilities por padrão. Se você remover alguma, o HolyArrs para com uma mensagem. Ele não volta para root. Para executar de fato como root, defina PUID=0 e PGID=0.

Os grupos extras de group_add: continuam valendo quando o HolyArrs troca de usuário.

UMASK só afeta arquivos novos. Deixe de fora para manter 022, em que você escreve e os outros leem. Use 002 quando um grupo também precisa escrever.

Pastas de mídia

Monte só as pastas que você usa: /movies, /tv e /music como pastas da Biblioteca e /downloads como a pasta de downloads.

Dica para hardlinks (links físicos): cada pasta que você monta separada é uma montagem separada dentro do container, e não dá para criar um hardlink de um arquivo entre montagens, então as importações viram cópias completas. Se você quer hardlinks, pode montar uma única pasta pai compartilhada (com os downloads e as pastas da Biblioteca dentro dela) no lugar das quatro montagens opcionais, e dar ao gerenciador de downloads a mesma montagem no mesmo caminho. A pasta pai também precisa ser um único sistema de arquivos. Compartilhamentos ou datasets separados de um NAS dentro dela continuam copiando. Settings > Library folders (Configurações > Pastas da Biblioteca) avisa você quando o HolyArrs precisa copiar.

HOLYARRS_SAVE_PATH é enviado ao gerenciador de downloads junto com cada download, então ele também muda onde o gerenciador de downloads salva. Deixe de fora para manter a configuração do próprio gerenciador de downloads. Se você deixar de fora, adicione a pasta de downloads em Settings > Library folders > Extra import folders (pastas extras de importação) para poder importar à mão a partir dela.

Guarde a chave mestra

O HolyArrs criptografa senhas, chaves e tokens salvos com uma chave mestra. A primeira inicialização cria /config/holyarrs.key.

Os backups nunca contêm essa chave. Guarde uma cópia em outro lugar. O jeito fácil: como Dono, abra Settings > Backups (Configurações > Backups) e escolha Download key kit (baixar o kit da chave). Para recuperar a chave, dê ao arquivo o nome holyarrs.key e coloque na pasta de configuração com o HolyArrs parado. Uma restauração com uma chave diferente é recusada. Com um volume nomeado não existe pasta para abrir: copie o arquivo para dentro com docker cp holyarrs.key hx:/config/ como em Docker Desktop. Vai mudar para um computador novo? Recupere a chave primeiro, depois restaure o backup. Veja Backups.

Você também pode manter a chave em um arquivo próprio, somente leitura:

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

O arquivo precisa existir e conter 32 bytes brutos, 64 dígitos hexadecimais ou base64 de 32 bytes. O usuário do PUID precisa conseguir ler o arquivo.

Reinício e restauração

Mantenha uma política de reinício. Uma restauração é verificada e preparada, e então o HolyArrs encerra com status 75 para o Docker iniciar o container de novo e aplicar a restauração. unless-stopped cuida disso.

Para atualizar uma build local, refaça a build e recrie o container sem mexer nas montagens:

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

Nunca remova /config durante uma atualização. Veja Atualizações e Backups.

Nomes de host e proxies reversos

Endereços IP e localhost funcionam sem configurar nada. Um nome de casa como tower.local que você usa durante a configuração inicial é salvo para você. Adicione outros nomes em Allowed host names (nomes de host permitidos) em Settings > Sign-in and security (Configurações > Login e segurança), ou em HOLYARRS_ALLOWED_HOSTS.

Quando um proxy reverso adiciona X-Forwarded-For, coloque só o endereço ou a rede do proxy em HOLYARRS_TRUSTED_PROXIES. Sem isso, o login único (SSO), os endereços reais dos clientes e o cookie Secure não funcionam, e todo mundo atrás do proxy divide um único limite de login. O log mostra o endereço do proxy que você deve adicionar. Se houver outro proxy na frente, como o Cloudflare, adicione também as faixas dele.

Com o nginx, envie 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 não baterem, o HolyArrs trata o visitante como alguém de fora da sua rede.

Segurança básica

• Não redirecione a porta 6262 no seu roteador. Use uma VPN como o Tailscale, ou um proxy reverso com HTTPS.
• Crie a conta de Dono logo depois da primeira inicialização.
• Guarde uma cópia da chave mestra longe da pasta de configuração.
• Mantenha a imagem atualizada.

Instalações especiais

Docker Desktop (Windows e Mac)

O Docker Desktop compartilha as pastas do host por uma camada em que as travas de arquivo do banco de dados não são seguras. O HolyArrs recusa um /config ali e mostra a solução na porta 6262. Use um volume nomeado para /config. As pastas de mídia podem continuar sendo 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 dentro do volume, pare o HolyArrs e execute:

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

Para copiar os backups para fora: docker cp holyarrs:/config/backups .

Em um Mac, se você já conferiu que as travas de arquivo funcionam na sua pasta, defina HOLYARRS_ALLOW_DESKTOP_FOLDER=1 para iniciar mesmo assim. O HolyArrs avisa a cada inicialização. Isso nunca libera a recusa para compartilhamentos de rede.

Sistema de arquivos raiz somente leitura

Só /config e /tmp precisam aceitar escrita:

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

PUID, PGID e UMASK continuam funcionando.

Iniciar como um usuário fixo

services:
  holyarrs:
    user: "1000:1000"

Nesse caso o HolyArrs não troca nenhum proprietário, então a pasta de configuração já precisa aceitar escrita desse usuário. PUID e PGID são ignorados e o log avisa isso. Isso vale também para o runAsUser do Kubernetes.

Docker rootless e Podman

No modo rootless, o root dentro do container é o seu próprio usuário, e os outros ids viram números altos no host. Com PUID=1000, a pasta de configuração acaba tendo como proprietário um desconhecido no host.

Você usa	docker info ou podman info mostra	Use
Docker normal	nenhum rootless	PUID e PGID como sempre
Docker rootless	rootless em Security Options	Opção 1
Podman rootless	rootless: true	Opção 1 ou 2

Opção 1. Defina PUID=0 e PGID=0. Isso é seguro só no modo rootless. Nunca faça isso com o Docker normal ou em um 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 em um único 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. Use :z nas pastas que o gerenciador de downloads compartilha. Não use nenhum dos dois em um compartilhamento de rede (NFS ou SMB): ele não aceita um novo rótulo e o container não iniciaria.
• Passe a verificação de saúde como uma lista. A imagem não tem shell.
• Mantenha a política de reinício always. O serviço do Podman que inicia depois de um reinício só inicia containers always.
• Para iniciar depois de um reinício sem entrar na sua conta, execute loginctl enable-linger $USER uma vez. Depois use o arquivo Quadlet, ou, para podman run, execute systemctl --user enable podman-restart.service.

Se a pasta já pertence a um id alto, pare o container primeiro 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 por nsenter dentro do daemon rootless (nsenter -U --preserve-credentials -n -m -t $(cat $XDG_RUNTIME_DIR/docker.pid)).

Faça sua própria imagem

A partir do checkout do HolyArrs:

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

Depois use holyarrs:local como a imagem.

Solução de problemas

Execute o doctor primeiro. Ele verifica a configuração, as pastas, a rede e o relógio, e diz como resolver cada problema.

• Container em execução: docker exec holyarrs /holyarrs doctor
• Container que não para de reiniciar: docker compose run --rm holyarrs doctor

Veja Solução de problemas para o log e o pacote de suporte.

Você vê	Faça isto
A pasta de configuração está em uma pasta compartilhada ou de rede	Use um disco local, ou um volume nomeado no Docker Desktop. No Unraid use /mnt/<pool>/appdata/holyarrs.
A pasta de configuração está na memória	Coloque /config em um disco. No Unraid, confira se o caminho do pool existe. Para um computador de teste, HOLYARRS_CONFIG_IN_MEMORY=yes permite isso.
A pasta de configuração não aceita escrita	Remova :ro e confira se PUID:PGID são proprietários da pasta.
O disco está cheio	Libere espaço no disco onde fica /config e depois reinicie.
/config não está mapeado	Veja abaixo.
Não é possível trocar de usuário	Devolva as quatro capabilities, ou use user: "<uid>:<gid>".
PUID/PGID não existe dentro deste container	Os ids estão fora da faixa mapeada. Veja Docker rootless e Podman.
Uma variável FILE__ não pode ser lida	Confira o caminho e se o arquivo está montado.
Permissão negada	Confira PUID, PGID e a permissão de escrita em todas as pastas.
Nome de host desconhecido	Abra o HolyArrs pelo IP e adicione o nome em Allowed host names.
As importações são copiadas	Monte uma única pasta compartilhada. Veja Pastas de mídia.
A chave mestra não corresponde	Recupere a chave que pertence a esses bancos de dados.
Restauração preparada, mas o app continua fora do ar	Adicione uma política de reinício e inicie o container.

Esqueceu de mapear /config?

O HolyArrs inicia mesmo assim, mas avisa em todo lugar. Tudo se perde quando o container é removido. Salve os dados primeiro:

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

Depois mapeie ./holyarrs-config:/config (ou um volume nomeado) e recrie o container. No Docker Desktop (Windows e Mac), use um volume nomeado, não uma pasta do host, e copie os dados para dentro como mostrado em Docker Desktop. Uma instalação mais antiga ainda pode estar em um volume sem nome. Liste esses volumes com docker volume ls.

Relacionados

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