Como fazer self-host do Shiori em 2026: arquivos, contas e armazenamento persistente

Uma implantação do Shiori que falha nem sempre apresenta um crash. Ela pode exibir a página de login enquanto o arquivamento falha porque as dependências do Chromium ou as permissões do filesystem estão incorretas. Em vez disso, comece com uma verificação de ponta a ponta: salve um bookmark com conteúdo arquivado, pesquise por ele, edite as tags e confirme que o arquivo continua disponível depois que a página de origem mudar.

Essa verificação corresponde ao propósito catalogado do Shiori: um bookmark manager que arquiva o conteúdo das páginas. Ela também revela mais cedo dependências ausentes, premissas incorretas sobre o proxy e dados efêmeros do que uma verificação de uptime.

Delimite a fronteira de runtime do Shiori

A saúde do processo e a saúde do produto são coisas distintas no Shiori. A porta 8080 pode responder enquanto a transação voltada ao usuário ainda falha. O requisito externo do Shiori é um volume de dados com permissão de escrita e acesso de saída às páginas arquivadas. Teste o DNS de saída, o TLS e o comportamento do provider sem publicar outro serviço de entrada.

Use este exercício de readiness depois de mudanças relevantes na configuração: salve um bookmark com conteúdo arquivado, pesquise por ele, edite as tags e confirme que o arquivo continua disponível depois que a página de origem mudar. Mantenha verificações externas dispendiosas fora das probes de liveness para que uma indisponibilidade do provider não cause um restart loop. O trabalho de capacity planning deve acompanhar a captura de páginas baseada em browser, o tamanho dos arquivos, as thumbnails e o fetching de saída, que refletem melhor a pressão real sobre o Shiori do que as requisições de página.

Restaure o Shiori em um host vazio

Liste o estado antes de criar o primeiro registro real: banco de dados, conteúdo de páginas arquivadas, thumbnails e configuração. Monte /shiori antes do bootstrap, grave dados de exemplo inofensivos e substitua o container para provar que esse caminho é realmente persistente. Confirme o mount gravando dados inofensivos, substituindo o Shiori e lendo esses dados novamente.

Snapshots são úteis para um rollback rápido, mas é necessário ter um backup independente quando o host ou o volume desaparece. Restaure em um ambiente vazio com a image fixada e confirme que bookmarks, tags, arquivos arquivados e contas retornam, e que um link de origem morto ainda abre o conteúdo salvo. Use volumes persistentes e snapshots para manter esses dois mecanismos de recuperação distintos.

Decisões de segurança específicas do Shiori

O risco de segurança específico da aplicação é manter a conta inicial inalterada em uma instância pública. A resposta operacional é substituir a conta inicial, limitar o compartilhamento público e tratar URLs privadas arquivadas como conteúdo sensível. Conclua o bootstrap por uma rota restrita e remova imediatamente o acesso temporário de configuração.

SHIORI_DIR controla o comportamento, não a confidencialidade; valide seu tipo e valor e armazene as credenciais reais do Shiori separadamente. Dê ao processo do Shiori apenas os mounts e as rotas de dependência documentados; evite acesso à raiz do host e ao socket do Docker. Registre falhas de autenticação e erros de configuração, mas redija tokens, connection strings e conteúdo dos usuários.

Um acceptance run de produção para o Shiori

Um release candidate do Shiori conquista tráfego ao concluir um cenário fixo: salvar um bookmark com conteúdo arquivado, pesquisá-lo, editar as tags e confirmar que o arquivo continua disponível depois que a página de origem mudar. Registre o digest da image, a configuração efetiva sem secrets, a origem pública e os timestamps desse cenário. Os dados de teste devem ser descartáveis, mas realistas o suficiente para exercitar o mesmo caminho usado pelos usuários.

Execute o teste depois de substituir o runtime e, em seguida, reconstrua o serviço a partir do banco de dados, do conteúdo de páginas arquivadas, das thumbnails e da configuração. A recuperação passa quando bookmarks, tags, arquivos arquivados e contas retornam, e um link de origem morto ainda abre o conteúdo salvo. Compare as medições de recursos da captura de páginas baseada em browser, do tamanho dos arquivos, das thumbnails e do fetching de saída com o release anterior e investigue qualquer variação significativa antes da promoção.

Por fim, exercite esta falha controlada: negue temporariamente o caminho de teste usado por um volume de dados com permissão de escrita e pelo acesso de saída às páginas arquivadas. Confirme que o Shiori explica a falha, não danifica o estado existente e retoma a operação depois que a condição válida retornar. Salve um trecho de log com os dados sensíveis removidos e o tempo de recuperação. Juntas, essas verificações cobrem comportamento, durabilidade e operabilidade, em vez de apenas o uptime do processo.

Inicie o Shiori com defaults observáveis

Mantenha a invocação inicial do Shiori reproduzível o suficiente para ser revisada em um pull request.

docker run -d \
  --name shiori \
  --restart unless-stopped \
  -p 127.0.0.1:8080:8080 \
  -v shiori-data:/shiori \
  -e SHIORI_DIR=/shiori \
  ghcr.io/go-shiori/shiori:latest

Não dependa de latest depois que existirem dados reais. Registre o digest utilizado, o usuário do container e a ownership do mount. Acompanhe o log da aplicação durante um teste completo — salve um bookmark com conteúdo arquivado, pesquise por ele, edite as tags e confirme que o arquivo continua disponível depois que a página de origem mudar — e anote qualquer migration antes de colocar a rota atrás do tráfego de produção.

Domínios, headers do proxy e porta 8080

Trate a URL externa do Shiori como uma configuração que sobrevive aos redeploys. Primeiro, encaminhe a UI e a API por uma origem HTTPS estável; depois, encaminhe o hostname para a porta 8080 mantendo intactos o host e o scheme originais.

O checklist de reachability da implantação pode provar que as requisições entram no container. Depois desse ponto, a falha conhecida — o arquivamento falha porque as dependências do Chromium ou as permissões do filesystem estão incorretas — deve ser investigada no Shiori, no estado dele ou na workload, e não na automação de certificados.

Faça upgrade do Shiori sem adivinhações

A primeira métrica operacional útil do Shiori é verificar se ele consegue salvar um bookmark com conteúdo arquivado, pesquisá-lo, editar as tags e confirmar que o arquivo continua disponível depois que a página de origem mudar. Combine isso com sinais de saturation para a captura de páginas baseada em browser, o tamanho dos arquivos, as thumbnails e o fetching de saída. Uma probe que verifica apenas o processo não deve chamar dependências dispendiosas nem reiniciar o container porque um upstream ficou temporariamente indisponível.

Trate upgrades como mudanças de dados, pois as migrations do banco de dados do Shiori e as dependências de captura de páginas podem alterar o comportamento do arquivamento. Fixe as versões, ensaie a operação sobre um estado restaurado e mantenha a image anterior disponível até que um rollback continue válido. Quando o arquivamento falhar porque as dependências do Chromium ou as permissões do filesystem estão incorretas, preserve os logs anteriores ao restart; eles normalmente contêm a mensagem causal.

O que o Dockup deve automatizar para o Shiori

A camada de plataforma do Shiori é composta pela porta 8080, ingress, TLS, configuração do runtime, storage e reachability das dependências. O Dockup pode reproduzir esses elementos na própria infraestrutura ou em um servidor conectado pelo cliente.

Depois, o operador conclui a camada do produto: encaminhar a UI e a API por uma origem HTTPS estável; aplicar esta regra de acesso — substituir a conta inicial, limitar o compartilhamento público e tratar URLs privadas arquivadas como conteúdo sensível; e executar “salvar um bookmark com conteúdo arquivado, pesquisá-lo, editar as tags e confirmar que o arquivo continua disponível depois que a página de origem mudar”. Registrar esse teste junto da implantação evita confundir provisionamento automatizado com readiness da aplicação.

Perguntas frequentes

O que o Shiori precisa para uma implantação em produção?

Encaminhe o container do Shiori na porta 8080 por uma única origem HTTPS. O requisito externo de entrega é um volume de dados com permissão de escrita e acesso de saída às páginas arquivadas. Não considere o Shiori pronto até conseguir salvar um bookmark com conteúdo arquivado, pesquisá-lo, editar as tags e confirmar que o arquivo continua disponível depois que a página de origem mudar.

Quais dados do Shiori devem fazer parte de um backup?

Persista /shiori e inclua o banco de dados, o conteúdo de páginas arquivadas, as thumbnails e a configuração no mesmo manifesto de recuperação. Um restore limpo do Shiori só passa quando bookmarks, tags, arquivos arquivados e contas retornam, e um link de origem morto ainda abre o conteúdo salvo.

O Shiori precisa de HTTPS atrás de um reverse proxy?

Use HTTPS para a origem pública do Shiori e mantenha a porta 8080 na rota interna. Aplique corretamente a configuração do Shiori: encaminhe a UI e a API por uma origem HTTPS estável. No Shiori, o HTTPS protege credenciais ou conteúdo dos usuários em trânsito e mantém consistente o comportamento do cliente sensível à origem.

Como testar um upgrade do Shiori?

Restaure o estado atual do Shiori em uma implantação isolada, aplique a versão candidata e repita sua transação de acceptance. Dê atenção especial a esse ponto, pois as migrations do banco de dados do Shiori e as dependências de captura de páginas podem alterar o comportamento do arquivamento. Mantenha a image anterior do Shiori até entender os limites da migração de dados e do rollback.