Treinamento 2023

Disponibilizaremos neste espaço todos os materiais relacionados ao treinamento ofertado à equipe do STI/COC em agosto de 2023. Cabe ressaltar que todas as orientações aqui presentes são traduções nossas da documentação oficial do AtoM.

MÁQUINA VIRTUAL

Preparada com o VMware Workstation Player, versão 17.0, cujo download foi feito diretamente no site do VMWare. Nesta máquina virtual foi instalado o Ubuntu 20.04.6 LTS (Focal Fossa), distribuição Linux sugerida na documentação do AtoM.
Download da máquina virtual: https://drive.google.com/drive/folders/1n_eUABOvR_yO6FbFkB_3mlCZH7CVK9tY?usp=sharing

Após download da máquina virtual (VM), é importante ajustar a configuração da memória RAM para 8GB, uma vez que existem requisitos mínimos da hardware para a operação do AtoM 2.7. Isso pode ser feito ao clicar com o botão direito sobre o nome da VM e em “Settings”, ajustar as configurações de memória, como ilustra a Figura 1 a seguir.

A instalação do AtoM 2.7 prioriza a execução de comandos no Terminal do Ubuntu. Assim, é importante abrir uma instância desse aplicativo (já que estamos usando a versão do Ubuntu com interface gráfica)

MYSQL

O sistema gerenciador de banco de dados recomendado para o AtoM é o MySQL na versão 8.0 ou superior e deve ser instalada no Ubuntu com os seguintes comandos:

sudo apt update

sudo apt install mysql-server

Como a instalação padrão do MySQL não é totalmente segura, é importante executar o script de segurança abaixo, para aprimorar a configuração padrão:

sudo mysql_secure_installation

IMPORTANTE: Ao ser questionado se deseja configurar o componente VALIDADE PASSWORD, você deve responder que sim. E escolher o nível MEDIUM (1) da política de validação de password, conforme ilustra a Figura 2.

Em seguida, o prompt apresentará algumas perguntas:

• Se você deseja remover os usuários anônimos. Responda que sim (Y)
• Se você deseja desabilitar o login remoto. Responda que não (N), já que em uma situação real de uso do AtoM eventualmente precisaremos logar remotamente
• Se você deseja remover o banco de dados de teste, bem como o acesso a ele. Responda que sim (Y)
• Se você deseja redefinir os privilégios das tabelas dos servidor de banco de dados. Responda que sim (Y)

Depois dessas confirmações, a instalação estará concluída. Contudo, a senha de root do banco de dados estará definida como vazia (ou enter). É EXTREMAMENTE importante definir uma senha de root para o banco de dados. Mesmo que a equipe de infraestruturá a modifique posteriormente. Assim, sugere-se executar os seguintes comandos:

sudo mysql -uroot -p

Pressione para acessar o mysql (já que não tem senha configurada de root. Quando já estiver no mysql, insira o comando a seguir, substituindo NOVA_SENHA_DE_ROOT pela senha definida pela equipe como senha de root.

ALTER USER 'root'@'localhost' IDENTIFIED BY 'NOVA_SENHA_DE_ROOT';

Depois disso, digite o comando abaixo para encerrar a execução do mysql.

quit

Por fim, você deve configurar o modo de operação do MySQL, conforme sugerido pela Artefactual (fabricante do AtoM). Para tal, edite o arquivo:

sudo nano /etc/mysql/conf.d/mysqld.cnf

Com o seguinte conteúdo:

[mysqld]
sql_mode=ERROR_FOR_DIVISION_BY_ZERO,NO_ENGINE_SUBSTITUTION
optimizer_switch='block_nested_loop=off'

Para sair do nano, deve-se pressionar o CTRL + X, digitar S (para salvar) e depois pressionar .

IMPORTANTE: Para edição do arquivo foi utilizado o editor nano, mas você pode optar pelo editor que melhor satisfazer suas demandas e necessidades (vi, vim etc.)

Por fim, deve-se reiniciar o serviço do MySQL, com o comando:

sudo systemctl restart mysql

ELASTICSEARCH

Trata-se da engine de busca utilizada no AtoM.

Antes de executar sua instalação, é necessário instalar o Java e recursos relacionados, o que pode ser feito com o comando:

sudo apt install openjdk-11-jre-headless apt-transport-https software-properties-common

Só depois deve-se fazer o download do Elasticsearch, já que o Ubuntu não fornece um pacote para ele. Para tal, execute:

wget -qO - https://artifacts.elastic.co/GPG-KEY-elasticsearch | sudo apt-key add -

IMPORTANTE: Não deixe de inserir o traço ( -) no final do comando acima!

Depois disso, adicione-o em seu repositório:

sudo echo "deb https://artifacts.elastic.co/packages/5.x/apt stable main" | sudo tee -a /etc/apt/sources.list.d/elastic-5.x.list

E execute:

sudo apt update

sudo apt install elasticsearch

Depois disso, basta habilitar e iniciar o serviço do elasticsearch com os comandos a seguir:

sudo systemctl enable elasticsearch

sudo systemctl start elasticsearch

IMPORTANTE: Se você estiver realizando o procedimento dentro da rede de dados da Fiocruz, pode se deparar com falhas no comando acima. Isso acontece devido a parâmetros de segurança implementados na instituição. Para resolver a questão, deve-se configurar um certificado no navegador Mozilla Firefox, conforme orientações deste tutorial disponível no site da RNP.

PHP

O AtoM exige que o PHP versão PHP 7.4 esteja instalado. Para tal, deve-se executar o seguinte comando que irá instalá-lo junto com o restante das extensões exigidas:

sudo apt install php-common php7.4-common php7.4-cli php7.4-curl php7.4-json php7.4-ldap php7.4-mysql php7.4-opcache php7.4-readline php7.4-xml php7.4-mbstring php7.4-xsl php7.4-zip php-apcu php-apcu-bc

Na sequência instala o Memcached, como mecanismo de cache do PHP:

sudo apt install php-memcache

GEARMAN JOB SERVER

O AtoM 2.7 depende do Gearman para executar determinadas tarefas cuja execução tome muito tempo. Isso é feito de forma assíncrona para garantir que as solicitações da Web sejam tratadas prontamente e as cargas de trabalho não atrapalhem o desempenho do sistema.

Para instalá-lo, basta executar o seguinte comando:

sudo apt install gearman-job-server

OUTROS PACOTES

Apache FOP

Necessário para geração de inventários em PDF. O comando a ser executado é:

sudo apt install --no-install-recommends fop libsaxon-java

Deve-se certificar que o comando java padrão aponte para o binário java versão 11 com o comando a seguir (caso apareçam erros, ignore-os):

sudo update-java-alternatives -s java-1.11.0-openjdk-amd64

Serviços para processamento de objetos digitais

Para que o AtoM seja capaz de processar objetos digitais em formatos como JPEG ou extrair texto de documentos PDF, deve-se instalar os seguintes pacotes:

1. ImageMagick: usado no AtoM para criar derivados de imagem (referência e miniatura )
2. Ghostscript: usado no AtoM com ImageMagick para criar imagens derivadas de PDF de uma página ou muitas páginas
3. pdftotext (parte do poppler-utils): usado no AtoM para extrair texto PDF e torná-lo pesquisável na busca do AtoM
4. FFmpeg: usado no AtoM para criar derivados de vídeo, incluindo a possibilidade de renderização do vídeo diretamente no navegador.

O comando para instalação de todos esses pacotes é:

sudo apt install imagemagick ghostscript poppler-utils ffmpeg

DOWNLOAD DO ATOM

Depois de instalar todas as dependências, devemos fazer download do pacote AtoM. Existem duas maneiras de fazê-lo: via download de um pacote em formato tar.gz ou via repositório git. As instruções apresentadas nesse tutorial dizem respeito ao download de arquivo tar.gz. Para informações sobre a instalação via repositório do git, consulte a documentação oficial.

Faça download do arquivo tar.gz, crie o diretório em que o AtoM deve ser posicionado e descompacte o arquivo diretamente para o diretório definido, com os seguintes comandos:

wget https://storage.accesstomemory.org/releases/atom-2.7.3.tar.gz

sudo mkdir /usr/share/nginx/atom -p

sudo tar xzf atom-2.7.3.tar.gz -C /usr/share/nginx/atom --strip 1

CRIAR O BANCO DE DADOS

Deve-se criar o banco de dados para o AtoM executando o seguinte comando usando a senha de root alterada anteriormente:

sudo mysql -h localhost -u root -p -e "CREATE DATABASE atom CHARACTER SET utf8mb4 COLLATE utf8mb4_0900_ai_ci;"

Depois disso, deve-se criar um usuário para acesso ao AtoM e definir as permissões de acesso exigidas pelo sistema com os comandos a seguir, substituindo SENHA_DEFINIDA por uma senha segura (pelo menos 8 caracteres, com números, letras e caracteres especiais em sua composição):

sudo mysql -h localhost -u root -p -e "CREATE USER 'useratom'@'localhost' IDENTIFIED BY 'SENHA_DEFINIDA';"

sudo mysql -h localhost -u root -p -e "GRANT ALL PRIVILEGES ON atom.* TO 'useratom'@'localhost'"

IMPORTANTE: Nunca use SENHA_DEFINIDA ou quaisquer outras senhas presentes em tutoriais disponíveis na Internet. Isso pode ocasionar graves problemas de segurança ao ambiente onde a aplicação está hospedada.

Uma observação importante é que os privilégios INDEX, CREATE e ALTER são necessários apenas durante o processo de instalação ou durante a atualização do AtoM para uma versão mais recente. Esses privilégios do usuário useratom podem ser removidos após o término da instalação no mysql.

EXECUTE O INSTALADOR

A instalação do AtoM, neste versão, é feita via linha de comando, usando recursos do framework no qual o AtoM opera (o Symfony). O comando a ser executado configura o AtoM de acordo com o ambiente, adiciona as tabelas necessárias e os dados iniciais ao banco de dados criado e cria o índice do Elasticsearch.

Antes de executar o comando, deve-se acessar o diretório do AtoM:

cd /usr/share/nginx/atom

E depois, digitar:

sudo php symfony tools:install

Durante a instalação, prompt pedirá algumas informações de configuração do atom, como host do banco de dados, porta, nome do usuário, senha, entre outros. A Figura 3, a seguir, ilustra as informações solicitadas que devem, posteriormente ser confirmadas.

 

As informações a serem preenchidas são:

• Database host: localhost
• Database port: 3306
• Database name: atom
• Database user: useratom
• Database password: SENHA_DEFINIDA
• Search host: localhost
• Search port: 9200
• Search index: atom

IMPORTANTE: Não esqueça de indicar a senha correta no lugar de SENHA_DEFINIDA

O sistema também pede para incluir alguns metadados relacionados ao AtoM, como título do site, descrição etc. Contudo, como nossa base de dados será migrada posteriormente, não há necessidade de incluir esses dados de maneira precisa.

Após preencher e confirmar as informações, deve-se responder a um aviso que informa a necessidade de remover os dados do banco de dados. Como é um banco de dados novo, sem informações relevantes, deve-se indicar que sim (Y) e prosseguir. A Figura 4 ilustra a pergunta feita em inglês.

 

Após instalar o AtoM, sugere-se configurar a região e o idioma (language) padrão do sistema. Isso pode ser feito dentro do arquivo settings.yml, que deve ser acessado com o comando a seguir:

sudo nano /usr/share/nginx/atom/apps/qubit/config/settings.yml

As informações a serem alteradas são default_culture e default_timezone, que devem passar a ser pt-BR e America/Sao_Paulo, conforme ilustra a Figura 5, a seguir.

IMPORTANTE: Em arquivos YML, é fundamental que indentação seja respeitada, uma vez que a mesma tem função semântica. Portanto, cuidado com espaços e tabs indesejados ao manipular arquivos com extensão .yml.

CONFIGURAÇÕES ADICIONAIS

Permissões de arquivos

É fundamental que o AtoM esteja configurado para operar com o usuário padrão do servidor Web. Apesar de ainda não ter sido instalado, o Nginx é o servidor que será utilizado na hospedar o AtoM e seu usuário padrão é o www-data.

Alguns diretórios no AtoM devem ser graváveis ​​pelo servidor web, por exemplo, de uploads. A maneira mais fácil de garantir isso é atualizar o proprietário do diretório AtoM e seu conteúdo executando o seguinte comando:

sudo chown -R www-data:www-data /usr/share/nginx/atom

Para limitar o acesso ao diretório por outros usuários, execute:

sudo chmod o= /usr/share/nginx/atom

Workers do Gearman

Para que o Gearman opere adequadamente é necessário configurá-lo, criando um arquivo de serviço:

sudo nano /usr/lib/systemd/system/atom-worker.service

Com o seguinte conteúdo:

[Unit]
Description=AtoM worker
After=network.target
# High interval and low restart limit to increase the possibility
# of hitting the rate limits in long running recurrent jobs.
StartLimitIntervalSec=24h
StartLimitBurst=3

[Install]
WantedBy=multi-user.target

[Service]
Type=simple
User=www-data
Group=www-data
WorkingDirectory=/usr/share/nginx/atom
ExecStart=/usr/bin/php7.4 -d memory_limit=-1 -d error_reporting="E_ALL" symfony jobs:worker
KillSignal=SIGTERM
Restart=on-failure
RestartSec=30

Depois, basta recarregar o systemd, ativar e iniciar o Worker do AtoM:

sudo systemctl daemon-reload

sudo systemctl enable atom-worker

sudo systemctl start atom-worker

PHP-FPM

O AtoM precisa do PHP-FPM, um gerenciador de processos, para melhor escalabilidade do sistema. Ele deve ser instalado com o comando:

sudo apt install php7.4-fpm

Depois de instalar, deve-se adicionar um novo pool do PHP para o AtoM, a partir do acréscimo das configurações a seguir em um novo arquivo atom.conf

sudo nano /etc/php/7.4/fpm/pool.d/atom.conf

Conteúdo do arquivo:

[atom]

; The user running the application
user = www-data
group = www-data

; Use UNIX sockets if Nginx and PHP-FPM are running in the same machine
listen = /run/php7.4-fpm.atom.sock
listen.owner = www-data
listen.group = www-data
listen.mode = 0600

; The following directives should be tweaked based in your hardware resources
pm = dynamic
pm.max_children = 30
pm.start_servers = 10
pm.min_spare_servers = 10
pm.max_spare_servers = 10
pm.max_requests = 200

chdir = /

; Some defaults for your PHP production environment
; A full list here: http://www.php.net/manual/en/ini.list.php
php_admin_value[expose_php] = off
php_admin_value[allow_url_fopen] = on
php_admin_value[memory_limit] = 512M
php_admin_value[max_execution_time] = 120
php_admin_value[post_max_size] = 72M
php_admin_value[upload_max_filesize] = 64M
php_admin_value[max_file_uploads] = 10
php_admin_value[cgi.fix_pathinfo] = 0
php_admin_value[display_errors] = off
php_admin_value[display_startup_errors] = off
php_admin_value[html_errors] = off
php_admin_value[session.use_only_cookies] = 0

; APC
php_admin_value[apc.enabled] = 1
php_admin_value[apc.shm_size] = 64M
php_admin_value[apc.num_files_hint] = 5000
php_admin_value[apc.stat] = 0

; Zend OPcache
php_admin_value[opcache.enable] = 1
php_admin_value[opcache.memory_consumption] = 192
php_admin_value[opcache.interned_strings_buffer] = 16
php_admin_value[opcache.max_accelerated_files] = 4000
php_admin_value[opcache.validate_timestamps] = 0
php_admin_value[opcache.fast_shutdown] = 1

; This is a good place to define some environment variables, e.g. use
; ATOM_DEBUG_IP to define a list of IP addresses with full access to the
; debug frontend or ATOM_READ_ONLY if you want AtoM to prevent
; authenticated users
env[ATOM_DEBUG_IP] = "10.10.10.10,127.0.0.1"
env[ATOM_READ_ONLY] = "off"

Posteriormente, o gerenciador de processos deve ser ativado e iniciado:

sudo systemctl enable php7.4-fpm

sudo systemctl start php7.4-fpm

E deve-se remover o pool padrão do PHP (www), já que não iremos utilizá-lo:

sudo rm /etc/php/7.4/fpm/pool.d/www.conf

E reiniciar o serviço:

sudo systemctl restart php7.4-fpm

NGINX

A última instalação a ser feita é a do servidor web Nginx. Existem muitos servidores web capazes de funcionar bem com PHP. O Apache é provavelmente o mais popular, mas para o AtoM o Nginx funciona melhor, diante de sua possibilidade de adaptação a ambientes de recursos limitados, além de escalar melhor e de maneira mais previsível altas cargas de trabalho.

Para instalar o nginx, deve-se utilizar o seguinte comando:

sudo apt install nginx

O Nginx implanta um servidor padrão (também conhecido como VirtualHost, para usuários do Apache) chamado default, que pode ser encontrado em /etc/nginx/sites-available/default. Para o AtoM, será criado um novo item:

sudo touch /etc/nginx/sites-available/atom

sudo ln -sf /etc/nginx/sites-available/atom /etc/nginx/sites-enabled/atom

E o default será removido:

sudo rm /etc/nginx/sites-enabled/default

Depois de criado, devemos incluir o seguinte conteúdo no servidor atom:

sudo nano /etc/nginx/sites-available/atom

upstream atom {
   server unix:/run/php7.4-fpm.atom.sock;
}

server {

   listen 80;
   root /usr/share/nginx/atom;

   # http://wiki.nginx.org/HttpCoreModule#server_name
   # _ means catch any, but it's better if you replace this with your server
   # name, e.g. archives.foobar.com
   server_name _;

   client_max_body_size 72M;

   location ~* ^/(css|dist|js|images|plugins|vendor)/.*\.(css|png|jpg|js|svg|ico|gif|pdf|woff|ttf)$ {

   }

   location ~* ^/(downloads)/.*\.(pdf|xml|html|csv|zip)$ {

   }

   location ~ ^/(ead.dtd|favicon.ico|robots.txt|sitemap.*)$ {

   }

   location / {
      try_files $uri /index.php?$args;
      if (-f $request_filename) {
         return 403;
      }
   }

   location ~* /uploads/r/(.*)/conf/ {

   }

   location ~* ^/uploads/r/(.*)$ {
      include /etc/nginx/fastcgi_params;
      set $index /index.php;
      fastcgi_param SCRIPT_FILENAME $document_root$index;
      fastcgi_param SCRIPT_NAME $index;
      fastcgi_pass atom;
   }

   location ~ ^/private/(.*)$ {
      internal;
      alias /usr/share/nginx/atom/$1;
   }

   location ~ ^/(index|qubit_dev)\.php(/|$) {
      include /etc/nginx/fastcgi_params;
      fastcgi_param SCRIPT_FILENAME $document_root$fastcgi_script_name;
      fastcgi_split_path_info ^(.+\.php)(/.*)$;
      fastcgi_pass atom;
   }

}

Depois disso, deve-se habilitar e recarregar o Nginx:

sudo systemctl enable nginx

sudo systemctl reload nginx

MIGRAÇÃO DE DADOS

Restauração do backup

Após instalar o AtoM, é necessário realizar a migração de dados da versão anterior. Para isso, deve-se realizar um backup dos arquivos e do banco de dados do servidor de hospedagem anterior. Esse tutorial considera que esse backup já foi realizado e que os arquivos da aplicação foram compactados em um arquivo .tar e o banco de dados exportado em um arquivo .sql (verifique o link no chat do treinamento).

Considerando que os arquivos de backup atom.tar e atom.sql foram transferidos para o diretório /home/sti, execute os seguintes comandos:

– Para descompactar o arquivo atom.tar:

tar -xfv atom.tar

– Para transferir os objetos digitais e inventários:

sudo mv atom/r /usr/share/nginx/atom

sudo mv atom/uploads/* /usr/share/nginx/atom/uploads

sudo mv atom/downloads/* /usr/share/nginx/atom/downloads

– Para remover os jobs anteriores – do outro servidor – que foram copiados anteriormente:

sudo rm -f /usr/share/nginx/atom/downloads/jobs/*

– Para remover o banco de dados atual (que está vazio, pois foi criado recentemente):

sudo mysql -u root-p -e "DROP DATABASE IF EXISTS atom;"

– Para criar um novo banco de dados – vazio:

sudo mysql -u root -p -e "CREATE DATABASE atom CHARACTER SET utf8mb4 COLLATE utf8mb4_0900_ai_ci;"

– Para carregar o banco de dados da Base Arch:

sudo mysql -u root -p atom < atom.sql

- Para criar um arquivo que permite reiniciar os serviços de maneira rápida e eficaz, digite:

sudo nano /usr/share/nginx/atom/refresh.sh

Copie o seguinte conteúdo para o arquivo:

php symfony cc
php symfony cc
sudo systemctl restart php7.4-fpm
sudo systemctl reload nginx

E atribua permissão de execução para o mesmo:

sudo chmod +x /usr/share/nginx/atom/refresh.sh

- Para atribuir as permissões adequadas em todo diretório ao usuário www-data (novamente):

sudo chown -R www-data:www-data /usr/share/nginx/atom

Execução da tarefa de migração

A tarefa de migração foi programada para ser feita a partir do Framework Symfony. Logo, é essencial que seja realizada dentro do diretório da aplicação:

cd /usr/share/nginx/atom

Dentro do diretório, execute o seguinte comando:

sudo php -d memory_limit=-1 symfony tools:upgrade-sql