Guia de Instalação do Oracle Application Express (APEX)

Esse manual visa servir de guia de instalação do Oracle Apex em banco de dados Oracle, tanto em servidor on premisse quanto em estrutura no Cloud. Esse guia já foi utilizado para a instalação a partir da versão 18 do Apex (atualmente estamos na versão 20) em bancos de dados Oracle 11, 12 e 18.

O primeiro passo para instalar o Oracle Apex é baixá-lo diretamente do site da Oracle, por meio do link https://www.oracle.com/technetwork/developer-tools/apex/downloads/index.html. Nessa página é apresentada a última versão lançada do Oracle Apex. Versões anteriores à última publicada podem ser encontradas no link Prior Release Archives). Recomendamos que seja baixada a versão all languages. Ela conterá os pacotes de idiomas disponíveis para que você possa alterar para a tradução de sua preferência. Para realizar o download lembre-se de primeiro aceitar os termos e condições no início do site.

Ao clicar no link de download você será levado à página de login da Oracle. Se não tiver um usuário cadastrado, será necessário criá-lo. Isso é gratuito e necessário para qualquer download que você deseje fazer na Oracle.

Após o download você terá um arquivo zip com nome APEX_NN.N.ZIP onde NN.N representa a versão (18.1, 18.2, 19.1, etc). Neste guia iremos usar como exemplo a versão 19.1, portanto nosso arquivo será APEX_19.1.ZIP.

O arquivo baixado precisa ser descompactado em uma pasta de sua preferência. Lembre-se de usar uma estrutura de pastas de nomes curtos e sem espaços e acentuações para não ter problemas ao rodar os scripts de instalação do APEX. Em nosso exemplo iremos extrair o arquivo em uma pasta temp. Após a descompactação os arquivos de instalação do APEX estarão localizados na pasta \temp\apex e terão os seguintes arquivos e pastas:

Com o arquivo descompactado, iremos iniciar a instalação propriamente dita. Para tanto será necessário acessar o SQLPLUS com um usuário com direitos de administrador em seu servidor, e logar nele com o usuário SYS em modo SYSDBA. Lembre-se, antes de entrar no SQLPLUS, de estar dentro da pasta onde os arquivos do APEX foram descompactados.

Caso esteja realizando a instalação em um banco de dados plugável, é necessário ajustar a sessão para o PDB do banco em questão, usando o comando abaixo:

SQL> Alter session set container=<NOME_DO_PDB>;

Lembre-se que o apontamento do PDB deverá ser realizado sempre que tiver que entrar no SQLPLUS durante a instalação, pois esse ajuste afeta somente a sessão logada.

A partir desse ponto iremos rodar alguns scripts do Oracle para realizar a instalação. Caso ao término de algum script você tenha saído do SQLPLUS, basta entrar novamente como explicado anteriormente.

O primeiro script a ser executado é o de instalação do APEX propriamente dito. Existem duas versões desse script. O apexins.sql instala o APEX completo, com as ferramentas de criação de aplicativos. O apxrtins.sql instala a versão run-time, que não permite criar ou editar ferramentas, mas somente executá-las.

Se a opção for pela instalação da versão full, execute o script conforme a linha abaixo:

SQL> @apexins.sql SYSAUX SYSAUX TEMP /i/

Caso a opção seja pela versão run-time, execute o segunte script com os respectivos parâmetros:

SQL> @apxrtins.sql SYSAUX SYSAUX TEMP /i/

Com esses parâmetros, as tabelas e demais objetos do APEX serão instalados no tablespace SYSAUX e usará como tablespace temporário o TEMP. Caso queira instalar em outro tablespace ou tenha outro nome para o temporário, basta trocar os parâmetros para os nomes desejados.

Os demais passos serão iguais tanto para a versão full quanto para a versão run-time.

O próximo passo servirá para definir o acesso do administrador do APEX. Para isso basta executar o script abaixo:

SQL> @apxchpwd.sql

Durante a execução o Oracle irá lhe pedir um nome para o administrador, sugerindo ADMIN, que pode ser mantido.

Em seguida ele pedirá um e-mail para o administrador. Entre seu e-mail e tecle ENTER.

Por fim, informe uma senha de sua preferência. Não são permitidas senhas com @ e senha simples. Precisa conter letras maiúsculas, minúsculas, números e caracteres especiais.

Agora será executada uma procedure que irá definir a porta que será usada pelo APEX, que será conectado pelo PL/SQL Gateway. Se a porta for definida para zero o serviço do PL/SQL Gateway será desabilitado. Isso será útil caso queira usar outro método de conexão para acessar o Oracle APEX, como o Oracle ORDS por meio do Tomcat, por exemplo. Normalmente a porta utilizada é a 8282, porém ela pode ser substituída pela porta de sua preferência (Lembre-se de liberar o acesso à porta escolhida em seu firewall):

SQL> EXEC DBMS_XDB.SETHTTPPORT(8282);

Nossa próxima tarefa é desbloquear o usuário APEX_PUBLIC_USER e trocar sua senha, usando os comandos abaixo:

SQL> ALTER USER APEX_PUBLIC_USER ACCOUNT UNLOCK; 
SQL> ALTER USER APEX_PUBLIC_USER IDENTIFIED BY <SENHA>; 

Após desbloquear o usuário do APEX devemos configurar os serviços de ouvinte dele e definir suas senhas. Para isso executamos os scritps abaixo e informamos os passwords quando solicitado:

SQL> @apex_rest_config.sql

Por fim vamos subir para o Oracle as imagens do APEX, por meio dos scripts abaixo, nos atentando que ao colocar o caminho dos arquivos do APEX é altamente recomendado que se use o caminho completo, inclusive referenciando a unidade de armazenamento.

SQL> @apex_epg_config.sql <Caminho dos arquivos do APEX>
SQL> @apxldimg.sql  <Caminho dos arquivos do APEX> 

Seguindo os passos acima o APEX já estará instalado em seu servidor e para acessá-lo basta usar em seu browser o endereço https://<ip_do_servidor>:<porta_apex>/apex. Caso esteja testando diretamente do servidor e tenha mantido a porta default do APEX (8282), o endereço ficaria https://127.0.0.1:8282/apex.

Algumas vezes você pode receber uma tela dizendo que é necessário informar o usuário e senha para acessar o XDB. Isso acontece por conta de direitos para o usuário anonymous do Oracle. Para conceder esses direitos faltantes ao usuário basta executar os comandos abaixo no SQLPLUS com o usuário SYS.

-- Dá direitos de DAV:READ ao usuário ANONYMOUS
 SET SERVEROUTPUT ON
 DECLARE
  l_configxml XMLTYPE;
  l_value VARCHAR2(5) := 'true'; -- (true/false)
  BEGIN
  l_configxml := DBMS_XDB.cfg_get();
 IF l_configxml.existsNode('/xdbconfig/sysconfig/protocolconfig/httpconfig/allow-repository-anonymous-access') = 0 THEN
  -- Add missing element.
  SELECT insertChildXML
  (
  l_configxml,
  '/xdbconfig/sysconfig/protocolconfig/httpconfig',
  'allow-repository-anonymous-access',
  XMLType('' ||  l_value ||  '
'),
  'xmlns="http://xmlns.oracle.com/xdb/xdbconfig.xsd"'
  )
  INTO l_configxml
  FROM dual;
 DBMS_OUTPUT.put_line('Element inserted.');
  ELSE
  -- Update existing element.
  SELECT updateXML
  (
  DBMS_XDB.cfg_get(),
  '/xdbconfig/sysconfig/protocolconfig/httpconfig/allow-repository-anonymous-access/text()',
  l_value,
  'xmlns="http://xmlns.oracle.com/xdb/xdbconfig.xsd"'
  )
  INTO l_configxml
  FROM dual;
 DBMS_OUTPUT.put_line('Element updated.');
  END IF;
 DBMS_XDB.cfg_update(l_configxml);
  DBMS_XDB.cfg_refresh;
END;
/

*** Caso o script acima apresente problema ao executar, utilize o download do mesmo clicando aqui. ***

Após executar o procedimento para dar direitos ao usuário anonymous, ajuste novamente a porta do Oracle APEX, confirme os dados no banco de dados e desbloqueie o usuário anonymous, seguindo os comandos abaixo:

SQL> EXEC DBMS_XDB.SETHTTPPORT( <porta_apex>);
SQL> commit;
SQL> Alter user anonymous account unlock;

Feito isso o APEX já está pronto para ser usado, porém somente com o idioma inglês. Para alterá-lo devemos rodar o script referente ao idioma desejado. Os scripts de idiomas se encontram na pasta builder, onde existem as pastas de cada idioma disponível, conforme mostra a figura abaixo:

Aqui vamos instalar o pacote de idioma Português (Brasil) que está na pasta pt-br. Para tanto iremos rodar o script load_pt-br.sql com o usuário sys porém antes devemos apontar o schema corrente para a versão do Apex que instalamos, conforme os comandos abaixo:

SQL> Alter session set current_schema=APEX_190100;
SQL> @load_pt-br.sql

Agora o Oracle Apex está instalado e pronto para ser utilizado, tanto no idioma inglês quanto no português.

Vale destacar que essa instalação foi feita usando a conexão para o Oracle APEX usando o PL/SQL Gateway. Essa conexão é indicada para ambientes de desenvolvimento ou testes. Para ambientes de produção sugerimos usar a conexão pelo Oracle ORDS por meio do Tomcat, que será explicada em outro artigo futuramente.