Beginners Guide

This guide installs an Oracle AI Database 26ai with a container database DB1 and the PDB ORCLPDB on an Oracle Linux 9 VM with ansible-oracle.

1. Overview

1.1. Architecture overview

1.2. What are we going to do?

Prepare the Ansible controller: Ansible in Ubuntu on WSL2 on Windows.
Configure the inventory with the IP address and login user of the Oracle Linux 9 VM.
Start the playbook playbooks/do_all.yml. It executes all needed playbooks:
1. opitzconsulting.ansible_oracle.os: prepare the VM for AutoUpgrade
2. playbooks/autoupgrade.yml: install AutoUpgrade on the VM and download a gold image from My Oracle Support. The gold image is a complete ORACLE_HOME including the Release Update.
3. opitzconsulting.ansible_oracle.single_instance_fs: configure the OS, install the ORACLE_HOME from the gold image and create the database.

1.3. Defaults

Table 1. Defaults used in this guide
Value	Description
`~/git/ansible-oracle`	git repository on the Ansible controller
`~/git/ansible-oracle/example/beginner/ansible`	Working directory for all Ansible commands
`beginner-dbfs`	Name of the VM in the inventory
`192.168.66.161`	IP address of the VM (`ansible_host`)
`ol`	Login user on the VM (`ansible_user`)
`/u01/sw`	Installation media on the VM, target of the download (`oracle_sw_source_local`)
`/u01/stage`	Staging directory on the VM (`oracle_stage`)

2. Requirements

2.1. Oracle Linux 9 VM

Any Oracle Linux 9 VM matching the requirements below can be used. See Create the VM with Hyper-V and Packer for an example with Hyper-V on Windows.

Table 2. Requirements for the VM
Item	Requirement
Operating system	Oracle Linux 9 x86_64
CPU	2 vCPUs (recommended)
Memory	8 GB RAM (recommended)
Disk	`/dev/sda` with the volume group `ol` on `/dev/sda3`. The volume group needs min. 81 GB free space for swap (16 GB), `/u01` (40 GB) and `/u02` (25 GB). See `host_fs_layout` in `group_vars/all/host.yml`.
Network	Fixed IP address, reachable from the Ansible controller with SSH
Internet	Access to the Oracle Linux yum repositories and to My Oracle Support for AutoUpgrade (`updates.oracle.com`, `login-ext.identity.oraclecloud.com`, `aru-akam.oracle.com`)
Login user	User with SSH login and `sudo` privileges, e.g. `ol`

2.2. Create the VM with Hyper-V and Packer

The repository packer-hyperv builds an Oracle Linux 9 template with Packer and creates the VM for this guide on Hyper-V. See the README of the repository for the installation of packer and task.

Important

All steps in this chapter are executed in PowerShell on Windows, not in WSL.

The template uses

the login user ol with sudo privileges and SSH key login,
the volume group ol on /dev/sda3, as expected by host_fs_layout in this guide, and
the SSH public key %USERPROFILE%\.ssh\id_ed25519.pub.

Clone the repository

git clone https://github.com/Rendanic/packer-hyperv.git
cd packer-hyperv

Allow Hyper-V for the current user (once, elevated PowerShell, log off and on afterwards)

task hyperv:hyperv-add-admin-user

Build the Oracle Linux 9 template

task hyperv:packer-ol9

Build the template with another SSH public key

task hyperv:packer-ol9 SSH_KEY_FILE=C:\path\to\key.pub

Create the VM from the template

cd OL9
.\create-vm.ps1 -NewVMName beginner-dbfs -Hostname beginner-dbfs -ExternalSwitch intern_66 -FixedIP 192.168.66.161 -CPUs 2 -MemoryGB 8

create-vm.ps1 creates the VM with two network adapters:

Default Switch with DHCP for the internet access
the switch from -ExternalSwitch with the fixed IP address from -FixedIP. Use this address for ansible_host in inventory/hosts.yml.

Important

The template has a disk with 80 GB. The volume group ol has approx. 60 GB free space then, but the guide needs 81 GB.
Increase the disk of the VM, e.g. to 130 GB, before you start the installation.

Note	The SSH public key of the template must belong to the private key of the Ansible controller. Copy the key pair from Windows into WSL or use the public key from WSL for `SSH_KEY_FILE`.

2.3. Ansible controller

This guide uses Ubuntu on WSL2 on Windows as Ansible controller.

Note	Optionally, the database VM can be used as Ansible controller as well. Install the packages with `dnf` instead of `apt` in this case, e.g. `sudo dnf install -y git python3`. `ansible_host` and `ansible_user` in the inventory are used the same way, the VM connects to itself with SSH.

Table 3. Requirements for the Ansible controller
Item	Requirement
Python	Python 3 with `venv`
Ansible	`ansible-core` >= 2.16
Internet	Access to GitHub and Ansible Galaxy

AutoUpgrade is executed on the VM, not on the Ansible controller. Java and the gold image are not needed on the Ansible controller.

2.4. My Oracle Support

A My Oracle Support account is needed for the download of the gold image.

3. Setup Ansible controller

Important

All steps are executed on the Ansible controller.

Install packages

sudo apt update
sudo apt install -y git python3-venv

Clone git repository

mkdir -p ~/git
cd ~/git

git clone https://github.com/oravirt/ansible-oracle.git

Create a Python virtual environment with Ansible

python3 -m venv ~/venv/ansible-oracle
source ~/venv/ansible-oracle/bin/activate

cd ~/git/ansible-oracle
pip install -r tools/dev/requirements_dev_2.16.txt

Tip	`tools/dev/requirements_dev_2.19.txt` installs ansible-core 2.19 instead of 2.16.

Important

Activate the virtual environment in each new shell with source ~/venv/ansible-oracle/bin/activate.

Install collections

cd ~/git/ansible-oracle/example/beginner/ansible
ansible-galaxy collection install -r requirements.yml

4. Configure inventory

4.1. IP address and login user

The VM is configured in inventory/hosts.yml. Change ansible_host and ansible_user for your VM.

inventory/hosts.yml

---
all:
  children:
    dbfs:
      hosts:
        beginner-dbfs:
          # IP address or DNS name of the Oracle Linux 9 VM
          ansible_host: 192.168.66.161
          # Login user on the VM with sudo privileges (SSH key login)
          ansible_user: ol

Note	`beginner-dbfs` is only the name of the host in the inventory. The host specific variables are in `inventory/host_vars/beginner-dbfs/`. Rename the directory as well, when you change the name.

4.2. SSH key

Ansible connects with an SSH key to the VM.

Create SSH key (skip it, when a key exists already)

ssh-keygen -t ed25519

Copy the public key to the VM

ssh-copy-id ol@192.168.66.161

4.3. Check the connection

Connection test

cd ~/git/ansible-oracle/example/beginner/ansible
ansible all -m ansible.builtin.ping

Test of sudo

ansible all -b -m ansible.builtin.command -a id

Tip	Add `--ask-become-pass` (`-K`) to all `ansible` and `ansible-playbook` commands, when `sudo` requires a password for the login user.

4.4. My Oracle Support credentials

The My Oracle Support credentials are read from the environment variables MOS_USERNAME and MOS_PASSWORD.

My Oracle Support credentials

export MOS_USERNAME=<your My Oracle Support login>
read -s MOS_PASSWORD && export MOS_PASSWORD

Alternatively, store the credentials in the file .env in the working directory and load it into the shell before starting ansible-playbook.

~/git/ansible-oracle/example/beginner/ansible/.env

MOS_USERNAME=<your My Oracle Support login>
MOS_PASSWORD=<your My Oracle Support password>

Load .env into the shell

cd ~/git/ansible-oracle/example/beginner/ansible
set -a; . ./.env; set +a

Important

.env contains your password. Restrict the permissions with chmod 600 .env.
The file is ignored by git (.gitignore).

Note	The lookups are defined in `inventory/group_vars/all/mos_login.yml`. Optionally, set `mos_username` and `mos_password` there statically instead of the environment variables. Encrypt the password with `ansible-vault` in this case.

4.5. Database passwords

The password for all database users is default_dbpass in inventory/group_vars/all/password.yml.

Warning

The default Oracle_123 is for test environments only. Change it and use ansible-vault for other environments.

5. AutoUpgrade on the VM

AutoUpgrade is executed on the VM (autoupgrade_run_local: false in inventory/group_vars/all/autoupgrade.yml). It downloads the gold image directly into /u01/sw on the VM. No installation media are copied from the Ansible controller (oracle_sw_copy: false).

The execution of AutoUpgrade on the VM requires:

the Python module pexpect for the keystore with the My Oracle Support credentials,
a JDK for autoupgrade.jar and
the download directory /u01/sw on the filesystem /u01.

The playbook os creates the filesystem /u01 (host_fs_layout in the inventory). playbooks/autoupgrade.yml installs the packages for the JDK and pexpect before the installation of AutoUpgrade. Therefore do_all.yml executes the playbook os before AutoUpgrade. The playbook os is executed a second time, because it is a fixed part of opitzconsulting.ansible_oracle.single_instance_fs. The second execution changes nothing.

Table 4. Download configuration in inventory/group_vars/all/autoupgrade.yml
Variable	Value	Description
`autoupgrade_download_latest`	`true`	Download the latest `autoupgrade.jar` from Oracle
`autoupgrade_download_patches`	`target_version: 26`, `patch: RECOMMENDED`, `gold_image: ALL`	Gold image for 26ai with all recommended patches
`autoupgrade_download_gold_image_rename`	`true`	Rename the gold image to `db_home_<release>.zip`, e.g. `db_home_26.04.zip`
`autoupgrade_download_gold_image_latest`	`true`	Symlink `db_home_26_latest.zip` to the latest gold image of 26ai

See Oracle AutoUpgrade for details.

Important

The gold image is built by Oracle on request.
When no suitable image is cached, the download can take a few hours.

The release update of the gold image is known only after the download. Therefore the inventory uses the symlink db_home_26_latest.zip as imagename instead of the real filename. The symlink points to the gold image with the highest release update in /u01/sw. It is changed only, when a newer gold image is downloaded - the download of an older release update keeps it unchanged.

Check the downloaded gold image on the VM

ls -l /u01/sw/db_home_*.zip

Example

db_home_26.04.zip
db_home_26_latest.zip -> db_home_26.04.zip

inventory/group_vars/all/db-homes.yml

  db26_si_ee: &db26_si_ee
    version: 26.1.0.0
    oracle_home: /u01/app/oracle/product/db26_si_ee
    edition: EE
    imagename: db_home_26_latest.zip

Tip	Use the real filename, e.g. `imagename: db_home_26.04.zip`, when an ORACLE_HOME must be installed with a fixed release update.

6. Install database with Ansible

Start installation

cd ~/git/ansible-oracle/example/beginner/ansible
ansible-playbook playbooks/do_all.yml

Note	The execution takes approx. 60 minutes plus the download of the gold image.

Table 5. Configuration of the database
Parameter	Value
ORACLE_BASE	`/u01/app/oracle`
ORACLE_HOME	`/u01/app/oracle/product/db26_si_ee`
ORACLE_SID	`DB1`
PDB	`ORCLPDB`
db_create_file_dest	`/u02/oradata`
db_recovery_file_dest	`/u02/fra`
Listener	`LISTENER`, port 1521

7. How to work with the installed database

ssh ol@192.168.66.161

Switch to user oracle

sudo -iu oracle

Initialize ocenv to set the environment variables

ocenv

ocenv shows the ORACLE_HOMEs, databases and listeners on the host. envhelp shows an overview of the commands.

Set ORACLE_SID

DB1

Start SQL*Plus

sql

8. Next Steps

Last modified November 1, 2026: example: New beginners Guide (5b828ccb)