Instalação do AtoM 2.8.2 » Blog Base Arch

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.

Cabe ressaltar que todos os procedimentos aqui relatados são baseados no processo oficial de instalação do AtoM, fornecido pela Artefactual no blog Access to Memory.

Download do AtoM

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.8.2.tar.gz

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

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

Importante: Todos os comandos devem ser executados como super usuário. Portanto, não esqueça de executar o comando que permite este privilégio:

sudo su

Criação do banco de dados

Deve-se criar um banco de dados para o AtoM no MySQL, a partir da execução do seguinte comando, que exige a senha de root (definida 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.

Outra 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.

Execução do instalador do AtoM

A instalação do AtoM, nesta 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, além de criar 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, 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. 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 (a não ser que a instituição de vocês vá operar com um AtoM novo). Os metadados solicitados são os seguintes:

Site title
Site description
Site base URL
Admin email
Admin username
Admin password

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 recém criado, sem informações cadastradas, deve-se indicar que sim (Y) e prosseguir. A Figura 1 ilustra a pergunta feita em inglês.

Captura de tela de uma mensagem de aviso no prompt do Ubuntu

Figura 1: Mensagem de aviso para confirmar e prosseguir com a instalação

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 2, a seguir.

Captura de telas do arquivo de configuração do AtoM

Figura 2: Trecho do arquivo settings.yml com as configurações que devem ser aplicadas.

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"

O PHP-FPM precisa ser habilitado e iniciado. Isso pode ser feito com os comandos:

sudo systemctl enable php7.4-fpm

sudo systemctl start php7.4-fpm

Para testar se tudo de certo, e o PHP FPM está habilitado, execute o comando:

sudo php-fpm7.4 --test

Caso, assim como nós da COC/Fiocruz, vocês não pretendam utilizar o servidor para outros propósitos, sugerimos que removam o pool padrão (www):

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

E reinicie 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 é 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 executar 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 acessá-lo:

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

E incluir o seguinte conteúdo:

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|rtf)$ {

   }

   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

NOTA SOBRE SEGURANÇA: Nosso treinamento utiliza o AtoM na porta 80 (padrão – http básico, sem criptografia). No entanto, é essencial que o sistema de vocês, quando disponível publicamente, utilize certificados TLS/SSL, para que seu conteúdo esteja disponível sob protocolo HTTPS.
Um aspecto essencial para o perfeito funcionamento do AtoM, tão logo ele seja instalado ou após passar por alguma atualização, é a limpeza do cache da aplicação, com o comando:

sudo php symfony cc

Nossa experiência de anos utilizando o AtoM nos fez criar um arquivo de script, não apenas para limpar o cache, mas também para reiniciar alguns serviços importantes. Sugerimos que vocês também criem esse arquivo de script, dentro do diretório do atom:

nano refresh.sh

E copiem o seguinte conteúdo para o arquivo, salvando-o ao sair:

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

Depois, dê permissão de execução para o arquivo, com o comando:

chmod +x refresh.sh

E, então, execute o script de limpeza, com o comando:

./refresh.sh

Antes de dar a instalação como finalizada, devemos acessar o ambiente administrativo do AtoM (com login e senha definidos anteriormente) e adicionar o português do Brasil como idioma padrão. Isso deve ser feito na área de configurações > Idiomas i18n.

Após acrescentar o idioma, volte para o prompt, acesse o diretório do atom:

cd /usr/share/nginx/atom

E reconstrua o índice de busca, com o comando a seguir:

php symfony search:populate

Mesmo sem conteúdo cadastrado, para que o idioma português do Brasil seja carregado como padrão e corretamente, deve-se executar este comando.

Pronto! O AtoM está instalado e pronto para uso.