APEX Deployment Tool - Setup

T

The most complicated part about ADT is the installation. But don't worry, it is not that complicated and everything after that is super easy.

This is part of multiple ADT articles:

• Introduction & workflow
• Setup connections, config, folder structure (this article)
• Recompile invalid objects
• Searching APEX and searching repo for objects
• Export APEX & live upload
• Export database objects
• Automated patching & deployment

Install

There is an Install guide in the repo, but in this article I will cover it in more details. You will need Python with some modules, SQLcl, possibly also Instant Client and Git. Here are the steps:

• clone ADT repo (lets say you clone it here: ~/Documents/ADT/)
• install any Git client, go for GitHub Desktop if you are new to this
• install Python 3.11 (and NOT 3.12 or higher)
• install SQLcl 24.1
• install Instant Client 19.16 - required for thick connections (also you might need Java too), you can skip this step if you are going to connect to OCI or if your target instance has passwords compatibility mode above 11g and you can install IC 21 on Windows
• make sure you have executables of Python, Git, Instant Client and SQLcl in your path
• install Python modules (like OracleDB) used by the ADT:
  

  pip3 install --upgrade pip
  pip3 install -r ~/Documents/ADT/requirements.txt --upgrade
  

• open your .zshrc or .bash_profile and add lines from .zshrc section below (on Windows)

Modify your .zshrc file

If you are on Windows, you have to create equivalent of this. Don't forget to adjust paths to your locations.

#export LANG=en_US.UTF-8
#export ARCH=x86_64
export ORACLE_HOME=~/instantclient_19_16
export DYLD_LIBRARY_PATH=$ORACLE_HOME
export LD_LIBRARY_PATH=$ORACLE_HOME
export OCI_LIB_DIR=$ORACLE_HOME
export OCI_INC_DIR=$ORACLE_HOME
export PATH=$PATH:$ORACLE_HOME:~/sqlcl/bin
export DBVERSION=19

alias python=/Library/Frameworks/Python.framework/Versions/3.11/bin/python3

export ADT_KEY=PASSWORD     # your password for encrypting/decrypting connections
export ADT_ENV=DEV          # your default environment name

function adt {              # add function so you can keep your prompts clean
    script=$1
    shift
    clear; python ~/Documents/ADT/$script.py "$@"
}

I am not a Windows user, but you would need something like this:

set LANG=en_US.UTF-8
set ARCH=x86_64
set ORACLE_HOME=C:\Users\USER_NAME\instantclient_21_10
set CLIENT_HOME=C:\Users\USER_NAME\instantclient_21_10
set TNS_ADMIN=C:\Users\USER_NAME\instantclient_21_10
set CLASSPATH=%ORACLE_HOME%
set DYLD_LIBRARY_PATH=%ORACLE_HOME%
set LD_LIBRARY_PATH=%ORACLE_HOME%
set OCI_LIB_DIR=%ORACLE_HOME%
set OCI_INC_DIR=%ORACLE_HOME%\sdk\include
set JAVA_HOME=C:\Program Files\Java\jdk-17\

set PATH=%PATH%;%ORACLE_HOME%;%ORACLE_HOME%\sqlcl\bin
set PATH=%PATH%;C:\Users\USER_NAME\AppData\Local\GitHubDesktop\app-3.3.12\resources\app\git\mingw64\bin\
set GIT_PYTHON_REFRESH=quiet
set GIT_PYTHON_GIT_EXECUTABLE=C:\Users\USER_NAME\AppData\Local\GitHubDesktop\app-3.3.12\resources\app\git\mingw64\bin\git.exe

set ADT_KEY=PASSWORD
set ADT_ENV=DEV

Configure ADT

At this point you should have everything installed, you can verify it in your Terminal (command line on Windows).

cd ~/Documents/YOUR_PROJECT_REPO/; adt config -version

If you are not able to create the `adt` function, then you would have to replace it this way. Just replace `adt action` with `python ~/Documents/ADT/action.py`. You can see available actions as files in ADT root.

cd ~/Documents/YOUR_PROJECT_REPO/; adt config -version
cd ~/Documents/YOUR_PROJECT_REPO/; python ~/Documents/ADT/config.py -version

You should see something like this:

Create connection

You made it. The most difficult part is behind you. Now lets connect to your database so you can start using ADT.

If you are connecting to OCI, you have to get the wallet first. Unzip your wallet to `config/` folder in your project folder. So if my instance name is `DEV23AI` then you should have wallet files in `~/Documents/YOUR_PROJECT_REPO/config/Wallet_DEV23AI/`.

If you run any ADT action (file in root) without arguments, you will get the help. For `adt config` you will get this:

Minimum arguments required to create a connection to OCI:

adt config -create -user USER_NAME -pwd USER_PASSWORD -service SERVICE_NAME -wallet WALLET_NAME -wallet_pwd WALLET_PASSWORD

For on-premise database:

adt config -create -schema SCHEMA_NAME -user USER_NAME -pwd USER_PASSWORD -hostname HOST_NAME -service SERVICE_NAME
adt config -create -schema SCHEMA_NAME -user USER_NAME -pwd USER_PASSWORD -hostname HOST_NAME -sid SID

This will create `config/connections.yaml` file in your project folder, connect to the database and list database and APEX versions. You can modify the file manually anytime you want. If you didn't setup `ADT_KEY` and didn't provided `-key` argument, your passwords will not be encrypted in this YAML file.

I would also recommend to add whole `config/` folder to your `.gitignore` file.

Support

If you have issues, you can try to reach me on LinkedIn.