= Developer mode installation

== Preparations

=== Prerequisites

Install the following system components:

- jdk-8 / openjdk-8-jdk / icedtea-8
- mime-types or mailcap
- unzip
- openssl
- bind-utils
- postgresql-server >= 9.5 / rh-postgresql95-postgresql-server
- postgresql >= 9.5 / rh-postgresql95-postgresql-server
- python-dateutil / dateutil
- python-m2crypto / m2crypto
- python-psycopg2 / psycopg
- python-jinja2 / Jinja2
- libxml2-python / libxml2[python]
- python-daemon
- otopi >= 1.1.0
- ovirt-host-deploy >= 1.1.0
- ovirt-js-dependencies
- ovirt-setup-lib
- maven-3
- ansible >= 2.4
- ovirt-ansible-roles
- ovirt-engine-metrics
- python-flake8 / pyflakes (optional)
- python-pep8 / pep8 (optional)
- python-docker-py (optional)
- python2-isort (optional)

Maven-3 is required, download and extract if not installed using
distribution package management, and add to PATH.

WildFly 11 is required along with ovirt-engine-wildfly-overlay. Preferred way
is to install following packages:

- ovirt-engine-wildfly
- ovirt-engine-wildfly-overlay

Both packages can be installed from ovirt-master-snapshot-static repository:

  [ovirt-master-snapshot-static]
  name=Latest oVirt master additional nightly snapshot
  baseurl=http://resources.ovirt.org/pub/ovirt-master-snapshot-static/rpm/@DIST@$releasever/
  enabled=1
  skip_if_unavailable=1
  gpgcheck=0

Please replace `@DIST@` with `fc` for Fedora or `el` for Centos/RHEL.

OVN/OVS is an optional dependency. If you want to use it, check the requirements in the
ovirt-engine.spec.in file for a list of packages. Otherwise, you should reply 'No'
when asked about it by engine-setup.

=== System settings

Build locales requires at least 10240 file descriptors, create the
following file, replace <user> with user that is used for building,
and logout/login:

[source]
./etc/security/limits.d/10-nofile.conf
----
<user> hard nofile 10240
#<user> soft nofile 10240  # optional, to apply automatically
----

If soft limit was not set, before building, apply new limit using:

  $ ulimit -n 10240

=== PostgreSQL accessibility

Configure PostgreSQL to accept user and password:

Locate `pg_hba.conf` within your distribution, common locations are:

- `/var/lib/pgsql/data/pg_hba.conf`
- `/etc/postgresql-*/pg_hba.conf`
- `/etc/postgresql/*/main/pg_hba.conf`
- `/var/opt/rh/rh-postgresql95/lib/pgsql/data/pg_hba.conf` (el7 with rh-postgresql95)

Within `pg_hba.conf` set method to `password` for `127.0.0.1/32` and
`::1/128`.

Tune PostgreSQL configuration:
Locate `postgresql.conf` within your distribution, common locations are:

- `/var/lib/pgsql/data`
- `/etc/postgresql*`
- `/var/opt/rh/rh-postgresql95/lib/pgsql/data/postgresql.conf` (el7 with rh-postgresql95)

Within `postgresql.conf` set:

  autovacuum_vacuum_scale_factor = 0.01
  autovacuum_analyze_scale_factor = 0.075
  autovacuum_max_workers = 6
  max_connections = 150
  work_mem = 8192

Restart the PostgreSQL service (`systemctl restart rh-postgresql95-postgresql` for the SCL one).

=== Database creation

Create database for ovirt-engine, usually the following sequence should
work to create a user named `engine` that owns database named `engine`:

  # su - postgres -c "psql -d template1" # if on fedora or
  # su - postgres -c "scl enable rh-postgresql95 -- psql -d template1" # if on el7 with rh-postgresql95
  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';

== Development

=== Environment

Development environment is supported only under non-root account. Do
not run this sequence as root.

Each instance of application must be installed at different `PREFIX` and
use its own database. Throughout this document application is installed
using `PREFIX="${PREFIX}"` and engine database and user, these should be
changed if a new instance is required. Do not mix different versions of
product with same `PREFIX/database`.

From this point on, the `"${PREFIX}"` will be used to mark the prefix
in which you selected to install the development environment.

=== Build

To build and install ovirt-engine at your home folder under ovirt-engine
directory execute the following command:

  $ make clean install-dev PREFIX="${PREFIX}"

NOTE: `${PREFIX}` should be replaced with the location in which you
intend to install the environment.

NOTE: Add DEV_BUILD_SCL_POSTGRESQL=1 in order to configure your local build
for SCL rh-postgresql95.

==== Build targets

all:: Build project.
clean:: Clean project.
all-dev:: Build project for development.
install-dev:: Install a development environment at PREFIX.
dist:: Create source tarball out of git repository.
maven:: Force execution of maven.

==== Build customization

The following `Makefile` environment variables are available for build
customization:

PREFIX:: Installation root directory. Default is `/usr/local`.

JS_DEPS_DIR:: The loaction of the ovirt-js-dependencies installation.
Default is `/usr/share/ovirt-js-dependencies`.

BUILD_GWT:: Build GWT. Default is `1`.

BUILD_ALL_USER_AGENTS:: Build GWT applications for all supported
browsers. Default is `0`.

BUILD_LOCALES:: Build GWT applications for all supported locales.
default is `0`.

BUILD_DEV:: Add extra development flags. Usually this should not be
used directly, as the all-dev sets this. Default is `0`.

BUILD_UT:: Perform unit tests during build. Default is `0`.

BUILD_JAVA_OPTS_MAVEN:: Maven JVM options. Can be defined as
environment variable. Default is empty.

BUILD_JAVA_OPTS_GWT:: GWT compiler and dev mode JVM options. Can be
defined as environment variable. default is empty.

NOTE: Note that `BUILD_JAVA_OPTS_GWT` overrides `BUILD_JAVA_OPTS_MAVEN`
when building GWT applications (`BUILD_JAVA_OPTS_MAVEN` settings still
apply, unless overridden).

DEV_BUILD_GWT_DRAFT:: Build "draft" version of GWT applications without
optimizations. This is useful when profiling compiled applications in
web browser. Default value is `0`.
+
Following changes are applied for draft builds:
- Prevent code and CSS obfuscation.
- Reduce the level of code optimizations.
+
On local development environment, using GWT Super Dev Mode (see below)
is preferred, as it automatically disables all optimizations and allows
you to recompile the GWT application on the fly.

DEV_BUILD_SCL_POSTGRESQL:: Configure your local development deployment
to be used with SCL rh-postgresql95 instead of system PostgreSQL.
Default value is `0`.
+

DEV_BUILD_GWT_SUPER_DEV_MODE:: Allows debugging GWT applications via
Super Dev Mode, using web browser's JavaScript development tooling.
Default value is `0`.
+
Do a local Engine development build as you normally would. Then, start
the Super Dev Mode code server as following:

  $ make gwt-debug DEV_BUILD_GWT_SUPER_DEV_MODE=1

In your browser, open http://127.0.0.1:9876/ and save the "Dev Mode On"
bookmark. Next, visit the GWT application URL (as served from Engine)
and click "Dev Mode On". This allows you to recompile and reload the
GWT application, reflecting any changes you've made in the UI code.

DEV_EXTRA_BUILD_FLAGS:: Any maven build flags required for building.
+
For example, if your machine is low on memory, limit maximum
simultaneous GWT permutation worker threads:
+
  DEV_EXTRA_BUILD_FLAGS="-Dgwt.compiler.localWorkers=1"

DEV_EXTRA_BUILD_FLAGS_GWT_DEFAULTS:: Any maven build flags required for building GWT applications.
+
By default, GWT applications are
built for Firefox only. To build for additional browsers, provide
comma-separated list of user agents, see
`frontend/webadmin/modules/pom.xml` for full list.
+
For example, to build for Firefox and Chrome:
+
  DEV_EXTRA_BUILD_FLAGS_GWT_DEFAULTS="-Dgwt.userAgent=gecko1_8,safari"
+
To build for all supported browsers, use `BUILD_ALL_USER_AGENTS=1`.
+
For example, to build only the English and Japanese locale:
+
  DEV_EXTRA_BUILD_FLAGS_GWT_DEFAULTS="-Dgwt.locale=en_US,ja_JP"
+
To build for all supported locales, use `BUILD_LOCALES=1`.


DEV_REBUILD:: Disable if only packaging components were modified.
Default is `1`.

WILDFLY_OVERLAY_MODULES:: Change location of WildFly overlay modules.
If you want to disable WildFly overlay configuration completely, please
set to empty string. Default is
`/usr/share/ovirt-engine-wildfly-overlay/modules`.

== Setup

To setup the product use the following command:

  $ "${PREFIX}/bin/engine-setup"

== JBoss

If you want to use different WildFly/EAP installation, specify it at
`--jboss-home=` parameter of setup.

== Environment

OVIRT_ENGINE_JAVA_HOME:: Select a specific Java home.

OVIRT_ENGINE_JAVA_HOME_FORCE:: Set to non zero to bypass Java
compatibility check.

== Refresh

If there are no significant changes, such as file structure or database
schema, there is no need to run the setup again, `make install-dev
<args>` will overwrite files as required, run `engine-setup` to refresh
database schema.

Do remember to restart the engine service.

If there is a significant change, safest path is to stop service, remove
`${PREFIX}` directory, build and setup.

The `${PREFIX}/bin/engine-cleanup` tool is also available to cleanup the
environment, it is useful for application changes, less for packaging
changes.

== Service administration

Most utilities and services are operational, including PKI, host deploy.

To start/stop the engine service use:

  $ "${PREFIX}/share/ovirt-engine/services/ovirt-engine/ovirt-engine.py" start

While the service is running, this command will not exit. Press
<Ctrl>-C to stop service.

Access using HTTP or HTTPS:

- http://<server>:8080
- https://<server>:8443

Debug port is available at `127.0.0.1:8787`.

== Running instance management (JMX)

ovirt-engine service supports jmx as management interface. Actually, this is
the standard jboss jmx interface, while authentication can be done using any
engine user with SuperUser role. Access is permitted only from the local
host.

Access JMX shell using provide OPTIONAL_COMMAND for non interactive usage:

  $ "${JBOSS_HOME}/bin/jboss-cli.sh" \
    --connect \
    --timeout=30000 \
    --controller=localhost:8706 \
    --user=admin@internal \
    --commands="OPTIONAL_COMMA_SEPARATED_COMMANDS"

Useful commands:

Modify log level::
+
  /subsystem=logging/logger=org.ovirt.engine.core.bll:write-attribute(name=level,value=DEBUG)

Create a new log category::
+
  /subsystem=logging/logger=org.ovirt.engine:add

Get the engine data-source statistics::
+
  ls /subsystem=datasources/data-source=ENGINEDataSource/statistics=jdbc/

Get threading info::
+
  ls /core-service=platform-mbean/type=threading/

By default JMX access is available only to localhost, to open JMX to
world, add `${PREFIX}/etc/ovirt-engine/engine.conf.d/20-setup-jmx-debug.conf` with:

  ENGINE_JMX_INTERFACE=public

== GWT debug

  $ make install-dev PREFIX="${PREFIX}"
  $ make gwt-debug

Debug port is 8000, detailed instructions for GWT debugging are
http://wiki.ovirt.org/DebugFrontend[here].

GWT debug URL, provided components running on same machine:

http://127.0.0.1:8080/ovirt-engine/webadmin/WebAdmin.html?gwt.codesvr=127.0.0.1:9997

Note that `gwt.codesvr` parameter does not apply when using Super Dev Mode.

== DAO tests

Create empty database for DAO tests refer to <<Database creation>>.

Provided user is `engine`, password is `engine` and database is
`engine_dao_tests`.

  $ PGPASSWORD=engine \
    ./packaging/dbscripts/schema.sh \
      -c apply -u engine -d engine_dao_tests

Run build as:

  $ make maven BUILD_GWT=0 BUILD_UT=1 EXTRA_BUILD_FLAGS="-P enable-dao-tests \
    -D engine.db.username=engine \
    -D engine.db.password=engine \
    -D engine.db.url=jdbc:postgresql://localhost/engine_dao_tests"

== VM console

After the environment is setup and installed, some adjustments are required.

Copy `vmconsole-host` configuration:

  $ sudo cp -p "${PREFIX}/share/ovirt-engine/conf/ovirt-vmconsole-proxy.conf \
  /etc/ovirt-vmconsole/ovirt-vmconsole-proxy/conf.d/50-ovirt-vmconsole-proxy.conf

If selinux is enabled on your machine, set type on vmconsole helper using:

$ sudo chcon --type=bin_t "${PREFIX}/libexec/ovirt-vmconsole-proxy-helper/ovirt-vmconsole-list.py"

== RPM packaging

  $ make dist
  $ rpmbuild -ts @tarball@
  # yum-builddep @srpm@
  # rpmbuild -tb @tarball@

The following spec file variables are available for package customization:

ovirt_build_quick:: Quick build, best for syntax checks. Default is `0`.

ovirt_build_minimal:: Build minimal Firefox only package. Default is
`0`.

ovirt_build_gwt:: Build GWT components. Default is `1`.

ovirt_build_all_user_agents:: Build GWT components for all supported
browsers. Default is `1`.

ovirt_build_locales:: Build GWT components for all supported locales.
Default is `1`.

Example:

  # rpmbuild -D"ovirt_build_minimal 1" -tb @tarball@
