# Oracle REST Data Services Docker image 24.1.1 ## Description This container will start a server instance with ORDS (Oracle Rest Data Services) and APEX (Oracle Application Express). At startup the container will install or upgrade ORDS and APEX in the specified database. The target default database pool for ORDS is specified in a file (conn_string.txt) that the container reads at startup. The database connection string is necessary to install/upgrade the database components. The file is deleted during the startup process. Although the container is intended to be removed when the container stops the ORDS and APEX database components will remain in the database available for other ORDS instances. **Note:** This image is for testing purposes only, as such it is unsupported and should not to be used in a production environment. - A mid-tier Java application, ORDS provides a Database Management REST API, SQL Developer Web, a PL/SQL Gateway, SODA for REST, and the ability to publish RESTful Web Services for interacting with the data and stored procedures in your Oracle Database. See https://www.oracle.com/rest for more information. - Oracle Application Express (APEX) is a low-code development platform that enables you to build scalable, secure enterprise apps, with world-class features, that can be deployed anywhere. See https://apex.oracle.com/ for more information. ## Version matrix Each image uses Oracle Linux with a specific version of ORDS and APEX. When an image is published it is tagged with the ORDS version it contains. In general, the version of APEX included in the image is the released version publicly available at the time the image was created. It is advised to always use the image with the `latest` tag so that the most recent ORDS and APEX is used. - 24.1.1 - ORDS 24.1.1 and APEX 23.2.0 ## Pulling the image ``` docker pull container-registry.oracle.com/database/ords:latest ``` ## Installing ORDS on your DB. Using the image for the first time, create a directory for the conn_string.txt file which will hold the connection string that the container will use. That directory will be mapped as a specific volume when starting the container. The below command will create conn_string.txt with `user/password@hostname:port/service_name` specified in the CONN_STING. Replace `user`, `password`, `hostname`, `port`, and `service_name` with the actual database connection details. Also, you can create a docker volume or directory for ORDS configurations. ``` mkdir ords_secrets ords_config chmod 777 ords_config echo 'CONN_STRING=user/password@hostname:port/service_name' > ords_secrets/conn_string.txt ``` Run the container... ``` docker run --rm --name ords -v `pwd`/ords_secrets/:/opt/oracle/variables -v `pwd`/ords_config/:/etc/ords/config/ -p 8181:8181 container-registry.oracle.com/database/ords:latest ``` Replace the container name, directory name and host port number as appropriate. **Note:** If you have doubts about connection strings or credentials please check the Important Notes section. ## Using an ORDS configuration volume. You can set a configuration mount with your ORDS configurations pointing to /etc/ords/config and the container will try to start the service with configurations on the mount point. Run the container with ords configurations mount ... ``` docker run --rm --name ords -v `pwd`/ords_secrets/:/opt/oracle/variables -v `pwd`/ords_config/:/etc/ords/config/ -p 8181:8181 container-registry.oracle.com/database/ords:latest ``` **Note:** If you start by the second time your container and you have provided a volume for configuration the first time, is not necessary to provide again the connections string file, The container will start ORDS with the configuration saved on configuration volume. But if you provide both, a configuration volume and connections string file, The container before starting ORDS will validate if APEX is installed or need to be upgraded and then will reconfigure this APEX if is necessary and then start ORDS. ## Start ORDS with a preset configuration. To run the container without installing/upgrading your DB, do not provide the conn_string.txt and provide a config folder with a valid configuration. ``` docker run --rm --name ords -v `pwd`/ords_config/:/etc/ords/config/ -p 8181:8181 container-registry.oracle.com/database/ords:latest ``` ## Set an SSL configuration. To start a secure service on the ORDS container, create a folder called "ssl", put your Certificate and Key files in this folder, the files needs to be named "cert.crt" and "key.key". ``` mkdir -p ords_config/ssl cp cert_file.crt ords_config/ssl/cert.crt cp key_file.key ords_config/ssl/key.key ``` Start the service with the configuration volume ... ``` docker run --rm --name ords -v `pwd`/ords_secrets/:/opt/oracle/variables -v `pwd`/ords_config/:/etc/ords/config/ -p 8181:8181 container-registry.oracle.com/database/ords:latest ``` If the container detects the certificate and key files it will start the ORDS service on secure mode. ## Custom scripts. If you need to run a custom script on the container you can add a volume with shell scripts pointing to /ords-entrypoint.d. ``` docker run --rm --name ords -v /custom_scripts_path/:/ords-entrypoint.d/ -v `pwd`/ords_secrets/:/opt/oracle/variables -v `pwd`/ords_config/:/etc/ords/config/ -p 8181:8181 container-registry.oracle.com/database/ords:latest ``` The ontainer will install/upgrade APEX and ORDS and before start the ORDS service will run alphabetically all the shell scripts on /ords-entrypoint.d. ## Login to APEX Open browser on localhost with the mapped port by docker (http://localhost:8181/ords) and use below credentials: ``` - Workspace: internal - User: ADMIN - Password: Welcome_1 ``` It is strongly recommend that this password is changed. ## Start container with IGNORE_APEX variable Setting up the `IGNORE_APEX=TRUE` variable, the container will not install, upgrade or configure Oracle APEX on your Database. ``` docker run --rm -e IGNORE_APEX=TRUE --name ords -v `pwd`/ords_secrets/:/opt/oracle/variables -p 8181:8181 container-registry.oracle.com/database/ords:latest ``` ## Important Notes - The conn_string.txt file is mandatory and must be mounted on /opt/oracle/variables/ directory in the container - The CONN_STRING variable in that file must in this format: CONN_STRING=user/password@hostname:port/service_name - The conn_string.txt file will be deleted when the container starts. The database connection details are not held in environment variables in the container. - The database credentials specified must have SYSDBA access because this is the database account that will be used to install/upgrade APEX and ORDS database components. - If the database already has an earlier version of APEX installed the container will upgrade it to the version packaged in the container. That is if the major versions of the release are the same. For compatibility in the upgrade process, should the major versions of the APEX release not be the same then the container will stop.