Instalação do AtoM – versão 2.6.4

Este post contém o passo-a-passo em português para instalação da versão 2.6.4 do AtoM. Baseia-se quase que totalmente na documentação oficial do sistema (com pequenas modificações). A documentação oficial está disponível na Wiki da Artefactual

A instalação do AtoM aqui apresentada refere-se à versão compatível com sistema Operacional Linux, assumindo que o Ubuntu 18.04 LTS Bionic Beaver foi previamente instalado no servidor que hospeda a aplicação.

Instalação das dependências (softwares essenciais)

Antes de instalar o AtoM, é necessário preparar o servidor, instalando os softwares essenciais para seu funcionamento.

A primeira providência a ser tomada é assumir o papel de root no terminal do servidor que hospedará o AtoM:

sudo su

MySQL

O AtoM requer o MySQL 8.0 ou superior, mas também foi testado com o Percona Server for MySQL 8.0. Este tutorial, no entanto, restringe-se à instalação do MySQL

Faça download da versão do MySQL recomendada e descompacte o pacote:

wget https://dev.mysql.com/get/mysql-apt-config_0.8.15-1_all.deb
sudo dpkg -i mysql-apt-config_0.8.15-1_all.deb

Durante a instalação, o sistema pedirá que seja definida uma senha de root do MySQL). Recomenda-se a utilização de uma senha forte (e que seja registrada em local seguro, pois será necessário utilizá-la posteriormente). Além disso, será solicitada a seleção do plug-in de autenticação padrão, que deve ser definido como Use Legacy Authentication Method (tradução: Usar método legado de autenticação):

sudo apt update
sudo apt install mysql-server

DICA: A instalação padrão do MySQL não é totalmente segura, porém acompanha um script de segurança que pode ser executado para melhorar a configuração padrão:

sudo mysql_secure_installation

A seguir, deve-se configurar o modo de operação do MySQL. O servidor MySQL pode operar em diferentes modos, o que afeta a sintaxe SQL compatível com o MySQL e as verificações de validação de dados que o servidor realiza. Para o AtoM são adicionadas as seguintes configurações no arquivo mysqln.cnf, que deve ser criado:

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

OBS: Neste tutorial, utiliza-se o editor nano, que pode ser substituído por quaiquer outros editores.

Os seguintes valores devem ser adicionados no arquivo:

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

OBS: No caso do nano, para salvar as alterações, deve-se pressionar o conjunto de teclas CTRL + X (salvar e sair do editor).

Na sequência, deve-se reiniciar o serviço do MySQL:

sudo systemctl restart mysql

Elasticsearch

Trata-se de um servidor de busca baseado no Apache Lucene e desenvolvido em Java. O Ubuntu não fornece um pacote específico, mas é possível baixá-lo diretamente do site da Elasticsearch, caso não seja possível seguir as orientações apresentadas a seguir.

Antes instalar o Elasticsearch, é necessário instalar o Java. Orienta-se utilizar o OpenJDK, mas o JVM da Oracle também funcionaria:

sudo add-apt-repository ppa:openjdk-r/ppa
sudo apt update
sudo apt install openjdk-8-jre-headless software-properties-common

Depois de instalar o Java com sucesso, prossiga com a instalação do Elasticsearch. Baixe e instale a chave de assinatura pública:

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

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

Adicione o repositório:

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 os comandos de instalação:

sudo apt update
sudo apt install elasticsearch

Inicie o serviço e configure-o para iniciar quando o sistema for inicializado:

sudo systemctl enable elasticsearch
sudo systemctl start elasticsearch

Servidor Web

As novas versões do AtoM sugerem o uso do Nginx, por este se adaptar melhor a ambientes de recursos limitados e de altas cargas de trabalho.

IMPORTANTE: As instruções a seguir presumem que o pacote Nginx será instalado no diretório /usr/share/nginx. No entanto, o caminho pode ser diferente em certos ambientes (por exemplo, /var/www). Pode-se optar também por um local diferente. Se for esse o caso, deve-se atualizar os trechos de configuração indicados posteriormente, neste tutorial, de acordo com a localização definida.

Instale o Nginx:

sudo apt install nginx

O Nginx implementa um servidor padrão (também conhecido como VirtualHost, para usuários do Apache) chamado default, disponível em: /etc/nginx/sites-available/default. A instalação do AtoM requer a edição da entrada default ou o acréscimo de uma nova entrada. O tutorial orienta a criação da nova entrada, conforme comandos a seguir:

sudo touch /etc/nginx/sites-available/atom
sudo ln -sf /etc/nginx/sites-available/atom /etc/nginx/sites-enabled/atom
sudo rm /etc/nginx/sites-enabled/default

E a edição de atom:

nano /etc/nginx/sites-available/atom

Com acréscimo dos seguintes valores:

upstream atom {
  server unix:/run/php7.2-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;

  # http://wiki.nginx.org/HttpCoreModule#try_files
  location / {
    try_files $uri /index.php?$args;
  }

  location ~ /\. {
    deny all;
    return 404;
  }

  location ~* (\.yml|\.ini|\.tmpl)$ {
    deny all;
    return 404;
  }

  location ~* /(?:uploads|files)/.*\.php$ {
    deny all;
    return 404;
  }

  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;
  }

  location ~* \.php$ {
    deny all;
    return 404;
  }

}

Após o ajuste, deve-se habilitar e reiniciar o Nginx:

sudo systemctl enable nginx
sudo systemctl reload nginx

PHP

O Ubuntu 18.04 inclui o PHP 7.2, que é mais rápido do que as versões anteriores. O AtoM utiliza PHP-FPM, um gerenciador de processos, que deve ser instalado juntamente com extensões exigidas pelo sistema, de acordo com o seguinte comando:

sudo apt install php7.2-cli php7.2-curl php7.2-json php7.2-ldap php7.2-mysql php7.2-opcache php7.2-readline php7.2-xml php7.2-fpm php7.2-mbstring php7.2-xsl php7.2-zip php-apcu

Instalou-se também o Memcached como mecanismo de cache, por intermédio do comando:

sudo apt install php-memcache

E criou-se um novo pool PHP para AtoM, adicionando o conteúdo abaixo listado em um novo arquivo atom.conf

nano /etc/php/7.2/fpm/pool.d/atom.conf

[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.2-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 gerenciador de processos do PHP deve ser ativado e reiniciado:

sudo systemctl enable php7.2-fpm
sudo systemctl start php7.2-fpm

E no caso de falhas na inicialização, é fundamental verificar se o arquivo de configuração foi criado com as informações corretas (listadas anteriormente). Pode-se verificar problemas de sintaxe no arquivo com o comando:

sudo php-fpm7.2 --test

Caso não utilize o pool PHP padrão (www), o mesmo pode ser removido:

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

Para finalizar, deve-se reiniciar o serviço:

sudo systemctl restart php7.2-fpm

Gearman Job Server

Este recurso é requerido desde a versão 2.2 do AtoM. Deve ser instalado com o seguinte comando:

sudo apt install gearman-job-server

A configuração do Gearman job (server e workers) será realizada após a instalação do AtoM

Outros pacotes

O AtoM requer a instalação de outros pacotes, não obrigatórios para o funcionamento do sistema como um todo, mas essenciais para habilitar algumas funcionalidades. Abaixo um breve resumo de cada um desses pacotes:

• Apache FOP (Formatting Objects Processor) 2.1: aplicativo Java que lê uma árvore de objetos de formatação (FO) e renderiza as páginas resultantes em uma saída especificada (útil para os relatórios emitidos pelo sistema)
• ImageMagick: software para criar, editar, compor ou converter imagens bitmap. Lê e grava imagens em uma variedade de formatos (mais de 100), incluindo DPX, EXR, GIF, JPEG, JPEG-2000, PDF, PhotoCD, PNG, Postscript, SVG e TIFF (útil na gestão de objetos digitais)
• Ghostscript: software utilizado na rasterização ou renderização de arquivos PostScript e PDF (Portable Document Format) para exibição ou impressão de páginas de documentos, e a conversão entre arquivos PostScript e PDF (útil na manipulação de objetos digitais em PDF)
• FFmpeg: software para garantir a transmissão (streamming) de audio de vídeo (útil na gestão de objetos digitais)
• pdftotext (parte de poppler-utils): Utilitário de linha de comando, de código aberto, para converter arquivos PDF em arquivos de texto simples, ou seja, extração de dados de texto de arquivos encapsulados em PDF (viabiliza pesquisa em arquivos PDF)

Mais detalhes sobre os pacotes não obrigatórios (mas recomendados) em: https://www.accesstomemory.org/pt-br/docs/2.6/admin-manual/installation/requirements/#other-dependencies

Para instalar o Apache FOP 2.1 deve-se executar o seguinte comando:

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

Nota: Este comando usa o parâmetro –no-install-recommends intencionalmente para garantir que apenas dependências sejam instaladas e não pacotes “recomendados”. Se –no-install-recommends não for especificado, openjdk-8-jre será instalado como uma dependência para um dos pacotes. Como o openjdk-8-jre-headless já foi instalado anteriormente – na seção Elasticsearch – deve-se evitar a instalação do pacote openjdk-8-jre.

Para instalar os demais pacotes, executar:

sudo apt install imagemagick ghostscript poppler-utils ffmpeg

Instalação do AtoM

As instruções a seguir presumem que a instalação está sendo realizada em /usr/share/nginx. Deve-se baixar o arquivo compactado que contém o AtoM com o comando a seguir. Para instalar o AtoM via repositório GIT, consulte a documentação oficial.

wget https://storage.accesstomemory.org/releases/atom-2.6.4.tar.gz
sudo mkdir /usr/share/nginx/atom
sudo tar xzf atom-2.6.4.tar.gz -C /usr/share/nginx/atom --strip 1

Ajuste a permissão dos arquivos para o usuário padrão do Nginx (www-data):

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

Crie o banco de dados, via comando mysql:

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

Notas:

1. Será criado um banco de dados denominado atom, que pode ter outra denominação, caso seja do interesse da instituição que está instalando o sistema.
2. Caso o servidor de banco de dados esteja hospedado em outro equipamento, subtitua localhost pelo IP do servidor (todas as vezes que o mesmo aparece neste tutorial)
3. Tenha certeza de que está usando um banco de dados vazio. Não utilize um banco de dados antigo com o mesmo nome, a menos que ele esteja vazio.

Crie um usuário específico do MySQL para o sistema (para maior segurança) e atribua os devido privilégios ao mesmo:

sudo mysql -h localhost -u root -p -e "CREATE USER 'atom'@'localhost' IDENTIFIED BY '12345';"
sudo mysql -h localhost -u root -p -e "GRANT ALL PRIVILEGES ON atom.* TO 'atom'@'localhost';"

Nota: Substitua a senha 12345 por uma senha adequada e segura (de preferência misturando números, letras (maiúsculas e minúsculas) e caracteres especiais

Execute o instalador Web, indicando o IP do servidor, ou caso esteja localmente no equipamento, acessando o endereço http://localhost em um navegador.

Preencha as informações solicitadas durante a instalação, tais como detalhes de configuração

• Database name: atom
• Database username: atom
• Database password: 12345 [não esqueça de mudar para a senha que foi definida]
• Database host: localhost
• Database port: 3306
• Search host: localhost
• Search port: 9200
• Search index: atom

E detalhes sobre a base que está sendo instalada:

• Site title
• Site description
• Site base URL
• Username
• E-mail address
• Password

Implantação do Gearman Job Worker

A melhor maneira de executar um worker é usar um supervisor de processo como o systemd, conforme orientações a seguir:

Crie o serviço:

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

Com as seguintes informações:

[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.2 -d memory_limit=-1 -d error_reporting="E_ALL" symfony jobs:worker
KillSignal=SIGTERM
Restart=on-failure
RestartSec=30

Recarregue o systemd, habilite e inicie o AtoM worker:

sudo systemctl daemon-reload
sudo systemctl enable atom-worker
sudo systemctl start atom-worker

Informações adicionais sobre o AtoM Worker:

Para controlar o status de execução do serviço, utiliza-se os seguintes comandos:

sudo systemctl enable atom-worker # Habilita o worker (na inicialização)
sudo systemctl start atom-worker # Inicia o worker
sudo systemctl stop atom-worker # Pára o worker
sudo systemctl restart atom-worker # Reinicia o worker
sudo systemctl status atom-worker # Obtém o status atual

Para ter acesso ao diário do novo atom-worker, deve-se executar o seguinte comando:

sudo journalctl -f -u atom-worker

Configurações extras

Sugere-se algumas configurações extras para uma instalação de AtoM no Brasil.

Idioma e horário

Alterar a cultura e timezone padrão no arquivo settings.yml para pt_br e America/SaoPaulo, respectivamente.

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

Edição do arquivo settings.yml

Nota: Atenção para identação de arquivos YML! Eles devem ser identados com

Criar script para limpeza de cache

Criar o arquivo refresh.sh contendo comandos de limpeza de cache e restart de serviços (PHP e Nginx):

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

Conteúdo do arquivo:

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

Atribuir permissão de execução para o arquivo:

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

Acesse o diretório do AtoM e execute o script:

cd /usr/share/nginx/atom/refresh.sh
./refresh.sh

Popular a interface de busca

Mesmo que não existam registros, é fundamental popular a interface de busca para que a cultura pt_BR seja ativada, com o comando:

php -d memory_limit=-1 symfony search:populate

Nota: É importante estar no diretório raiz do AtoM para que o comando seja realizado (usr/share/nginx/atom/)

Pronto! O AtoM está instalado!