Como instalar o Apex 19.1 + ORDS 19.1

     Olá pessoal,

     Veremos neste artigo um roteiro de instalação do Apex 19.1 e do ORDS 19.1 (Oracle REST Data Services), última versão desses 2 softwares até a data em que fiz a instalação deles em um ambiente de homologação (20/5/19) e fiz um esboço do que hoje virou este artigo. O roteiro contempla uma instalação em Banco de Dados Oracle com arquitetura Multitenant ou Singletenant (12c em diante) ,instalado em um servidor Linux. Essa instalação compreende um ambiente "full development" do "Oracle Application Express" (Apex) com o Web listener "Oracle REST Data Services" funcionando em modo standalone.

      Ressalto que não sou especialista em Apex muito menos em ORDS. Tenho conhecimentos que posso classificar como avançado do básico em Apex e básico do básico em ORDS. Não entrarei em detalhes conceituais sobre os 2 softwares neste artigo, por isso sugiro que você leia a documentação deles (ver referências) caso queira aprender mais. O objetivo deste artigo é apenas passar uma "receita de bolo" que funcionou comigo, após diversas tentativas de instalação (errei muitas vezes até conseguir fazer os 2 funcionarem). Instalar estes softwares é uma tarefa que classifico como chata, pois é cheia de detalhes e pontos de atenção, que poderão causar diversos erros posteriores, caso não tenhamos executado corretamente algum dos passos que irei passar adiante.

   Só para contextualizar um pouco mais o assunto, é importante entender que o Apex possui uma arquitetura simples (do ponto de vista funcional) onde páginas são dinamicamente geradas usando metadados armazenados no Oracle Database (para aprender mais veja o artigo Desenvolvendo aplicações web com o Oracle Application Express que escrevi em 2011). O ORDS, por sua vez, atende requisições REST, traduzindo-as em chamadas ao Banco de Dados, e devolve as respostas e "result sets" aos clientes, transformando-as antes em JSON. O ORDS possui um web server embutido chamado Jetty, que é uma das opções existentes disponíveis para trabalhar com o Apex, sendo a opção mais fácil e rápida de configurar/usar.

Instalação/Atualização do Apex 19.1

É importante ressaltar que tanto para instalar quanto atualizar o Apex, os procedimentos e scripts são os mesmos. 

1- Faça download do Apex 19.1 completo (arquivo "apex_19.1.zip") a partir do site da Oracle e copie-o para o servidor de Banco de Dados onde ele será instalado. Sugiro copiá-lo para a pasta ORACLE_BASE:

2- Dentro da pasta ORACLE_BASE crie outra pasta com nome "apexnnxxx", onde "nn" corresponde à versão do Apex e "xxx" é uma sigla que identifica o tipo do ambiente de Banco de Dados em que ele será instalado (exemplo: "apex19prd"). Mova o arquivo para essa última pasta e descompacte-o lá dentro, como no exemplo abaixo. Chamaremos a partir de agora essa última pasta de APEX_HOME:

$ cd $ORACLE_BASE
$ mkdir $ORACLE_BASE/apex19prd
$ mv ./apex_19.1.zip ./apex19prd
$ cd ./apex19prd
$ unzip apex_19.1.zip

3- Após descompactar o arquivo "apex_19.1.zip" entre na pasta "APEX_HOME/apex", entre no SQL Plus e execute o arquivo apexins.sql conectado no BD desejado, como no exemplo abaixo:

$ cd $ORACLE_BASE/apex19prd/apex
$ export ORACLE_SID=xxx --- substitua xxx pelo nome do CDB desejado
$ sqlplus / as sysdba
SQL> alter session set container = xxx; -- substitua xxx pelo nome do PDB desejado
SQL> @apexins.sql SYSAUX SYSAUX TEMP /i/
SQL> exit

Obs.: É recomendado instalar o Apex sempre no PDB, e não no CDB. Ao término da instalação verifique se ocorreram erros analisando o conteúdo do arquivo de log gerado (cujo nome é exibido ao final da instalação). Se ocorreu algum erro pesquise como tratá-lo, pois possivelmente ele irá impactar depois na utilização do Apex.

4- Instale o pacote "load_pt-br.sql" para permitir a tradução do Apex para o idioma português, entrando na pasta APEX_HOME/apex/builder/pt-br (é necessário configurar previamente o character set para AL32UTF8). Este passo é opcional, mas acho muito interessante segui-lo, pois ele traduzirá todas as páginas de gerenciamento do Apex para o nosso idioma, facilitando o entendimento dos usuários (não pense apenas em você, que é de TI, e está acostumado a ler muita coisa em inglês):

$ cd $ORACLE_BASE/apex19prd/apex/builder/pt-br
$ export ORACLE_SID=xxx --- substitua xxx pelo nome do CDB desejado
$ export NLS_LANG=American_America.AL32UTF8
$ sqlplus / as sysdba
SQL> alter session set container = xxx; -- substitua xxx pelo nome do PDB desejado
SQL> @load_pt-br.sql;
SQL> exit

5- Execute o script "apex_rest_config.sql" localizado na pasta do APEX_HOME/apex para configurar o REST no banco de dados. Serão criados e solicitadas as senhas para os usuários APEX_LISTENER e APEX_REST_PUBLIC_USER:

$ cd $ORACLE_BASE/apex19prd/apex
$ export ORACLE_SID=xxx --- substitua xxx pelo nome do CDB desejado
$ sqlplus / as sysdba
SQL> alter session set container = xxx; -- substitua xxx pelo nome do PDB desejado
SQL> @apex_rest_config.sql;

6- Se for uma nova instalação execute o script "apxchpwd.sql" para criar e configurar a senha do usuário ADMIN do APEX:

SQL> @apxchpwd.sql;

7- Se for uma nova instalação configure a conta do usuário APEX_PUBLIC_USER, pois ela encontra-se inicialmente bloqueada e com a senha expirada:

SQL> ALTER USER APEX_PUBLIC_USER IDENTIFIED BY XXX ACCOUNT UNLOCK ; -- substitua XXX pela senha desejada

8- Habilite os serviços de rede para o usuário APEX_190100 poder enviar e-mail pelo servidor SMTP da sua empresa. O envio de e-mails pelo Apex é funcionalidade útil que certamente algum Desenvolvedor do Apex precisará no futuro:

BEGIN
   DBMS_NETWORK_ACL_ADMIN.APPEND_HOST_ACE(
      host => 'xxx',  -- substitua xxx pelo nome do servidor smtp
      ace => xs$ace_type(privilege_list => xs$name_list('connect'),
      principal_name => 'APEX_190100',
      principal_type => xs_acl.ptype_db));
END;

Repita a execução do script acima se o Apex utilizar outros serviços de rede, tal como um "Print Server".

--- Fim da instalação do Apex 19.1 ---

----------------------------------------------------------------------------------------------------------------

Instalação do Java JDK 8

É necessário ter instalado o Java JDK 8, pois o ORDS 19.1 é simplesmente um componente Java que só pode ser executado a partir desta versão do Java. Sugiro fazer a instalação dele na pasta APEX_HOME. Segue abaixo o roteiro:

Faça download do Java JDK 8 (arquivo "jdk-8u211-linux-x64.tar.gz") a partir do site da Oracle e copie-o para a pasta APEX_HOME. Descompacte o arquivo e renomeie a pasta gerada (após descompactação) "jdk18.8.0_211" para apenas "jdk". Chamaremos a partir de agora essa última pasta de JDK8_HOME:

$ cd $ORACLE_BASE/apex19prd/
$ tar -zxvf jdk-8u211-linux-x64.tar.gz
$ mv ./jdk18.8.0_211 ./jdk

--- Fim da instalação do Java JDK 8 ---

----------------------------------------------------------------------------------------------------------------

Instalação do ORDS 19.1
  

O roteiro abaixo contempla somente novas instalações do ORDS. Se você estiver fazendo uma atualização, o caminho pode ser diferente e não está documentado aqui.

1- Crie uma pasta com nome "ords" dentro do APEX_HOME. Chamaremos essa nova pasta a partir de agora de ORDS_HOME. Faça download do ORDS 19.1 (arquivo "ords-19.1.0.092.1545.zip") a partir do site da Oracle e copie-o para o ORDS_HOME. Descompacte o arquivo copiado:

$ cd $ORACLE_BASE/apex19prd/
$ mkdir ords
--- copie o arquivo ords-19.1.0.092.1545.zip para dentro da pasta criada na linha anterior usando a ferramenta/utilitário apropriada
$ cd ords
$ unzip ords-19.1.0.092.1545.zip

2- Dentro do ORDS_HOME execute o Java JDK 8 (referenciando o caminho completo do JDK8/bin) instalado no passo anterior passando como valor o pacote "ords.war" + valor "install advanced", como no exemplo abaixo:

$ $ORACLE_BASE/apex19prd/jdk/bin/java -jar ords.war install advanced

3- Ao abrir o prompt de instalação do ORDS resposta as perguntas necessárias conforme roteiro abaixo, prestando atenção nas partes em negrito para informar os valores corretos:

This Oracle REST Data Services instance has not yet been configured.
Please complete the following prompts

Enter the location to store configuration data: /xxx/apex19prd/ords/config

Enter the name of the database server [localhost]: xxx

Enter the database listen port [1521]: -- pressione ENTER se estiver usando 1521

Enter 1 to specify the database service name, or 2 to specify the database SID [1]: -- pressione ENTER

Enter the database service name: xxx 

Enter 1 if you want to verify/install Oracle REST Data Services schema or 2 to skip this step [1]: -- pressione ENTER

Enter the database password for ORDS_PUBLIC_USER: -- informe a senha desejada p/ o usuário ORDS_PUBLIC_USER

Confirm password: -- repita a senha do usuário ORDS_PUBLIC_USER

Requires to login with administrator privileges to verify Oracle REST Data Services schema.

Enter the administrator username: sys

Enter the database password for SYS AS SYSDBA: -- informe a senha do usuário SYS

Confirm password: -- repita a senha do usuário SYS

Enter the default tablespace for ORDS_METADATA [SYSAUX]: -- pressione ENTER

Enter the temporary tablespace for ORDS_METADATA [TEMP]: -- pressione ENTER

Enter the default tablespace for ORDS_PUBLIC_USER [USERS]: -- pressione ENTER

Enter the temporary tablespace for ORDS_PUBLIC_USER [TEMP]: -- pressione ENTER

Enter 1 if you want to use PL/SQL Gateway or 2 to skip this step. If using Oracle Application Express or migrating from mod_plsql then you must enter 1 [1]: -- pressione ENTER

Enter the PL/SQL Gateway database user name [APEX_PUBLIC_USER]: -- pressione ENTER

Enter the database password for APEX_PUBLIC_USER: -- informe a senha desejada p/ o usuário APEX_PUBLIC_USER

Confirm password: -- repita a senha do usuário APEX_PUBLIC_USER

Enter 1 to specify passwords for Application Express RESTful Services database users (APEX_LISTENER, APEX_REST_PUBLIC_USER) or 2 to skip this step [1]: -- pressione ENTER

Enter the database password for APEX_LISTENER: -- informe a senha desejada p/ o usuário APEX_LISTENER

Confirm password: -- repita a senha do usuário APEX_LISTENER

Enter the database password for APEX_REST_PUBLIC_USER: -- informe a senha desejada p/ o usuário APEX_REST_PUBLIC_USER

Confirm password: -- repita a senha do usuário APEX_REST_PUBLIC_USER

Enter 1 if you wish to start in standalone mode or 2 to exit [1]: 2

Pronto! O passo principal da instalação do ORDS já finalizou. Agora falta apenas configurar a geração de arquivos de log e criar o arquivo de gerenciamento (para fazer stop, start etc.) do serviço ORDS, que é necessário para você acessar as páginas de desenvolvimento e gerenciamento do Apex. 

4- Este passo é opcional, mas é bom seguirmos para termos um arquivo de log que nos permite identificar quais páginas do Apex estão sendo usadas, e o "quanto" estão sendo usadas. Criaremos uma pasta com nome "etc" e outra com nome "logs", dentro da pasta ORDS_HOME/config/ords/standalone, e depois criaremos dentro da pasta "etc" um arquivo com nome jetty-http.xml, com o conteúdo que segue no roteiro logo abaixo:

$ cd $ORACLE_BASE/apex19prd/ords/config/ords/standalone
$ mkdir -p etc
$ mkdir -p logs
$ cd ./logs
$ vi jetty-http.xml

<?xml version="1.0"?>
<!DOCTYPE Configure PUBLIC "-//Jetty//Configure//EN" "http://www.eclipse.org/jetty/configure.dtd">
<Configure id="Server" class="org.eclipse.jetty.server.Server">
<Ref id="Handlers">
<Call name="addHandler">
<Arg>
<New id="RequestLog" class="org.eclipse.jetty.server.handler.RequestLogHandler">
<Set name="requestLog">
<New id="RequestLogImpl" class="org.eclipse.jetty.server.NCSARequestLog">
<Set name="filename"><Property name="jetty.logs" default="XXX/apex19prd/ords/config/ords/standalone/logs"/>ords-access-yyyy_mm_dd.log</Set>
<Set name="filenameDateFormat">yyyy_MM_dd</Set>
<Set name="retainDays">90</Set>
<Set name="append">true</Set>
<Set name="extended">false</Set>
<Set name="logCookies">false</Set>
<Set name="LogTimeZone">GMT</Set>
</New>
</Set>
</New>
</Arg>
</Call>
</Ref>
</Configure>

Salve o arquivo e saia do "vi".

5- Crie o arquivo de gerenciamento do serviço do ORDS na pasta APEX_HOME, com o nome "apexl.sh" e conteúdo abaixo:

$ cd /ora00/app/oracle/product/apex19prd
$ vi apexl.sh

#!/bin/sh
#
. /etc/rc.d/init.d/functions
PORT=8888
NAME="Oracle Application Express ORDS 19.1, porta $PORT" # nome e/ou frase indicando informacoes uteis e que facilitam a identificacao do ambiente do Apex
JAVA="/xxx/apex19prd/jdk/bin/java" # local de instalacao do JDK8
ORDSWAR="xxx/apex19prd/ords/ords.war" # local de instalacao do ORDS
IMAGES="xxx/apex19prd/apex/images"
OPTIONS=" -jar $ORDSWAR standalone --port $PORT --apex-images $IMAGES"
DATE='date +%Y_%m_%d'
LOGFILE=xxx/apex19prd/apex/ords/config/ords/standalone/logs/ords-access-$DATE.log # nome do arquivo de log do dia atual
PIDFILE=xxx/apex19prd/apex/ords_listener.pid  # arquivo para guarda PID do ORDS

start() {
echo -n "Starting $NAME: "
if [ -f $PIDFILE ]; then
PID=`cat $PIDFILE`
echo APEX Listener already running: $PID
exit 2;
else
nohup $JAVA $OPTIONS 2>/dev/null >> $LOGFILE &
RETVAL=$!
echo Started PID: $RETVAL
echo
echo $RETVAL >>$PIDFILE
return $RETVAL
fi
}

status() {
echo -n "Status $NAME: "
if [ -f $PIDFILE ]; then
PID=`cat $PIDFILE`
echo ORDS already running: $PID
ps -ef | grep $PID
else
echo ORDS not running
fi
}

stop() {
if [ -f $PIDFILE ]; then
PID=`cat $PIDFILE`
echo -n "Shutting down $NAME "
echo
kill $PID
rm -f $PIDFILE
else
echo ORDS not running
fi
return 0
}

log() {
echo "Verifyng ORDS logfile of actual day: $LOGFILE"
echo "Press CTRL+C to stop"
echo "..."
tail -f $LOGFILE
}

case "$1" in
start)
start
;;

stop)
stop
;;

status)
status
;;

restart)
stop
start
;;

log)
log
;;

*)

echo "Usage: {start|stop|status|restart|log}"
exit 1
;;

esac
exit $?

6- Atribua privilégios de execução ao arquivo "apexl.sh" e inicialize o ORDS em modo standalone para permitir conexões ao Apex:

$ chmod +x apexl.sh
$ apexl.sh start

Sugiro criar uma chamada para o comando acima startar o ORDS após o startup do BD, através de uma "trigger de startup", utilizando o pacote OS_COMMAND, como citado no artigo Configurando o startup do Oracle Apex após o startup do Banco de Dados.

Obs.: Seguem abaixo outros serviços que podem executados através do script "apexl.sh" criado no passo 5:

a) Parar o ORDS:
$ apexl.sh stop

b) Verificar se o ORDS está sendo executado:
$ apexl.sh status

c) Verificar o log do ORDS:
$ apexl.sh log

d) Reiniciar o serviço do ORDS:
$ apexl.sh restart

----------------------------------------------------------------------------------------------------------------

OBSERVAÇÕES GERAIS:

Depois de instalado e configurado, as credenciais do ORDS ficam armazenadas na pasta "ORDS_HOME/config/ords", nos seguintes arquivos:

     - defaults.xml – configurações gerais, tais como conexão com banco de dados
     - standalone/standalone.properties – informações de porta e local de imagens para execução como standalone
     - conf/apex.xml – configuração do usuário APEX_PUBLIC_USER
     - conf/apex_al.xml – configuração do usuário APEX_LISTENER
     - conf/apex_pu.xml – configuração do usuário ORDS_PUBLIC_USER
     - conf/apex_rt.xml – configuração do usuário APEX_REST_PUBLIC_USER

Na pasta "ORDS_HOME/params" existe também o arquivo:
     - ords_params.properties: configurações de conexão com banco de dados, usuários do Apex, pasta de imagens.

Se precisar redefinir as conexões com banco de dados (servidor, SID ou Service_name, usuários APEX no Oracle) execute dentro da pasta ORDS_HOME o comando abaixo:

 
$ cd $ORACLE_BASE/apex19prd/ords
$ $ORACLE_BASE/apex19prd/jdk/bin/java -jar ords.war setup

Se precisar limpar uma instalação do ORDS, remova apenas as pastas e arquivos abaixo:
     - ORDS_HOME/config/
     - ORDS_HOME/params/ords_params.properties

--- Fim da instalação do ORDS 19.1 ---



Referências:
   - Oracle REST Data Services (ORDS) : Standalone Mode 
   - Oracle Application Express Installation Guide, Release 19.1 (F13754-01), March 2019
   - Oracle REST Data Services Installation, Configuration, and Development Guide, Release 19.1 (F17016-02), May 2019