This post is also available in:
Português (Portuguese (Brazil))
If you need an Oracle Database up and running fast — to test a patch, reproduce an issue, or validate a query — building the infrastructure from scratch every time is a waste. Oracle’s official GitHub repository provides ready-to-use Vagrant boxes for all major versions, including 19c.
In this guide, you’ll spin up a full Oracle Database 19.3.0 inside an isolated VM, with the database initialized and ready for connections, using only Vagrant and VirtualBox.
Prerequisites
Make sure you have the following before starting:
| Requirement | Min. Version | Notes |
|---|---|---|
| VirtualBox | 6.1+ | Must be installed before Vagrant |
| Vagrant | 2.3+ | |
| Git | any | To clone the repository |
| Oracle 19c Binary | LINUX.X64_193000_db_home.zip | Download from Oracle eDelivery |
| Free disk space | ~35 GB | VM + database + binary |
| Available RAM | 4 GB | The VM uses 2 GB by default |
⚠️ VirtualBox must be installed before Vagrant. Installing them in reverse order causes provider detection issues.
Step 1 — Download the Oracle 19c Binary
Vagrant does not download Oracle binaries automatically — you need to obtain them manually from Oracle eDelivery or OTN.
- Go to edelivery.oracle.com
- Sign in with your Oracle account (free registration)
- Search for Oracle Database 19c — select the Linux x86-64 version
- Download the file:
LINUX.X64_193000_db_home.zip
Keep the file accessible — you’ll copy it into the correct directory in the next step.
Step 2 — Clone the Official Repository
git clone https://github.com/oracle/vagrant-projects.git
cd vagrant-projects/OracleDatabase/19.3.0Expected directory structure:
19.3.0/
├── Vagrantfile
├── install.sh
├── ora19c.conf
└── scripts/Step 3 — Place and Validate the Binary
Copy the Oracle ZIP into the 19.3.0 directory:
cp /path/to/LINUX.X64_193000_db_home.zip .Confirm it’s in the right place:
ls -lh *.zip-rwxrwxr-x 1 henrique henrique 2.9G Apr 30 11:26 LINUX.X64_193000_db_home.zip⚠️ The filename matters. The
Vagrantfilereferences the exact nameLINUX.X64_193000_db_home.zip. Do not rename the file.
Validate the SHA-256 before proceeding
The provision script validates the ZIP checksum before installing. A corrupted download will fail mid-provision — and you’ll only find out after waiting 10+ minutes.
Validate upfront:
cat db_installer.sha256ba8329c757133da313ed3b6d7f86c5ac42cd9970a28bf2e6233f3235233aa8d8 */vagrant/LINUX.X64_193000_db_home.zipsha256sum LINUX.X64_193000_db_home.zipba8329c757133da313ed3b6d7f86c5ac42cd9970a28bf2e6233f3235233aa8d8 LINUX.X64_193000_db_home.zipBoth hashes must be identical. If they differ, the file is corrupted — download it again before continuing.
Step 4 — Bring Up the VM
vagrant upThe full process takes 15 to 30 minutes depending on your hardware. Vagrant will:
- Download the Oracle Linux 7 base box (first run only, ~1 GB)
- Create and start the VM in VirtualBox
- Run the Oracle Database installation script
- Initialize the database
At the end of provisioning, you’ll see the database creation progress and the generated password:
oracle-19c-vagrant: INSTALLER: Oracle software installed
oracle-19c-vagrant: INSTALLER: Listener created
oracle-19c-vagrant: Prepare for db operation
oracle-19c-vagrant: 8% complete
oracle-19c-vagrant: Copying database files
oracle-19c-vagrant: 31% complete
oracle-19c-vagrant: Creating and starting Oracle instance
oracle-19c-vagrant: 32% complete
oracle-19c-vagrant: 46% complete
oracle-19c-vagrant: Completing Database Creation
oracle-19c-vagrant: 51% complete
oracle-19c-vagrant: Creating Pluggable Databases
oracle-19c-vagrant: 58% complete
oracle-19c-vagrant: 77% complete
oracle-19c-vagrant: Executing Post Configuration Actions
oracle-19c-vagrant: 100% complete
oracle-19c-vagrant: Database creation complete.
oracle-19c-vagrant: Global Database Name:ORCLCDB
oracle-19c-vagrant: System Identifier(SID):ORCLCDB
oracle-19c-vagrant: INSTALLER: Database created
oracle-19c-vagrant: INSTALLER: Oratab configured
oracle-19c-vagrant: INSTALLER: Created and enabled oracle-rdbms systemd's service
oracle-19c-vagrant: ORACLE PASSWORD FOR SYS, SYSTEM AND PDBADMIN: <generated password>
oracle-19c-vagrant: INSTALLER: Installation complete, database ready to use!💡 The password for SYS, SYSTEM, and PDBADMIN is auto-generated and printed on the second-to-last line. Copy it before closing the terminal — it is not saved to any easily accessible file.
Step 5 — SSH into the VM
vagrant sshOnce inside, switch to the oracle user:
sudo su - oracleStep 6 — Validate the Database
Connect to the CDB
sqlplus / as sysdbaSELECT name, db_unique_name, open_mode FROM v$database;NAME DB_UNIQUE_NAME OPEN_MODE
--------- ------------------------------ --------------------
ORCLCDB ORCLCDB READ WRITECheck the PDB
SHOW PDBS;CON_ID CON_NAME OPEN MODE RESTRICTED
------ ------------------------------ ---------- ----------
2 PDB$SEED READ ONLY NO
3 ORCLPDB1 READ WRITE NOOpen the PDB if needed
ALTER PLUGGABLE DATABASE ORCLPDB1 OPEN;
ALTER SESSION SET CONTAINER = ORCLPDB1;Step 7 — External Connection from the Host
The box comes pre-configured with port forwarding — ports 1521 and 5500 from the VM are mapped directly to the host.
Via SQLPlus
Validated with Oracle 23c client on the host:
sqlplus sys/<password>@localhost:1521/orclpdb1 as sysdba⚠️ Oracle client 19c or later requires
DISABLE_OOB=ONto connect via VirtualBox NAT. Without it, the connection fails with ORA-12637. Add it to the client’ssqlnet.oraon the host — see the Known Errors section for the full procedure.
Connection Parameters
| Parameter | Value |
|---|---|
| Host | localhost |
| Port | 1521 |
| Service Name | ORCLCDB (CDB) or orclpdb1 (PDB) |
| Username | sys |
| Role | SYSDBA |
| Password | (password generated during vagrant up) |
Essential Vagrant Commands
| Command | What it does |
|---|---|
vagrant up | Creates and starts the VM |
vagrant ssh | Opens an SSH session into the VM |
vagrant halt | Gracefully shuts down the VM |
vagrant suspend | Suspends the VM (saves state to disk) |
vagrant resume | Resumes from a suspended state |
vagrant reload | Restarts and reloads the Vagrantfile |
vagrant destroy | Removes the VM and frees disk space |
vagrant status | Shows the current state of the VM |
💡 Use
vagrant suspend/vagrant resumeto preserve the database state between sessions without waiting for the full startup again.
Known Errors
VBoxManage: command not found
VirtualBox is not installed or not in your PATH. Install VirtualBox before running vagrant up.
Vagrant provider "virtualbox" is not usable
This happens when the VirtualBox kernel module isn’t loaded. Fix:
sudo modprobe vboxdrvIf the module doesn’t exist, reinstall VirtualBox along with the appropriate kernel headers and extension packages for your distribution.
Timed out while waiting for the machine to boot
The VM started but Vagrant couldn’t establish the SSH connection within the timeout. Common causes:
- Virtualization not enabled in BIOS/UEFI — verify that VT-x or AMD-V is enabled
- Insufficient RAM — the VM requires at least 2 GB of available memory on the host
ORA-12637: Packet receive failed when connecting from the host
Oracle Net 19c+ attempts to automatically detect Out Of Band (OOB) break support. Some network stacks — including VirtualBox NAT — do not handle this correctly, causing the connection to silently fail.
This error appears when connecting via SQLPlus or SQL Developer from the host using an Oracle 19c or later client.
Fix: disable OOB in the client’s sqlnet.ora on the host:
echo "DISABLE_OOB=ON" >> ~/.sqlnet.oraFor SQL Developer, also add it to the sqlnet.ora of the Oracle Home it references:
echo "DISABLE_OOB=ON" >> $ORACLE_HOME/network/admin/sqlnet.oraThe parameter is read on every new connection — no restart needed.
💡 This is Oracle’s documented solution for Docker and Vagrant environments with 19c+ clients. Reference: oracle/docker-images FAQ
This is the most common failure in this flow. The provision script validates the binary’s SHA-256 before installing — if the download was interrupted or corrupted, provision fails with:
oracle-19c-vagrant: /vagrant/LINUX.X64_193000_db_home.zip: FAILED
oracle-19c-vagrant: sha256sum: WARNING: 1 computed checksum did NOT match
oracle-19c-vagrant: INSTALLER: Database installer file missing or invalid.Diagnose it:
sha256sum LINUX.X64_193000_db_home.zip
cat db_installer.sha256If the hashes differ, the file is corrupted. Download it again from Oracle eDelivery, validate the hash, then destroy the VM before retrying:
vagrant destroy
vagrant up⚠️ Do not use
vagrant reload --provisionin this case. The provision failed before creating the oracle user and database structure — the VM is in a broken state and must be recreated from scratch.
References
- oracle/vagrant-projects — GitHub
- Oracle Database 19c Documentation
- Oracle eDelivery
- VirtualBox Downloads
- Vagrant Documentation