README.developer

Developer mode installation
===========================


PREPARATIONS
------------

PREREQUISITES

Install the following system components:

 - jdk-7 / openjdk-7-jdk / icedtea-7
 - unzip
 - openssl
 - postgresql-server postgresql
 - python-m2crypto / m2crypto
 - python-psycopg2 / psycopg
 - python-cheetah / cheetah
 - libxml2-python / libxml2[python]
 - python-daemon
 - otopi >= 1.1.0
 - ovirt-host-deploy >= 1.1.0
 - jboss-as (optional)
 - maven-3 (optional)
 - pyflakes (optional)
 - python-pep8 / pep8 (optional)
 - patternfly1 (optional)

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

>=Jboss 7.1.1 is required, download and extract it if not installed
using distribution package management.

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:

/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

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

restart postgresql service.

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"
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=$HOME/ovirt-engine 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.

BUILD

To build and install ovirt-engine at your home folder under ovirt-engine
directory, use:

$ make clean install-dev PREFIX=$HOME/ovirt-engine

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 [/usr/local]
    Installation root directory.

PATTERNFLY_DIR [/usr/share/patternfly1/resources]
    The location of the PatternFly installation.

BUILD_GWT [1]
    Build GWT.

BUILD_GWT_USERPORTAL [1]
    Build user portal if gwt is enabled.

BUILD_GWT_WEBADMIN [1]
    Build web admin if gwt is enabled.

BUILD_LOCALES [0]
    Build additional locales.

BUILD_DEV [0]
    Add extra development flags. Usually this should not be used
    directly, as the all-dev sets this.

BUILD_UT [0]
    Perform unit tests during build.

DEV_BUILD_GWT_DRAFT [0]
    Build draft gwt application without optimizations.

DEV_EXTRA_BUILD_FLAGS
    Any maven build flags requires for building.

    For example, if your machine is low on memory, use:
    DEV_EXTRA_BUILD_FLAGS="-Dgwt.compiler.localWorkers=2"

DEV_EXTRA_BUILD_FLAGS_GWT_DEFAULTS [-D gwt.userAgent=gecko1_8]
    By default, only the gecko1_8 (Mozilla Firefox) support is built,
    building all permutations is possible by specifying
    DEV_EXTRA_BUILD_FLAGS_GWT_DEFAULTS="".

    A list of all supported browsers is available at gwt.userAgent
    property within frontend/webadmin/modules/pom.xml.

DEV_REBUILD [1]
    Disable if only packaging components were modified.

SETUP

To setup the product use the following command:

$ $HOME/ovirt-engine/bin/engine-setup

If Jboss is installed not via distribution package management,
add the following parameter, provided JBOSS_HOME environment contains
the location of the Jboss installation:
   --jboss-home="${JBOSS_HOME}"

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
$HOME/ovirt-engine directory, build and setup.

The $HOME/ovirt-engine/bin/engine-cleanup is also available to cleanup
the environment, it is useful for application changes, less for packaging
changes.

ADMINISTRATION

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

To start/stop the engine service use:

$ $HOME/ovirt-engine/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

GWT DEBUG

$ make install-dev PREFIX="${HOME}/ovirt-engine"
$ make gwt-debug DEBUG_MODULE=<module>

While <module> is webadmin or userportal-gwtp.

Debug port is 8000, detailed instructions for GWT debugging are at [1].

GWT debug URLs, provided components running on same machine:
    WebAdmin    http://127.0.0.1:8080/ovirt-engine/webadmin/WebAdmin.html?gwt.codesvr=127.0.0.1:9997
    UserPortal  http://127.0.0.1:8080/ovirt-engine/userportal/UserPortal.html?gwt.codesvr=127.0.0.1:9997

[1] http://wiki.ovirt.org/DebugFrontend

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"

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 [0]
    Quick build, best for syntax checks.

ovirt_build_minimal [0]
    Build minimal Firefox only package.

ovirt_build_gwt [1]
    Build gwt components.

ovirt_build_locales [1]
    Build extra locales.

Example:

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