HOWTO: Local Installation of Ansible-Oracle

1. Intro

This guide will show you how to get Ansible-Oracle up and running with a local installation (as opposed to a container or Vagrant setup).

It is assumed that the server is airgapped and doesn’t have Internet access and therefore it’s demonstrated how to install all necessary binaries manually.

Note
 This guide aims at developers who want to test different setups with different dependencies. To enable you to run the Ansible-Oracle environment independently of other versions of Ansible, Python and Galaxy modules, everything will be encapsulated within a Python Virtual Environment (venv). If you prefer to install everything globally, you’ll find info on how to do so below.

The steps in this guide were tested with OL9.5, Python 3.9, Ansible 2.14 and Ansible-Oracle 4.11.1.

2. What you need

2.1. Server and OS

  • Oracle Linux 9 or RHEL 9 (this guide was tested with OL 9.5)

  • OS install DVD or ISO attached to your machine.

  • At least 50 MB free space in the /home filesystem.

2.2. Mandatory RPMs

These RPMs can be installed from the OS install image (DVD ISO).

  • git

  • ansible-core

  • python3-pip

2.3. Other mandatory files

Download these files on a device with Internet access and transfer them to the target server’s /tmp directory.

2.3.1. Optional:

  • tig, for easier navigation of git repos.

3. Setup Ansible

3.1. User

dnf install -y git ansible-core python3-pip
useradd ansible

su - ansible
mkdir .ssh
cd .ssh/
vi authorized_keys
ssh-keygen -t ed25519
## No password
## Paste the contents of id_ecdsa.pub into /root/.ssh/authorized_keys on target machine

3.2. Python Virtual Environment and Ansible Collections

# As ansible user
mkdir -p /home/ansible/ansible/inventory
cd ~/ansible
unzip /tmp/ansible-oracle-4.11.1.zip
mv ansible-oracle-4.11.1 ansible-oracle
cd ansible-oracle
echo ".venv/" >> .gitignore
python3 -m venv .venv

# Activate the virtual environment
source .venv/bin/activate

Install packages in the virtual environment:

Note
 If you don’t want the dependencies within the venv, change the -p ~/ansible/ansible-oracle/.venv/lib/collections to -p ~/ansible/ansible-oracle/playbooks/collections. This is the default path for Ansible Navigator. 
ansible-galaxy collection install /tmp/ansible_collections/ansible-posix-1.5.4.tar.gz -p ~/ansible/ansible-oracle/.venv/lib/collections
ansible-galaxy collection install /tmp/ansible_collections/ansible-utils-5.1.0.tar.gz -p ~/ansible/ansible-oracle/.venv/lib/collections
ansible-galaxy collection install /tmp/ansible_collections/community-general-9.5.4.tar.gz -p ~/ansible/ansible-oracle/.venv/lib/collections
ansible-galaxy collection install /tmp/ansible_collections/community-crypto-2.24.0.tar.gz -p ~/ansible/ansible-oracle/.venv/lib/collections
ansible-galaxy collection install /tmp/ansible_collections/community-mysql-3.12.0.tar.gz -p ~/ansible/ansible-oracle/.venv/lib/collections
ansible-galaxy collection install /tmp/ansible_collections/devsec-hardening-8.8.0.tar.gz -p ~/ansible/ansible-oracle/.venv/lib/collections
ansible-galaxy collection install /tmp/ansible_collections/opitzconsulting-ansible_oracle-4.11.1.tar.gz -p ~/ansible/ansible-oracle/.venv/lib/collections
Starting galaxy collection install process
[WARNING]: The specified collections path '/home/ansible/ansible/ansible-oracle/collections' is not part of the configured Ansible collections paths
'/home/ansible/.ansible/collections:/usr/share/ansible/collections'. The installed collection will not be picked up in an Ansible run, unless within a
playbook-adjacent collections directory.

For background info on Ansible in a Python venv, see: How to set up and use Python virtual environments for Ansible

3.3. Shell Alias

This alias for Bash sets the environment and jumps to the ansible-oracle directory.

alias aov='cd ~/ansible/ansible-oracle ; source .venv/bin/activate ; export ANSIBLE_COLLECTIONS_PATHS=".venv/lib/collections:$ANSIBLE_COLLECTIONS_PATHS"'

You could also define the path to the ansible collections in ansible.cfg:

[defaults]
collections_paths = .venv/lib/collections

3.4. SSH Key

For passwordless login, the ansible user needs a SSH key. This is optional, if you run on local connections or if you prefer to provide a password.

ssh-keygen -q -t ed25519 -N '' <<< $'\ny' >/dev/null 2>&1

Copy the contents of id_ed25519.pub to the target host’s root user into ~/.ssh/authorized_keys.

4. Target Host

4.1. python-oracledb

The target (database) host needs python-oracledb installed. The modules of Ansible-Oracle use this package in thick mode (Oracle Client libraries of the ORACLE_HOME) to issue database queries. The Playbook os.yml installs this package with the role pyoracledb. The version depends on the Python version of the target host (1.4.2 for Python 3.6 on OL8, 4.0.2 for Python 3.9 on OL9). Without access to the Python package index, put the wheel files into a directory and point to it from your inventory, e.g., pyoracledb_wheel_dir: /tmp/python-packages. pip selects the wheel file matching the Python version of the target host.

Otherwise, the package must be manually installed as root.

4.1.1. Optional: install python-oracledb manually

As shown above, on the target machine:

pip install /tmp/python-packages/oracledb-*.whl

Skip the installation with the role pyoracledb in this case: pyoracledb_install: false.

5. Ready to go!

Activate the virtual environment by issuing aov. Then, run your playbooks as usual.

Last modified November 8, 2026: oracle_crs_listener: new module, replaces ibre5041.ansible_oracle_modules (b83347f9)