pombredanne / pnc

System for managing, executing, and tracking builds

Project-ncl

A system for managing, executing, and tracking builds

Building

Requirements:

• JDK 8
• Maven 3.2

The default build is executed by running mvn clean install.

Integration tests using application server

By default the integration tests which require application server are disabled.

Integration tests requiring JEE application server (Wildfly 9 or EAP 6.4) are placed in module "integration-test". To run integration tests use profile -Pcontainer-tests (eg. mvn clean install -Pcontainer-tests).

Remote tests require enabling additional Maven profile -Premote-tests.

To run integration test you have to specify install phase by default.

To use phase verify append property -DuseTargetBuilds (no value required) to use artifacts generated during package phase in target folder.

Installing application server for integration tests

Application server is installed by default to folder target in project top level folder. During installation additional modules required to run integration tests are installed into the server.

You must specify url to downloase server zip file -Deap6.zip.url. To specify local file use -Deap6.zip.url=file://LOCAL_ZIP_PATH, for example:

-Deap6.zip.url=file:///home/development/artifacts/JBEAP-6.4.5.GA/jboss-eap-6.4.5.GA.zip)

Installation of application server to specific folder

To run only installation of application server to specific folder use -Dtest.server.unpack.dir=. For example to install server to /tmp folder:

mvn clean verify -Pcontainer-tests -Deap6.zip.url=SERVER_ZIP_URL -pl :test-common,:test-arquillian-container -Dtest.server.unpack.dir=/tmp

Running integration tests using preinstalled and running application server

1. Install application server (see Installation of application server to specific folder)

2. start the server

   sh /tmp/jboss-eap-6.4/bin/standalone.sh

3. run integration tests with additional system properties and excluded module test-arquillian-container

   -Darq.container.wf.configuration.jbossHome=/tmp/jboss-eap-6.4 -Darq.container.wf.configuration.allowConnectingToRunningServer=true -pl !:test-arquillian-container

   mvn clean verify -Pcontainer-tests -pl !:test-arquillian-container -Deap6.zip.url= -DuseTargetBuilds -Darq.container.wf.configuration.jbossHome=/tmp/jboss-eap-6.4 -Darq.container.wf.configuration.allowConnectingToRunningServer=true

Running integration tests in Intellij IDEA

1. Install application server (see Installation of application server to specific folder)

2. start the server

   sh /tmp/jboss-eap-6.4/bin/standalone.sh

3. Create new Run/Debug configuration of type Arquillian JUnit

• setup arquillian container - Click button Configure in Arquillian Container tab, add 'Manual container configuration', add 'Maven dependency' in dependencies, type in text field org.jboss.as:jboss-as-arquillian-container-managed:7.2.0.Final

• select test class or package or module in Configuration tab

• specify path to application server and allow to connect to running server in VM options:

  -Darq.container.wf.configuration.jbossHome=/tmp/jboss-eap-6.4 -Darq.container.wf.configuration.allowConnectingToRunningServer=true

• optionally append following properties (no value required) to VM options: -DcreateArchiveCopy - to write ear deployed by arquillian to project folder (eg. for content inspection) -DuseTargetBuilds - to use artifact generated by package phase in target folder

Property useTargetBuilds can be used together with configuration 'Run maven goal' mvn package -DskipTests=true in 'before lunch' tab to deploy code changes without actual need to run mvn clean install

Configuration

All configurations are centralized in configuration file moduleconfig/src/main/resources/pnc-config.json.

Configuration file is filled with env variables, you can set required variables instead of editing the file itself. See the config file for list of available env variables.*

If you want to use a different (external) config file location you can define a path to it with -Dpnc-config-file=/path/to/pnc-config.json.

For the configuration descriptions see api doc of classes in moduleconfig/src/main/java/org/jboss/pnc/common/json/moduleconfig

Building for Production (Postgresql DB)

A Maven profile called production is provided to configure the appropriate settings to build a deployment file which is compatible with the postgresql database.

mvn install -Pproduction

TODO: this is not working currently, integration tests are always run against HSQLDB The container tests can also be run against postgresql by activating the container-tests profile, and the production profile.

mvn install -Pproduction,container-tests

##Authentication: This project comes with possibility to be secured. Security is delivered via Keycloak project http://keycloak.jboss.org/. To be able to turn on whole project on secure side you need 2 parts to fulfill.

1. Have running and configured Keycloak server instance.
   
2. Build & configure security for your PNC installation.

###Authentication - prepare Keycloak server
PRE-REQUIREMENTS:

Install your Keycloak server standalone or in Openshift according to

• http://keycloak.github.io/docs/userguide/html/server-installation.html.
• http://keycloak.github.io/docs/userguide/html/openshift.html

Configure Keycloak server

1. Create your realm By default the Keycloak server comes with "master realm", which is for demo purpose, so please create your own realm.

2. Put your Direct Grant API on at https://``/auth/admin/master/console/#/realms/``/login-settings
3. Add/Create your users via https://``/auth/admin/master/console/#/realms/``/users
4. Define roles and assign users to it via https://``/auth/admin/master/console/#/realms/``/roles
5. Create 3 client app's at https://``/auth/admin/master/console/#/realms/``/clients
6. First client app for pncweb UI with: * Client Protocol = openid-connect * Access Type = confidental * Valid Redirect URIs = http://localhost:8080/pnc-web/* (Please add URI's for different host's as you need for your installed pnc Web UI's) * Go to "Installation" tab and select "Keycloak JSON" format and copy&paste or download the installation. 7. Second client app for pncrest with: * Client Protocol = openid-connect * Access Type = confidental * Valid Redirect URIs = http://localhost:8080/pnc-rest/* (Please add as much URI's as you need for your installed pnc rest's) * Go to "Installation" tab and select "Keycloak JSON" format and copy&paste or download the installation. 8. Third client app for pncdirect with: * Client Protocol = openid-connect * Direct Grants Only = ON * Access Type = public * Go to "Installation" tab and select "Keycloak JSON" format and copy&paste or download the installation.

HINTS

1. pncrest keycloak.json additional props -> use these below for skipping ssl & defining rest for accepting only access_token for authentication/authorization.

• "ssl-required": "none",
• "bearer-only" : true,

2. pncweb keycloak.json additional props -> look at http://keycloak.github.io/docs/userguide/html/ch08.html#adapter-config to find more about adapter's config.

• "ssl-required" : "none",
• "use-resource-role-mappings" : false,
• "enable-basic-auth" : false,
• "enable-cors" : true,
• "cors-max-age" : 1000,
• "cors-allowed-methods" : "POST,PUT,DELETE,GET",
• "bearer-only" : false,

###Authentication - build & configure your PNC
By default PNC project comes with no security at all, it is up to you to turn it on. In case you want to enable authentication use -Pauth together with your build command. Enabling authentication means following

1. Your backend REST endpoints will become secured

• inside rest.war under folder WEB-INF are added files from rest/src/main/auth
• keycloak.json file is configuration file managing connection to Keycloak server
• web.xml file where you define security-constraints & security-roles, which specifies users authrorization's to each REST endpoint

2. Your pnc web UI gain the SSO ability and authentication via Keycloak login page.

• with your first unauthenticated session you will be redirected from pnc web UI into Keycloak login page.
• you will be asked to provide your credentials.
• after successful log-in you will be redirected back to pnc web UI.

3. Configure your JEE server (EAP) for keycloak

• Use -Dauth.eap.home=<path to your EAP installation> with you build command, if you want EAP configure for Keycloak. According the http://docs.jboss.org/keycloak/docs/1.1.0.Final/userguide/html/ch08.html#jboss-adapter-installation installation will be performed on server for the given path.

Using an alternate JBoss server location

By default, the Maven build will download JBoss EAP and extract it to a local directory such as target/jboss-eap-6.4. However, you can also configure and run tests in an alternate JBoss EAP location. The first step is to install the necessary HSQL and Postgresql JDBC drivers and datasources.

$ cd test-arquillian-container
$ mvn clean install -Pconfigure-test-container -Dtest.server.build.dir=/path/to/eap/server

The container-tests can be run against this JBoss server using similar command line options.

$ mvn clean install -Pcontainer-tests -Dtest.server.build.dir=/path/to/eap/server

Manually Configuring the Datasource for HSQL DB

You will need to download the hsqldb jar file and copy the jar file into the standalone/deployments directory of your JBoss server. Check the server log to see that the driver deployed successfully.

From the EAP/Wildfly admin console, select Configuration-->Connector-->Datasources. Click the "Add" button to add a new datasource and set the required fields.

Name: NewcastleTestDS
JNDI Name: java:jboss/datasources/NewcastleTestDS
JDBC Driver: hsqldb-2.3.3.jar
Connection URL: jdbc:hsqldb:mem:newcastletestmemdb

You can test the connection before saving the datasource settings. Finally, enable the datasource, and it is ready to be used by the newcastle application.

Installing Postgres for Development

Basic installation instructions for Postgres on recent versions of Fedora can be found on the Fedora wiki: https://fedoraproject.org/wiki/PostgreSQL

(Optional) In addition to the postgresql server, it's useful to install the gui admin tool pgadmin3 (yum install pgadmin3).

Once postgresql is installed and started, you can create and modify the databases using the psql command.

Connect to postgres

$ psql -h localhost newcastle -U <ROOT_USERNAME>

Create the user "newcastle Create user

postgres=# CREATE USER newcastle WITH PASSWORD newcastle;

Create the newcastle database Create newcastle database

postgres=# CREATE DATABASE newcastle OWNER newcastle;

Once the database is created, the schema can be built using the SQL files included with the newcastle source code, or it can be created automatically if it doesn't exist.

Configuring the Datasource

You will need to download and install the PostgreSQL JDBC driver into Wildfly (https://jdbc.postgresql.org/download.html). Copy the postgresql jdbc driver jar into the standalone/deployments directory of your JBoss server. Check the server log to see whether the driver deployed successfully.

From the EAP/Wildfly admin console, select Configuration-->Connector-->Datasources. Click the "Add" button to add a new datasource and set the required fields.

Name: NewcastleDS
JNDI Name: java:jboss/datasources/NewcastleDS
JDBC Driver: postgresql-9.3.jar
Connection URL: jdbc:postgresql://localhost:5432/newcastle
Username: newcastle
Password: newcastle

You can test the connection before saving the datasource settings.

UI Module Compilation Errors

Due to the need to integrate a modern frontend workflow into a maven project there can occasionally be some complications in a build. Some data is cached by the UI that is not completely cleaned by running maven clean. In case of strange build failures with the UI module please try running: maven clean -Dfrontend.clean.force and this will completely clean out all data. NOTE: with this profile enabled build times will increase by a few minutes as the ui build system will have to retrieve a large amount of previously cached data.