Oracle Instant Client Setup
PCR360 requires Oracle Instant Client on the host machine when using an Oracle database. The client is not bundled in the Docker image — it is bind-mounted from the host into the web container at runtime.
Skip this guide entirely if you are using MySQL.
Which version to use
|
Oracle database version |
Instant Client version |
|---|---|
|
Oracle 19c ADB |
IC 19.x (e.g. 19.28) |
|
Oracle DB 12.1+ |
IC 21 |
1. Download Instant Client
Download the RPM packages from Oracle (requires an Oracle account):
https://www.oracle.com/database/technologies/instant-client/linux-x86-64-downloads.html
Alternatively, copy the RPMs from yum.oracle.com/OL8 or from an existing Oracle server.
Packages needed:
-
oracle-instantclient-basic -
oracle-instantclient-sqlplus -
oracle-instantclient-sdk
2. Install to the host
# Install the RPMs directly
sudo dnf install -y oracle-instantclient19.28-basic-*.rpm \
oracle-instantclient19.28-sqlplus-*.rpm \
oracle-instantclient19.28-sdk-*.rpm
The RPMs install the shared libraries to:
/usr/lib/oracle/<version>/client64/lib/
For example, IC 19.28 installs to /usr/lib/oracle/19.28/client64/lib/. Use this path as ORACLE_IC_PATH in .env.
The directory must contain the shared libraries, and a network/admin/ subdirectory with the Oracle Net configuration files:
/usr/lib/oracle/19.28/client64/lib/
├── libclntsh.so (and other .so files)
└── network/
└── admin/
├── sqlnet.ora (required — must include EZCONNECT for Easy Connect strings)
└── tnsnames.ora (required if using TNS aliases for DB_NAME)
sqlnet.ora minimum content (Easy Connect & TNS aliases):
NAMES.DIRECTORY_PATH = (EZCONNECT, TNSNAMES)
For ADB with mTLS wallet, copy the wallet files into network/admin/:
/usr/lib/oracle/19.28/client64/lib/network/admin/
├── sqlnet.ora (from your ADB wallet download)
├── tnsnames.ora (from your ADB wallet download)
├── cwallet.sso
└── ewallet.p12
3. Configure .env
Set these values in .env before building or starting the stack:
ORACLE_CLIENT_VERSION=19.28 # must match the IC version you installed
ORACLE_IC_PATH=/usr/lib/oracle/19.28/client64/lib
ORACLE_NLS_LANG=AMERICAN_AMERICA.AL32UTF8
The IC directory is bind-mounted read-only into the web container at startup. The entrypoint runs ldconfig so libclntsh.so is found by the PHP oci8 extension.
4. Verify the bind-mount
After the container starts, confirm the IC is visible inside it:
docker exec pcr360-web-test-1 ls /usr/lib/oracle/19.28/client64/lib/libclntsh.so
docker exec pcr360-web-test-1 php -r "echo phpversion('oci8');"
The second command should print the oci8 extension version (e.g. 3.3.0).