Oracle#
This page covers the plain-language Oracle connection check that release.sh runs on Citadel and that squire doctor oracle runs from your terminal, and the two opt-in Oracle-ready Docker images Squire ships for local work. Next, read Citadel setup to wire the release script into the dashboard, or Local parity to run the app on the real images.
The connection check#
The release runs an Oracle connection check (oracle-check.php) after PROCTOR and before the smoke test. It is a report, never a gate: a finding prints in the deployment log and the release goes on. When the app does not use Oracle (no ORACLE_* settings) it prints nothing.
It checks, in order:
- the settings are present,
- the host resolves,
- the port answers within 3 seconds,
- the
oci8driver is loaded, - the login works.
The check stops at the first failure, so a bad port never costs a login attempt. Only setting names are ever printed, never values.
Settings: ORACLE_USERNAME, ORACLE_PASSWORD, and either ORACLE_TNS (Easy Connect host:port/service, or a full (DESCRIPTION=...) descriptor) or ORACLE_HOST, ORACLE_PORT and ORACLE_SERVICE_NAME.
squire doctor oracle#
vendor/bin/squire doctor oracle runs the same plain-language Oracle connection check that release.sh runs on Citadel, from your terminal or sail php vendor/bin/squire doctor oracle. It reads the ORACLE_* settings from the environment and the app's .env, prints setting names and never values, and stays silent when the app has no Oracle settings. Add -v for the client version.
Oracle-ready images (local)#
Apps that talk to Oracle need the Instant Client and the oci8 extension. Squire ships two opt-in Docker recipes that carry both, so nobody compiles them by hand:
squire/oracle-sail:<php>: Laravel Sail's own runtime plus the Oracle install. In yourdocker-compose.yml, swap the service'sbuild:block forimage: squire/oracle-sail:8.4and keep the rest of the service as Sail wrote it; the image keeps Sail's entrypoint contract, including theWWWUSERUID remap.squire/oracle-parity:<php>: the officialphp:<php>-cli-bookwormimage with the extensions Citadel apps use (intl, ldap, soap, zip, gd, pdo_mysql, mysqli, bcmath, pcntl, exif, redis, imagick), Composer and git, plus the Oracle install. This is the flavor WELD'scompose.oracle.yamlpoints its services at. It runs as a non-rootappuser whose UID is a build argument (APP_UID) and can still be overridden at run time.
The names above are the local names of scripts/oracle-image-build.sh. The published images live in the group's images project (the stack's shared image registry; Squire's own GitLab has no container registry), at <registry>/enterprise-apps/images/squire-oracle-parity:8.4 and <registry>/enterprise-apps/images/squire-oracle-sail:8.4 (<registry> is the registry address of the images project shown on its Container Registry page), plus :8.4-<squire version> for a fixed one; a Sail app swaps build: for image: with that path.
Every tag so far published linux/arm64 only. From Squire 0.10.5, a tag publishes both flavors for PHP 8.3, 8.4 and 8.5 for linux/arm64: Apple silicon Macs and arm64 Linux hosts can pull them. The pipeline now builds linux/amd64 natively on an amd64 runner as well, so the next tag publishes both architectures in one list; until a tag has, on an amd64 computer, Citadel-shaped hosts included, build the images locally with scripts/oracle-image-build.sh (below). Pulling a tag that predates the first multi-arch one on amd64 fails with "no matching manifest for linux/amd64", which is the image's way of saying the same thing.
The 0.10.5 tag published all six (linux/arm64). Pin the fixed tag with its list digest so a pull always gets the same bytes:
| Image | List digest |
|---|---|
squire-oracle-sail: |
sha256: |
squire-oracle-sail: |
sha256: |
squire-oracle-sail: |
sha256: |
squire-oracle-parity: |
sha256: |
squire-oracle-parity: |
sha256: |
squire-oracle-parity: |
sha256: |
So a Sail app on an Apple silicon Mac writes image: <registry>/enterprise-apps/images/squire-oracle-sail:8.4-0.10.5@sha256:3d942883ea31c802e2a958542697941c6bff4b36989931e12e2c24289b690a87. Later tags are listed in MAINTAINING.md, What each tag published.
Both flavors download Oracle's Instant Client Basic Light at build time under Oracle's license and never commit it: the install script pins the exact SHA-256 of each zip. Oracle does not publish a 21.x client for arm64, so the line differs per architecture: linux/amd64 gets 21.7.0.0.0 and linux/arm64 gets 19.32.0.0.0.
scripts/oracle-image-build.sh --flavour sail --php 8.4 # or: --flavour parity
scripts/oracle-image-test.sh --flavour all --platform linux/amd64