ovirt-engine: the virtualization manager behind oVirt, and how to build it

The management server half of the oVirt project

The oVirt Engine is the virtualization manager of the oVirt project, and this repository holds its source. The primary language is Java, the default branch is master, and the repository is organised the way a long lived enterprise product usually is: a `backend/` directory for the Java server, a `frontend/` directory for the web client, `ear/` for the packaged application archive, `packaging/` and `build/` for the RPM and build machinery, and a `config/` directory.

The README is short on description and long on instructions, and that shape is the main thing to understand before reading further. It is a contributor document. There is a section on submitting patches, a section on reporting bugs and documentation issues through GitHub issues, a pointer to the oVirt users forum and mailing list, and then the bulk of the text is a developer mode installation guide.

The scope question matters here. The Engine is the management side of oVirt: the place where a cluster, its storage, its network and its virtual machines are defined. The repository does not describe itself as a complete virtualization stack, and the packaging directory, the RPM spec file and the prerequisite list below all point at a component that expects other oVirt packages, host agents and hosts to be present.

For a reader, the practical question is therefore whether they want to build and run the management server itself, which is what this repository supports, or deploy the oVirt product, which is a different exercise handled by the packaging and documentation sites.

The last push to the repository was on 2026-10-20, and the repository is not archived.

The prerequisite list is the real specification of the project

The developer mode section opens with a dependency list, and it is long enough to be the most informative part of the README. It is worth reading as a description of what the Engine is built from and what it expects from the host.

The Java side requires `java-11-openjdk-devel`, and the note on Java versions is explicit: the project is built and run using Java 11, and 4.3 branches and earlier are excluded. The build tooling is `maven >= 3.5`.

The Python and tooling side is where the modern oVirt stack shows through. The list includes `python3-otopi >= 1.10.0` and `python3-ovirt-setup-lib`, which are the setup tooling the installer uses, and `ansible-core >= 2.12.0` with `ansible-runner >= 2.1.3` and `ovirt-ansible-roles >= 1.2.0`. The README explains the ansible part: since oVirt 4.5 the engine is integrated with ansible-core and ansible-runner, so the RPM packages for both have to be installed, but no additional configuration is required.

A cluster of optional entries follows, each marked optional in the list: `ovirt-engine-metrics`, `ovirt-provider-ovn`, and `python3-ovirt-engine-sdk4`, plus the linting tools `ansible-lint`, `pyflakes`, `pycodestyle` and `isort`.

The database requirement is stated separately and just as firmly: `postgresql-server >= 12.0`, `postgresql >= 12.0` and `postgresql-contrib >= 12.0`. A virtualization manager of this kind keeps its state in a relational database, and the rest of the README is largely about getting that database into a state the Engine can use.

Java 11 and WildFly 15: the version constraints a contributor has to satisfy

The engine runs on WildFly, and the README is specific about it. WildFly 15 is required along with `ovirt-engine-wildfly-overlay`, and the preferred installation is the two packages `ovirt-engine-wildfly` and `ovirt-engine-wildfly-overlay`.

The Java setup is given as a worked example using the `alternatives` command, which is how a machine with several JDKs installed selects the default.

$ sudo alternatives --config java

The listing in the README shows four alternatives on a typical development host, including a JDK 9, a JDK 11 and a JDK 8, with the selection currently on the Java 8 entry, and the instruction is to type the selection number for the Java 11 alternative. The same is then done for `javac`.

If Maven is not already running on Java 11, the fix is an exported `JAVA_HOME`.

$ export JAVA_HOME=/lib/jvm/java-11

There is a second constraint in the same area that is easy to miss. Building locales requires at least 10240 file descriptors, so the README asks for a limits file to be created with the build user substituted in, and for a logout and login afterwards. If the soft limit was not set, the limit can be applied for the current session before building.

  $ ulimit -n 10240

That is the kind of detail that only appears in a document written by people who hit the failure, and it is the clearest signal that the README is a working setup rather than a marketing page.

PostgreSQL: initdb, pg_hba.conf and the engine database

The database section is the longest part of the developer mode guide, and it walks through the steps in order.

First the cluster is initialised and enabled.

  $ sudo postgresql-setup --initdb --unit postgresql

Then the authentication method is set in `pg_hba.conf`, whose location depends on the distribution, with three common paths listed. The method becomes `password` for the local IPv4 and IPv6 addresses, and the README explains the alternative, which is to widen those entries so PostgreSQL is reachable from outside the machine. The same applies to `postgresql.conf`, where a set of values has to be present.

  max_connections = 150
  work_mem = 8MB
  autovacuum_max_workers = 6
  autovacuum_vacuum_scale_factor = 0.01
  autovacuum_analyze_scale_factor = 0.075
  maintenance_work_mem = 64MB

Then the database itself is created, and the README gives the exact sequence, which creates a user named `engine` owning a database named `engine`.

  # su - postgres -c "psql -d template1"
  template1=# create user engine password 'engine';
  template1=# drop database engine;
  template1=# create database engine owner engine template template0
  encoding 'UTF8' lc_collate 'en_US.UTF-8' lc_ctype 'en_US.UTF-8';
  template1=# \q

The last step enables the `uuid-ossp` extension in the new database, which the Engine uses for identifier generation, and then the service is enabled and started.

The template database and the locale are chosen deliberately, and the README notes the `drop database engine` step in the middle of the sequence, which is there to make the create step repeatable rather than an accident.

For a developer this is the longest part of the setup, and it is the part most worth automating in a CI image.

The docker-compose development environment and its port map

A container based path exists, and the compose file at the top of the repository is the clearest statement of how the development environment is wired.

The database service publishes the PostgreSQL port and mounts a configuration file and an init script from the `.automation/` directory, with the password set in the environment.

services:
  postgres:
    ports:
      - "5432:5432"
    volumes:
      - ./.automation/ovirt-postgres.conf:/etc/postgresql/postgresql.conf
      - ./.automation/init-db.sh:/docker-entrypoint-initdb.d/init-db.sh
    environment:
      POSTGRES_PASSWORD: "ovirt"
    command:
      - "postgres"
      - "-c"
      - "config_file=/etc/postgresql/postgresql.conf"

The engine service is built from the repository `Dockerfile` and depends on the database, and the published ports are listed with comments that name each one.

    ports:
      - "8080:8080"
      - "8443:8443"
      - "8787:8787"
      - "54323:54323"
      - "9696:9696"
      - "6642:6642"
      - "35357:35357"
      - "2222:2222"
      - "6100:6100"
      - "7410:7410"

The same set appears in the Dockerfile, where the exposed ports are declared, and in the README's firewall guidance, which opens 8080 for HTTP, 8443 for HTTPS, 8787 for the Java debug port and 54323 for the imageio proxy, then reloads the firewall. The comments in the compose file identify the rest: an external network provider port for OVN, the OVN database, an OVN OpenStack identity API port, VDSM SSH, noVNC and Kdump.

The `ulimits` block in the compose file sets a nofile limit of 2048, with a comment explaining that the ulimit is needed because of a python-daemon issue, and the container command handles the ownership of the mounted PKI folder, which has to belong to the build user for the make script to work. These are the small frictions of running a Java application that expects root owned PKI files inside a container, and the compose file is the accumulated answer to them.

The Makefile switches that decide what gets built

The Makefile is where the build options live, and the first block of variables is a legible summary of what a build can include.

BUILD_GWT=1
BUILD_ALL_USER_AGENTS=0
BUILD_LOCALES=0
BUILD_DEV=0
BUILD_UT=1
SKIP_CHECKS=0
EXTRA_BUILD_FLAGS=
BUILD_VALIDATION=1
BUILD_ENV_VALIDATION=1
BUILD_JAVA_OPTS_MAVEN?=
BUILD_JAVA_OPTS_GWT?=
DEV_REBUILD=1
DEV_BUILD_GWT_DRAFT=0
DEV_BUILD_GWT_SUPER_DEV_MODE=1

The GWT build is the interesting one. It is the compile step for the web client, and it is by far the slowest part of an oVirt engine build, which is why the file has a `BUILD_GWT` switch and a separate set of development time GWT flags including a draft mode and a super dev mode. Turning it off is the standard way to shorten a rebuild loop when you are working on the backend.

Other switches control unit tests, which are on by default, the validation steps, and the skipping of checks entirely. The `DEV_REBUILD` flag sits alongside the GWT development flags, which suggests the default development target rebuilds rather than reuses artifacts.

The rest of the Makefile lays out the installation layout, with variables for the package name, the prefix, and the directories that hold the binaries, configuration, PKI material, documentation, the application archive, the JBoss modules, logs, backups and state. The application archive path is defined as `engine.ear` under the data root, which is the deployment unit the packaging produces.

The Dockerfile mirrors the same workflow at the container level. It starts from a build container image, installs the linting tools, copies the working directory, runs `make ovirt-engine.spec` to generate the spec, installs the build dependencies from that spec, installs the runtime dependencies, and then checks that the `en_US.UTF-8` locale resolves, with a comment saying this fails the build early so a broken locale cannot silently break deployment later.

Release cadence, licensing and what this repository does not include

The release history shows a 4.5 line that is still receiving point releases. Version 4.5.7 was published on 2025-12-17, with 4.5.3.11 from 2024-05-14 and 4.5.6 from 2024-02-12 also listed.

The last push was on 2026-10-20, so the source is being changed even though the tagged releases are on the 4.5 branch. The README's own constraint about Java 11 and the exclusion of 4.3 branches and earlier shows where the supported range sits.

On licensing, the repository carries a file named `ASL2` alongside a `LICENSE` and a `NOTICE` file, and the licence field is reported as a custom licence that GitHub cannot classify. A source header in the Makefile states `SPDX-License-Identifier: Apache-2.0` for the oVirt authors, which is the usual form for the Apache License 2.0, but because the metadata and the file headers do not agree on their face, the authoritative terms are in the `LICENSE` file itself. That is not legal advice, it is a pointer to the right file to read before redistribution.

The last limitation is the scope one. This repository builds the management server. It is not a hosted virtualization platform, it is not a hypervisor, and it is not a self contained product you can install and forget. The prerequisite list mentions `ovirt-imageio-daemon`, `ovirt-engine-metrics` and `ovirt-provider-ovn` as separate packages, and the setup steps in the README stop at a working engine on a developer machine, with the rest of the oVirt stack, hosts, storage domains and the rest of the life cycle, handled elsewhere.

The right way to treat this repository is therefore as the control plane of a stack you already intend to run, and the developer mode instructions as the price of entry for working on it directly.

Editorial conclusion

ovirt-engine is worth engaging with if you intend to contribute to the oVirt management server or to automate a build of it in CI, because the developer mode instructions are unusually complete about the PostgreSQL, Java and WildFly setup. It is not the place to start if you want to run oVirt, since the packaged product includes host agents and the rest of the stack, and it is not a good base for a new virtualization platform in 2026, given that the documented release line is 4.5. Verify first which oVirt version your target hosts expect, then confirm the Java 11 and PostgreSQL 12 requirements on your build machine before you try to assemble the environment from the README.

Frequently asked questions

Official sources

1. Issues
2. oVirt/ovirt-engine on GitHub
3. README
4. Releases