Além de informações sobre a organização e estrutura do AtoM em mais detalhes [link pendente], listamos aqui algumas das principais demandas de manutenção que recebemos dos usuários da Base Arch na COC. Sugerimos fortemente que aqueles que já possuem alguma experiência, que tragam suas demandas para discutirmos em conjunto.
- Comandos básicos de manutenção
- Como traduzir termos da interface
- Erro do ElasticSearch: log imenso
- Instalar Google Analytics
- Miniatura de PDF
- Não acessa imagens do diretório “r” da raiz
- Páginas com histórico das alterações feitas nas versões e de acompanhamento de bugs
Comandos básicos de manutenção
A documentação oficial do AtoM apresenta uma lista extensa de comandos a serem executados no prompt, que ajudam a solucionar vários problemas do AtoM, bem como executar ações normalmente não são suportadas na interface do usuário ou que demoram muito tempo para serem executadas via interface.
A intenção aqui é destacar apenas alguns desses comandos, sem listar todas as possibilidades. Sugerimos FORTEMENTE que acessem a documentação oficial mantida pela Artefactual, sempre que enfrentarem um problema. A consulta à fonte oficial é fundamental para garantir que os procedimentos adotados estejam atualizados e de acordo com as boas práticas recomendadas pela equipe desenvolvedora do AtoM.
Embora não seja muito comum, é possível que alguns comandos mudem de uma versão para outra do AtoM. Por isso, é essencial consultar sempre a documentação correspondente à versão que está instalada em seu ambiente, evitando assim a execução de comandos obsoletos ou incompatíve
Algumas ações de manutenção que já precisaram ser executadas em nosso ambiente foram:
- Limpar o cache da aplicação: após qualquer alteração no AtoM, é fundamental limpar o cache para que as mudanças tenham efeito. Em alguns casos, pode ser necessário repetir o procedimento duas vezes e reiniciar o serviço do PHP. Para facilitar esse processo, criamos o script refresh.sh, apresentado anteriormente.;
- Descobrir a versão do AtoM em execução;
- Gerenciar contas de usuários, como promover um usuário comum para administrador, redefinir senhas ou criar novos usuários com permissões administrativas;
- Regerar derivações de imagens (thumbnails e visualizações);
- Reindexar textos de PDFs, para torná-los pesquisáveis no sistema;
- Gerar ou renomear slugs;
- Corrigir problemas na estrutura hierárquica de descrições e termos, quando as relações entre itens (pai e filho) ficam desorganizadas (útil quando o sistema começa a exibir itens fora de ordem ou com erros);
- Reindexar totalmente o sistema para restaurar resultados de busca ou corrigir problemas na navegação (muito frequente);
- Limpar dados temporários e cache para resolver falhas de carregamento ou de exibição;
- Corrigir e organizar termos duplicados na taxonomia, unificando entradas iguais (como dois termos “Rio de Janeiro” em “Lugares”), ajustando automaticamente as referências para manter os dados consistentes;
- Atualizar o status de publicação das descrições (útil para fundos ou coleções grandes, que levam muito tempo para serem publicadas manualmente pela interface);
- Excluir uma descrição e seus objetos digitais vinculados;
- Resolver problmas de integridade de dados;
- Excluir dados temporários (áreas de transferência salvas, registro de acesso e downloads);
- Executar um script PHP genérico para os casos em que seja necessário manipular dados e não existam tarefas pré-existentes (nunca fizemos, mas é bem interessante).
Link para todos os comandos de linha da versão 2.9: https://www.accesstomemory.org/pt-br/docs/2.9/admin-manual/maintenance/cli-tools/#maintenance-cli-tools
Como traduzir termos da interface
A tradução de termos na interface do AtoM não é uma tarefa trivial. Isso porque o AtoM apresenta diferentes formas de traduzir os conteúdos, conforme foi apresentado na aula sobre visão geral da área administrativa: via menu, via configurações e no arquivo XML. Propomos que todos tentem realizar as três formas de tradução.
Tradução via menu
Vamos ajustar o termo “instituição arquivistica” (ilustrado na Figura 1) para “entidade custodiadora”, conforme orientação indicada por Kalinka em uma das aulas. Para tal, deve-se acessar a interface administrativa do AotM com um usuário com perfil de administrador e navegar até o menu Administrador > Menus. Como apresentado nos slides da visão geral da área administrativa (slide 12), o menu correspondente a esta área, no tema da Base Arch, é o browse.
Figura 1: Menu de acesso ao conteúdo no tema da Base Arch
Acesse o item browseRepository, destacado na Figura 2, e modifique o termo conforme indicado anteriormente.
Figura 2: Item de menu a ser alterado
Tradução via configurações
Apesar da mudança no menu, alguns termos da interface referente a entidade custediadora continuarão com problema (conforme Figura 3), pois é necessário também ajustar a “Etiqueta de interface do usuário”.
Figura 3: Termo continua sem tradução em outras áreas da interface
Para tal, deve-se acessar o menu Administrador > Configurações e na lateral, o item Etiqueta de interface do usuário. Então, é só ajustar o termo para “Entidade custodiadora”
Figura 4: Área que permite alteração de alguns elementos da interface
Tradução via barra de tradução da interface
A maioria dos outros elementos da interface são traduzíveis via barra azul, posicionada na base da página (Figura 5).
Figura 5: Barra de tradução do AtoM
Neste caso, basta buscar o elemento a ser traduzido e colocar o texto em português, como ilustra a Figura 6.
Figura 6: Preenchimento da traduçao via recurso na interface administrativa
Lembrando que a barra de tradução só é exibida para usuários com permissão de tradutor e administrador.
Tradução via arquivo XML
Apesar do recurso presente na interface administrativa, nem todo conteúdo é passível de tradução no sistema. Isso acontece porque, por algum motivo, alguns termos da interface não estão presentes no arquivo de tradução. Vamos trabalhar com um exemplo. No menu Administrador > Configurações e no menu lateral: “Elementos padrões da página”, tente encontrar e traduzir o termo “Digital object carousel”. Ele não está disponível. Por isso, precisamos acessar o arquivo XML de tradução, via prompt para fazer o ajuste.
Acesse o diretório do atom:
cd /usr/share/nginx/atom
Edite o arquivo de tradução do idioma pt-BR:
nano apps/qubit/i18n/pt_BR/messages.xml
Procure pela entrada (o termo em inglês) via CTRL + W do nano. Se não encontrar (não vai), inclua uma nova entrada no final do documento (antes do </body>):
<trans-unit id="note01" xml:space="preserve">
<source xml:space="preserve">Digital object carousel</source>
<target xml:space="preserve" state="final">Carrossel de objeto digital</target>
<note>Termo não presente na versão 2.9.2</note>
</trans-unit>
Saia do nano com CTRL + X (salvando a alteração) e reinicie o cache e os serviços com o ./refresh.sh
./refresh
Importante: Se o texto da tradução contiver caracteres especiais, esses devem ser digitados usando caracteres em hexadecimal do padrão HTML/XML.
A Figura 8, a seguir, detalha a estrutura do item no arquivo XML.
Figura 8: Explicação de cada elemento do XML de tradução
Erro do ElasticSearch: log imenso
Já enfrentamos problemas com o Elasticsearch, pois ele pode gerar arquivos de log muito grandes em pouco tempo. Em alguns casos, os logs ocuparam mais de 64 GB do disco em apenas uma semana, comprometendo todo o armazenamento da máquina. Pedimos ajuda, na ocasião, no grupo de usuários do AtoM, mas não tivemos um retorno que resolvesse a questão em definitivo. Diante disso, configuramos um script no cron do Linux para excluir periodicamente os arquivos de log do Elasticsearch, como uma solução paliativa para evitar que o sistema ficasse sem espaço em disco até encontrarmos uma abordagem mais adequada e definitiva. O comando usado para exclusão foi o:
rm /var/log/elasticsearch/* -R
Link para discussão no grupo do Atom Users: https://groups.google.com/g/ica-atom-users/c/hGhFcj208n8/m/dgdS2OhXBAAJ
Caso queira saber a quantidade de espaço em disco que o ElasticSearch de sua instalação ocupa, basta acessar o diretório de logs do ElasticSearch e rodar o comando a seguir:
cd /var/log/elasticsearch/ du -sh
Instalar Google Analytics
Para rastrear o tráfego e a atividade da sua instância de AtoM, o ID de rastramento do Google Analytics deve ser adicionado no arquivo de configuração config/app.yml conforme ilustrado na Figura 9:
Figura 9: Trecho do arquivo de configuração para inclusão do ID do Google Analytics
Para ajustar este arquivo, acesse o arquivo app.yml com o comando a seguir e incorpore o código da sua instalação na variável google_analytics_api_key:
nano /usr/share/nginx/atom/config/app.yml
Miniatura de PDF
Em algumas versões do AtoM, pode ocorrer de as miniaturas (thumbnails) geradas a partir de arquivos PDF não aparecerem, mesmo após a execução do comando para regerar as derivativas (php symfony digitalobject:regen-derivatives).
Ao pesquisarmos na lista de discussão AtoM Users, encontramos relatos de que isso pode estar relacionado a uma mudança nas configurações de segurança do ImageMagick. Em uma atualização recente, o suporte a formatos Ghostscript (como PDF) foi desabilitado por padrão.
A orientação é reativar esse suporte comentando (ou removendo) uma linha específica do arquivo policy.xml. Para tal, acesse-o:
/etc/ImageMagick-6/policy.xml
E comente (ou delete) a linha a seguir:
<policy domain="coder" rights="none" pattern="PDF" />
Após essa alteração, execute o script refresh.sh para limpar o cache e reiniciar os serviços:
./refresh.sh
Gere novamente as derivativas:
php symfony digitalobject:regen-derivatives
E reconstrua o índice de busca:
php -d memory_limit=-1 symfony search:populate
Não acessa imagens do diretório “r” da raiz
Na nossa base Arch, muitas imagens ficam dentro do diretório /r/ da raiz do sistema. E sempre precisamos lembrar de migrá-las quando atualizamos de uma versão para outra. Na nossa última migração tivemos que fazer algumas alterações, pois para reconhecê-las deve-se incluir o diretório em uma das entradas do arquivo de configurações do nginx. Assim, basta acessá-lo em:
/etc/nginx/sites-available/atom
Deve-se alterar a linha a seguir:
location ~* ^/(css|dist|js|images|plugins|vendor)/.*\.(css|png|jpg|js|svg|ico|gif|pdf|woff|woff2|otf|ttf)$ {
}
Para:
location ~* ^/(css|dist|js|images|plugins|r|vendor)/.*\.(css|png|jpg|js|svg|ico|gif|pdf|woff|woff2|otf|ttf)$ {
}
Páginas com histórico das alterações feitas nas versões e de acompanhamento de bugs
O AtoM possui uma página específica para o anúncio de novas versões, onde são detalhados os novos recursos, melhorias e correções de bugs incluídos em cada atualização do ICA-AtoM e do AtoM.
Está neste link: https://wiki.accesstomemory.org/wiki/Releases/Release_announcements.
Outra página bastante útil é o bug tracker oficial do AtoM, onde é possível encontrar, relatar e acompanhar bugs, além de discutir melhorias e acompanhar o desenvolvimento da aplicação. Está disponível no seguinte link: https://github.com/artefactual/atom/issues.