Guia de instalação

Primeiro início de sessão e operação

O primeiro administrador, as atualizações, as cópias de segurança, o coming soon e a política de segurança.

O primeiro administrador

O registo só está aberto a quem tem um código de convite, e os códigos geram-se na consola — que ainda ninguém pode abrir. O primeiro código gera-se na própria máquina.

  1. Imagem: no servidor, na raiz do repositório, docker compose -f deploy/prod-allinone/docker-compose.yml exec -e MERYDION_DATA_ROOT=/var/lib/merydion/data merydion merydion-auth invite-code.
  2. Pasta: no PowerShell, na pasta, $env:MERYDION_DATA_ROOT = (Resolve-Path .\data).Path; .\bin\merydion-auth.exe invite-code.
  3. O comando mostra um código no formato XXXX-XXXX-XXXX; invite-code 5 mostra cinco.
  4. No portal, clique em Entrar e depois em Criar conta: introduza o código, registe-se com o e-mail escrito em ADMINISTRATORS e confirme-o com o código do e-mail de verificação.
  5. Inicie sessão: Diagnóstico, no fundo de cada página, abre a consola, onde se geram os restantes códigos de convite.

Sugestão Se o e-mail de verificação não chegar, verifique a palavra-passe da caixa de correio: o serviço de início de sessão indica no arranque quando falta.

Atualizar

Uma atualização substitui a imagem e mantém os dados: estão no volume do contentor, que pertence ao projeto e não à imagem.

  1. Na máquina de desenvolvimento, com o repositório atualizado, construa a nova imagem: .\rebuild_container_release.ps1 -NoSeedData.
  2. Copie-a para o servidor, verifique-a e carregue-a como da primeira vez: sha256sum -c merydion-allinone.tar.sha256 && docker load -i merydion-allinone.tar.
  3. Inicie com o mesmo comando da primeira vez: docker compose --env-file deploy/prod-allinone/.env -f deploy/prod-allinone/docker-compose.yml up -d deteta a nova imagem e recria o contentor, com uma interrupção de poucos segundos.
  4. Abra a consola no separador Atualização: onde uma linha indicar Atualização disponível, clique em Executar atualização — até lá, as funções de dados desse serviço ficam desligadas.

Sugestão Antes de cada atualização, confirme no diagnóstico que as cópias das bases de dados estão em ordem (o cartão «Cópias das bases de dados») e copie os ficheiros: a atualização das bases de dados trabalha sobre uma cópia e mantém o original até a cópia ser verificada, mas as cópias são o seu próprio caminho de regresso.

Cópias e restauro

Cada serviço mantém uma cópia contínua das bases de dados que gere — contas, índices dos documentos, correio, conversas — com um atraso máximo de cerca de um segundo, e pode restaurá-las tal como estavam em qualquer instante dos últimos sete dias. Os ficheiros propriamente ditos — documentos, anexos, pré-visualizações — são escritos uma vez e nunca mudam: são copiados à parte, ou guardados num bucket S3.

  1. Leve as cópias das bases de dados para fora da máquina: registe um destino da classe backups num bucket S3 ou noutro disco, e ative-o.
  2. Imagem: copie os ficheiros, sem as bases de dados, enquanto está em execução: docker run --rm -v merydion-prod-allinone_merydion_state:/d:ro -v "$PWD/files":/b alpine sh -c 'tar czf /b/files-$(date +%F).tgz -C /d --exclude="*.db" --exclude="*.db-*" --exclude=./backups --exclude=./restores .' escreve um arquivo datado na pasta files.
  3. Pasta: pare-a com .\stop.ps1, copie inteira a pasta data e volte a iniciá-la.
  4. Se um administrador registou outro destino para os ficheiros, copie a sua pasta na mesma ronda: os ficheiros criados depois da sua ativação só estão lá.
  5. Guarde as cópias longe da máquina que protegem.

Sugestão Para repor uma base de dados ou a instalação inteira tal como estava num dado instante, pare a instalação e execute merydion-storage copies restore (o procedimento «Cópias e restauro» do runbook): o comando escreve as bases de dados restauradas numa pasta nova, que depois ocupa o lugar da antiga.

Pôr o site em coming soon

O coming soon mostra a cada visitante apenas uma página de pré-visualização enquanto a instalação se prepara: o portal, as aplicações, o Palatys e a consola esperam por trás dela, também para os administradores.

  1. Inicie sessão como administrador e abra https://merydion.example.com/coming-soon.html?enabled=true: a página confirma e o site fica em coming soon.
  2. Para voltar a ligar o site, abra https://merydion.example.com/coming-soon.html?enabled=false: depois da confirmação a página leva-o à página inicial.
  3. Se não tiver sessão iniciada, a página pede-a primeiro; a uma conta que não é de administrador diz-lho, e nada muda.
  4. O estado é o ficheiro site/coming-soon na pasta de dados: retirá-lo volta a ligar o site mesmo sem a página.

Sugestão A página do coming soon existe em inglês e em italiano; a um visitante de outro idioma chega a inglesa.

Ligar as estatísticas de visitas

O site pode contar as suas visitas com o Google Analytics 4, pedindo primeiro o consentimento a cada visitante: enquanto um visitante não aceitar, nada da Google é carregado. As estatísticas ficam desligadas até a instalação indicar o seu ID de medição, e a consola de administração nunca as tem.

  1. No Google Analytics, crie uma propriedade e um stream de dados Web para o endereço do site, e copie o respetivo ID de medição (começa por G-).
  2. Imagem: no ficheiro .env junto a docker-compose.yml acrescente MERYDION_GOOGLE_ANALYTICS_ID=G-XXXXXXXXXX e recrie o contentor com docker compose up -d. Pasta: exporte a mesma variável na sessão antes de start.ps1.
  3. Abra o site numa janela privada: em baixo à esquerda aparece o aviso sobre as estatísticas de visitas, e no fundo de cada página aparece «Preferências de cookies».
  4. Para desligar as estatísticas, esvazie a variável e recrie o contentor: o aviso desaparece, e os navegadores de quem tinha aceitado deixam de carregar o Google Analytics.

Sugestão A política de privacidade e a política de cookies já descrevem as estatísticas, em todos os idiomas, para a instalação que as liga. Na propriedade, defina a retenção de dados que pretende — a Google guarda os dados de uma visita no máximo 14 meses — e deixe os sinais Google desligados: o site também os desliga do seu lado.

Abrir o site aos motores de pesquisa

Cada instalação diz aos motores de pesquisa que não a indexem enquanto não ligar a indexação: uma cópia do site que não é a oficial — uma instalação de teste, a de uma organização — nunca lhe faz concorrência nos resultados. Os endereços que as páginas, as pré-visualizações e os mapas do site declaram são os do site oficial, https://merydion.eu, e as páginas da conta, a consola e a página de um endereço que não existe nunca entram num índice.

  1. Apenas na instalação que serve o site oficial. Imagem: no ficheiro .env junto a docker-compose.yml acrescente MERYDION_SITE_INDEXING=1 e recrie o contentor com docker compose up -d. Pasta: exporte a mesma variável na sessão antes de start.ps1.
  2. Confirme: curl -I https://merydion.eu/ já não mostra o cabeçalho X-Robots-Tag: noindex, e https://merydion.eu/robots.txt aponta para https://merydion.eu/sitemap.xml.
  3. No Google Search Console e no Bing Webmaster Tools, verifique o domínio com um registo DNS e envie https://merydion.eu/sitemap.xml.
  4. Para tirar novamente o site dos motores de pesquisa, esvazie a variável e recrie o contentor: cada resposta volta a dizer noindex, e os motores retiram as páginas na visita seguinte.

Sugestão Um portal gerado para outro endereço define MERYDION_SITE_ORIGIN (por exemplo https://www.example.com) quando é gerado: os endereços canónicos, as variantes de idioma, as pré-visualizações e os mapas do site passam então a indicar esse endereço. A página de um endereço que não existe responde no idioma da sua pasta, com o estado 404.

A Content-Security-Policy do portal

As páginas do portal funcionam sob uma Content-Security-Policy estrita enviada pelo gateway: uma página só pode usar os próprios ficheiros, pedidos à própria origem, imagens também de data: e blob:, e nenhuma moldura de outro site. É o que impede um fragmento de marcação intruso de executar código. A única exceção são as estatísticas de visitas: as páginas que podem contar visitas admitem também o gtag.js da Google, apenas no seu caminho, e a recolha do Google Analytics, que só são carregados depois de um visitante aceitar.

  1. Um portal personalizado com scripts ou estilos escritos dentro das páginas não funciona: scripts e estilos vão em ficheiros próprios.
  2. window.MERYDION_AUTH_BASE, window.MERYDION_API_BASE e window.MERYDION_DIAGNOSTICS_BASE só podem mover uma família de pedidos para outro caminho da mesma origem; um endereço noutra origem é ignorado, com um erro na consola do navegador.
  3. As páginas da consola da instalação têm a política sem a exceção das estatísticas e, além disso, não se podem mostrar dentro de uma moldura.
  4. A política está em apps/portal-csp.mjs e nos três Caddyfile, e um teste mantém-nos iguais: altere-a nos quatro sítios ao mesmo tempo.

Sugestão O formulário de início de sessão do serviço de identidade e a página de recusa da consola chegam com uma política própria, ainda mais estrita.

Voltar ao guia

Produtividade, made in Italy.

Leve toda a suite para a sua equipa — simples, segura e inteiramente sua.