Skip to content

Latest commit

 

History

History
220 lines (198 loc) · 8.2 KB

README.md

File metadata and controls

220 lines (198 loc) · 8.2 KB
Raw

ords-config-image

This image generates configuration files and war files for Oracle Rest DataServices based on data provided by dadEdit3 database.

If you want to run this image outside of CERN, you will notice 3 things missing:

  1. dadEdit3 database (which schema you can find here
  2. Teigi service - which is CERN-internal tool and is used to as a secure password storage
  3. ORDS.war files that you have to download yourself from Oracle, due to licensing issues (see here)

Detailed How-To

Required setup

To generate the config and the war file, run the container with following environment variables set:

  1. SERVICE_NAME to the service for which the config should be generated

  2. password for dbjeedy service account should be mounted in /tmp/passwords in a file formatted like so: TAG jeedy-service/serviceaccounts.dbjeedy_pwd=XXXXX. Other account can be used using the TBAG_ACCOUNT_NAME and TBAG_SERVICE_ACCOUNT_TAG variables.

OR

  1. SERVICE_NAME to the service for which the config should be generated

  2. TBAG_ACCOUNT_PASS - The passsword to access the teigi database can be specified directly through this environment variable if working in a trusted environment. Otherwise this can be omitted and you will be asked to enter it during container startup.

Optional env variables:

Name Description Default
TBAG_SERVICE_ACCOUNT_TAG TAG used for the service account password jeedy-service/serviceaccounts.dbjeedy_pwd
TBAG_TIMEOUT Timeout for the teigi client in seconds. Only integers. 20
TNS_ADMIN location of the TNS names file in this dockerfile, if mounted from outside /ORA/dbs01/syscontrol/etc
TNSNAMES_URL URL from which the TNS names will be downloaded http://service-oracle-tnsnames.web.cern.ch/service-oracle-tnsnames/tnsnames.ora
TBAG_ACCOUNT_NAME The user that will be able to query the Secrets Manager Backend (e.g. Teigi). dbjeedy
TBAG_PASSWORD_TAGS The password tags/keys to retrieve from the Secrets Manager Backend. If we want to retrieve multiple tags/keys, they should be comma seperated (e.g. "tag1,tag2,tag3") serviceaccounts.dadedit_pwd
TBAG_SECRETS_FILE_FILENAME_FULL_PATH The full path of the file that will be created, containing the requested secrets. Please avoid using common Linux filesystem locations, as this may destroy your fs. /ORA/dbs01/syscontrol/projects/systools/etc/passwd.dadedit
TBAG_SERVICE The service to query in Teigi jeedy-service
TARGET_CONTAINER_USER The user (name or id) to change the ownership of the created file(s) 1000
TARGET_CONTAINER_GROUP The group (name or id) to change the ownership of the created file(s) 1000
VOLUME_MOUNT_DIRECTORY If you want to change the default location of generated files. It has to correspond to the config directory set in ORDS' properties (through the dadEdit3 service). /ORA/dbs01/syscontrol/local/dadEdit

Artifacts

If creating the artifacts succeeded, there should be a directory (in /ORA/dbs01/syscontrol/local/dadEdit by default) with 3 key elements:

  1. conf directory, containing all of the configuration files for ORDS
  2. wars directory, containing the preconfigured war (for SSO, non-SSO cases, pointing to the right config directory, etc.)
  3. A JSON file, containing information about the service, taken from dadEdit3.

Interacting with ORDS

To display a full list of available commands, go to the directory or folder containing the ords.war file and execute the following command:

java -jar /work-dir/artifacts/ords/wars/ords.war help

A list of the available commands is displayed. To see instructions on how to use each of these commands, enter help followed by the command name, for example:

java -jar /work-dir/artifacts/ords/wars/ords.war help configdir

Example commands

  1. Validating the ORDS schema for cerndb1
java -jar /work-dir/artifacts/ords/wars/ords.war validate --database cerndb1
  1. Change the default caching configuration to disabled
java -jar /work-dir/artifacts/ords/wars/ords.war set-property cache.caching true
  1. Create or update an user named ords_admin with role Listener Administrator
java -jar /work-dir/artifacts/ords/wars/ords.war user ords_admin "Listener Administrator"
  1. Install or upgrade Oracle REST Data Services schema, proxy user and related database objects.
java -jar /work-dir/artifacts/ords/wars/ords.war schema

Using this image for retrieving the artifacts

Specify all the required parameters and the artifacts (WARs, config files) will be generated in /ORA/dbs01/syscontrol/local/dadEdit by default, so mount a volume there.

docker run --rm -v $PWD/passwd.jeedy_service_account:/tmp/passwords/passwd.jeedy_service_account -e SERVICE_NAME=DEVORDS -v $PWD/artifacts:/ORA/dbs01/syscontrol/local/dadEdit gitlab-registry.cern.ch/jeedy/utils/ords-config-image:2.3

Getting DADs credentials

When the config files have been generated, it's possible to use the DAD information there to access the schemas. If you navigate to /work-dir/artifacts/ords/ords/<<SERVICE_NAME>>/ords/conf, you can find the DAD configuration there.

If there's incosistency with the name of the DAD config file name with the database name, see the url-mapping.xml file in /work-dir/artifacts/ords/ords/<<SERVICE_NAME>>/ords.

This image comes pre-installed with sqlplus for convenience.

QA

Q: How does ords.war know where the configuration files are?

A: In the WEB-INF/web.xml in ords.war there's a line specifying the config directory. It can be changed either manually (editing the web.xml and repacking) or we can let ORDS handle it - java -jar /work-dir/artifacts/ords/wars/ords.war config <<new-path-to-config>>

Q: I just want to quickly test some new features/settings/bugs of ORDS locally, but against the exisiting DBs. How do I?

A: In that case you might want to try ORDS' standalone mode: java -jar /work-dir/artifacts/ords/wars/ords.war standalone

Q: Wow, ORDS is so amazing, I want to know more and follow all the latest updates! Do you know any awesome resources?

A: Yes, see: