# Oracle Autonomous Database Free Container Image Documentation Oracle Autonomous Database Free Container image supports 2 types of database workload types; `ADW` and `ATP`. These are similar to Transaction Processing and Data Warehouse workload type databases in Autonomous Database Serverless Cloud service. Following key features are supported: - Oracle Rest Data Services (ORDS) - APEX - Database Actions - Mongo API - Oracle Estate Explorer (OEE) The storage size is limited to 20 GB for each Database ## Using this image ### Database versions From the [released images](https://container-registry.oracle.com/ords/ocr/ba/database/adb-free), choose the database version and corresponding image to work with. We use the following naming convention: | Database version | Latest image tag | Specific release image tag | |------------------|------------------|----------------------------| | 23ai | latest-23ai | 24.11.4.2-23ai | | 19c | latest | 24.9.3.2 | ### Container CPU/memory requirements Oracle Autonomous Database Free container needs 4 CPUs and 8 GiB memory ### Install podman Please refer the official documentation to install podman on [Linux](https://podman.io/docs/installation#installing-on-linux), [Windows](https://podman.io/docs/installation#windows) or [Mac](https://podman.io/docs/installation#macos) ### Start podman machine on MacOS (x86_64) or Windows (x86_64) Containers need the Linux kernel. Run following commands to start a podman virtual machine ```bash podman machine init podman machine set --cpus 4 --memory 8192 podman machine start ``` Refer the [FAQ](#faq) to configure virtual machine on ARM machine (M1/M2 chips) ### Starting an ADB Free container > Note: Although the instructions use `podman`, the image format is compliant with both Open Container Initiative (OCI) and Docker. > ADB container works seamlessly with both OCI and Docker container runtimes. You can also use `docker` to start the container. To start an Oracle Autonomous Database Free container for **ATP** workload, run the following command ```bash podman run -d \ -p 1521:1522 \ -p 1522:1522 \ -p 8443:8443 \ -p 27017:27017 \ -e WORKLOAD_TYPE=ATP \ -e WALLET_PASSWORD=*** \ -e ADMIN_PASSWORD=*** \ --cap-add SYS_ADMIN \ --device /dev/fuse \ --name adb-free \ container-registry.oracle.com/database/adb-free:latest-23ai ``` > Note: Use `container-registry.oracle.com/database/adb-free:latest` for 19c #### On first startup of the container: - User mandatorily has to change the admin passwords. Please specify the password using the environment variable `ADMIN_PASSWORD` - Wallet is generated using the wallet password `WALLET_PASSWORD` Following table explains the environment variables passed to the container | Environment variable | Description | |----------------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | WORKLOAD_TYPE | Can be either `ATP` or `ADW`. Default value is `ATP` | | DATABASE_NAME | Database name should contain only alphanumeric characters. if not provided, the Database will be called either `MYATP` or `MYADW` depending on the passed workload type | | ADMIN_PASSWORD | Admin user password must be between 12 and 30 characters long and must include at least one uppercase letter, one lowercase letter, and one numeric. The password cannot contain username | | WALLET_PASSWORD | Wallet password must have a minimum length of eight characters and contain alphabetic characters combined with numbers or special characters. | | ENABLE_ARCHIVE_LOG | To enable archive logging in the database. Default value is True. To turn off archive logging set the value to False | > **_Note_**: For OFS mount, container should start with `SYS_ADMIN` capability. Also, virtual device `/dev/fuse` should be accessible #### Ports Note the following ports which are forwarded to the container process | Port | Description | |------|--------------------------------------| | 1521 | TLS | | 1522 | mTLS | | 8443 | HTTPS port for ORDS / APEX and Database Actions | | 27017 | Mongo API | #### HTTP proxy If you are behind a corporate proxy, there are 2 ways to configure the database to use the proxy settings 1. Set the `HTTP_PROXY` database property. This is used by packages like `DBMS_CLOUD` ```sql exec DBMS_CLOUD_CONTAINER_ADMIN.set_database_property('HTTP_PROXY', 'www-my-corp-proxy.com:80/'); ``` 2. Use `UTL_HTTP.set_proxy` to set proxy for HTTP requests sent using UTL_HTTP ```sql exec UTL_HTTP.SET_PROXY('www-my-corp-proxy.com'); ``` ### adb-cli `adb-cli` can be used to perform database operations after container is up and running To use adb-cli, you can define the following alias for convenience ```bash alias adb-cli="podman exec <container_name> adb-cli" ``` #### Available commands ```bash >> adb-cli --help Usage: adb-cli [OPTIONS] COMMAND [ARGS]... ADB-S Command Line Interface (CLI) to perform container-runtime database operations Options: -v, --version Show the version and exit. --help Show this message and exit. Commands: add-database change-password ``` #### Add Database You can add a database using the `add-database` command ```bash adb-cli add-database --workload-type "ADW" --admin-password "Welcome_1234" ``` #### Change Password To change password for Admin user, use the following command ```bash adb-cli change-password --database-name "MYADW" --old-password "Welcome_1234" --new-password "Welcome_12345" ``` ### Migrating data across containers #### Mount Volume To persist data across container restarts and removals, you should mount a volume at `/u01/data` and follow the steps mentioned in the [documentation to migrate PDB data across containers](https://docs.oracle.com/en-us/iaas/autonomous-database-serverless/doc/autonomous-docker-container.html#GUID-03B5601E-E15B-4ECC-9929-D06ACF576857) ```bash podman run -d \ -p 1521:1522 \ -p 1522:1522 \ -p 8443:8443 \ -p 27017:27017 \ -e WORKLOAD_TYPE='ATP' \ -e WALLET_PASSWORD=*** \ -e ADMIN_PASSWORD=*** \ --cap-add SYS_ADMIN \ --device /dev/fuse \ --name adb-free \ --volume adb_container_volume:/u01/data \ container-registry.oracle.com/database/adb-free:latest-23ai ``` ### Connecting to Oracle Autonomous Database Free container #### ORDS/APEX/Database Actions Container hostname is used to generate self-signed SSL certs to serve HTTPS traffic on port 8443. APEX and Database Actions can be accessed using the container host (or simply localhost) | Application | URL | |------------------|------------------------------------------------------------------------------| | APEX | https://localhost:8443/ords/apex | | Database Actions | https://localhost:8443/ords/sql-developer | > **_Note:_** For additional databases plugged in using `adb-cli add-database` command, please use the URL formats `https://localhost:8443/ords/{database_name}/apex` and `https://localhost:8443/ords/{database_name}/sql-developer` to access APEX and Database Actions respectively. #### Wallet Setup In the container, TLS wallet is generated at location `/u01/app/oracle/wallets/tls_wallet` Copy wallet to your host. ```bash podman cp adb-free:/u01/app/oracle/wallets/tls_wallet /scratch/tls_wallet ``` In this example, wallet is copied to `/scratch/tls_wallet` folder Point `TNS_ADMIN` environment variable to the wallet directory ```bash export TNS_ADMIN=/scratch/tls_wallet ``` If you want to connect to a remote host where the ADB free container is running, replace `localhost` in `$TNS_ADMIN/tnsnames.ora` with the remote host FQDN ```bash sed -i 's/localhost/my.host.com/g' $TNS_ADMIN/tnsnames.ora ``` #### Available TNS aliases Similar to Autonomous Database Serverless Cloud service, use any one of the following aliases to connect to ADB free container. ##### MYATP TNS aliases For mTLS use the following - myatp_medium - myatp_high - myatp_low - myatp_tp - myatp_tpurgent For TLS use the following - myatp_medium_tls - myatp_high_tls - myatp_low_tls - myatp_tp_tls - myatp_tpurgent_tls ##### MYADW TNS aliases For mTLS use the following - myadw_medium - myadw_high - myadw_low For TLS use the following - myadw_medium_tls - myadw_high_tls - myadw_low_tls TNS alias mappings to their connect string can be found in` $TNS_ADMIN/tnsnames.ora` file. #### TLS walletless connection To connect without a wallet, you need to update your client's truststore with the self-signed certificate generated at container start ##### Linux system truststore Copy `/u01/app/oracle/wallets/tls_wallet/adb_container.cert` from container and update your system truststore ```bash podman cp adb-free:/u01/app/oracle/wallets/tls_wallet/adb_container.cert adb_container.cert sudo cp adb_container.cert /etc/pki/ca-trust/source/anchors sudo update-ca-trust ``` ##### MacOS system trustsore For MacOS, please refer the [support guide](https://support.apple.com/guide/keychain-access/add-certificates-to-a-keychain-kyca2431/mac) to add certificate to keychain ##### JDK truststore For JDK truststore update, you can use `keytool` Linux example: ```bash sudo keytool -import -alias adb_container_certificate -keystore $JAVA_HOME/lib/security/cacerts -file adb_container.cert ``` MacOS example: ```bash sudo keytool -import -alias adb_container_certificate -file adb_container.cert -keystore /Library/Java/JavaVirtualMachines/jdk-17.jdk/Contents/Home/lib/security/cacerts ``` #### SQL Developer Desktop application Copy the wallet from the container and zip it ```bash podman cp adb-free:/u01/app/oracle/wallets/tls_wallet /scratch/tls_wallet zip -j /scratch/tls_wallet.zip /scratch/tls_wallet/* ``` Once you zip the Wallet, open SQLDeveloper and follow the below steps: 1. Click on File -> New -> Database Connection 2. Enter username / password 3. From "Connection Type" dropdown choose "Cloud Wallet" 4. Under "Configuration file" browse path to your wallet.zip 5. Select Service from the dropdown 6. Click on Connect #### SQL*Plus In this example, we connect using the alias `myatp_low` ```text sqlplus admin/<myatp_admin_password>@myatp_low SQL*Plus: Release 21.0.0.0.0 - Production on Wed Jul 26 22:38:27 2023 Version 21.9.0.0.0 Copyright (c) 1982, 2022, Oracle. All rights reserved. Last Successful login time: Wed Jul 26 2023 16:36:16 +00:00 Connected to: Oracle Database 19c Enterprise Edition Release 19.0.0.0.0 - Production Version 19.20.0.1.0 SQL> ``` #### Python Install the python-oracledb driver for Oracle Database ```bash python3 -m pip install oracledb ``` ```python import oracledb conn = oracledb.connect(user="admin", password="<myadw_admin_password>", dsn="myadw_medium", config_dir="/scratch/tls_wallet", wallet_location="/scratch/tls_wallet", wallet_password="***") cr = conn.cursor() r = cr.execute("SELECT 1 FROM DUAL") print(r.fetchall()) >> [(1,)] ``` ### Create an app user Connect as Admin ```bash sqlplus admin/<myatp_admin_password>@myatp_medium ``` Create user as shown below: ```sql CREATE USER APP_USER IDENTIFIED BY "<my_app_user_password>" QUOTA UNLIMITED ON DATA; -- ADD ROLES GRANT CONNECT TO APP_USER; GRANT CONSOLE_DEVELOPER TO APP_USER; GRANT DWROLE TO APP_USER; GRANT RESOURCE TO APP_USER; -- ENABLE REST BEGIN ORDS.ENABLE_SCHEMA( p_enabled => TRUE, p_schema => 'APP_USER', p_url_mapping_type => 'BASE_PATH', p_url_mapping_pattern => 'app_user', p_auto_rest_auth=> TRUE ); commit; END; / -- QUOTA ALTER USER APP_USER QUOTA UNLIMITED ON DATA; ``` ### Oracle Estate Explorer (OEE) [Oracle Estate Explorer](https://www.oracle.com/database/cloud-migration/estate-explorer/) is a tool that enables customers to programmatically evaluate groups of Oracle databases for migration readiness to Oracle’s Autonomous Database (ADB). The output from OEE provides a high-level estate overview of the tested group of databases, ranks them according to their alignment with ADB pre-requisites and delivers a graded relative effort of any remediation required. The OEE APEX app is installed in the adb-free images and is available to use out-of-the-box Following steps are required to launch the OEE app: 1. Login as Database admin and set a password for the `MPACK_OEE` user ```sql ALTER USER MPACK_OEE IDENTIFIED BY <PASSWORD> ``` 2. Visit the APEX URL using https://localhost:8443/ords/apex 3. Login to the `MPACK_OEE` APEX workspace using the password set in Step 1 4. Change the MPACK_OEE’s APEX account password. A warning page will be displayed after changing the MPACK_OEE’s APEX account password, please ignore it and click on Application Builder to launch the OEE application. 5. On the application home page, click "Run Application" to open the OEE app in a new browser tab. ## F.A.Q ### How can I run Oracle Autonomous Database Free container on ARM64 arch i.e. machines with M1/M2 chips ? Use colima + docker to emulate x86_64 arch. Replace podman with docker in all commands. This is only until we have a native ARM 64 image. ### How can I install colima and docker on machines with M1/M2 chips ? ```bash brew install docker brew install docker-compose brew install colima brew reinstall qemu ``` ### How can I start Colima x86_64 Virtual Machine with minimum memory/cpu requirements ? > Note: Running x86_64 arch containers can have issues translating instructions for ARM. We give higher memory to the VM to avoid such issues. ```bash colima start --cpu 4 --memory 10 --arch x86_64 ``` ### How can I start Colima x86_64 Virtual Machine using Apple's new virtualization framework - Rosetta ? > Note: Running x86_64 arch containers can have issues translating instructions for ARM. We give higher memory to the VM to avoid such issues ```bash softwareupdate --install-rosetta colima stop colima delete colima start --cpu 4 --memory 10 --arch x86_64 --vm-type vz --vz-rosetta # Verify if Colima is using the new profile docker context ls colima status ``` ### How can I start podman VM on x86_64 Mac with minimum memory/cpu requirements ? ```bash podman machine init podman machine set --cpus 4 --memory 8192 podman machine start ```