Installation and Dev

Overview

Edit this section Report an issue

This guide helps you get started with Meveo. It covers server configuration and use of the default database. Advanced deployment options are not covered. For a deeper description of features or configuration options, consult the other reference guides.

Prerequisites

Edit this section Report an issue

The following binaries must be installed in your local environment:

Software

Version

Download Link

Java

8

https://developers.redhat.com/products/openjdk/download

Git

latest

https://git-scm.com/downloads

Maven

latest

https://maven.apache.org/download.cgi

PostgreSQL

9.5

https://www.postgresql.org/download/

PGAdmin

4

https://www.pgadmin.org/download/

PostgreSQL Driver

42.2.4

https://jdbc.postgresql.org/download.html

Keycloak

>5

https://www.keycloak.org/downloads.html

Keycloak Adapter

>5

https://www.keycloak.org/downloads.html

Wildfly

15.0.0.Final

https://wildfly.org/downloads/

Eclipse

JEE-latest

https://www.eclipse.org/downloads/packages/

Installation Guide

This guide is intended for Windows users. Minor changes to the instructions must be done to become applicable to other operating systems.

Java

  1. Install or extract the OpenJDK in your PC.

  2. Set the environment variable JAVA_HOME, make sure it points to where you installed the OpenJDK. In Windows explorer, right click on This PC / Properties / Advance system settings / Environment variables / New. Refer to this guide.

  3. Add %JAVA_HOME%\bin in the Windows Path environment variable. Refer to this guide.

  4. Open a Windows command prompt and type "java -version", hit enter. The Java version installed on your system should be shown.

Git

  1. Download and install Git.

Maven

  1. Download and extract the maven archive into your PC.

  2. Add the M2_HOME with value pointing to where you extract maven to your Windows environment variable. See what we did in Java above. Add the %M2_HOME%\bin folder to your Windows environment path just as we did with Java above.

  3. Open a Windows command prompt and type "mvn -version", hit enter. Just like Java it should give us the version of maven installed.

PostgreSQL

  1. Download and install PostgreSQL. Take note of the admin password as we will use it later.

PGAdmin

  1. Download and install PGAdmin.

  2. Open PGAdmin, it might ask you for a master password. Enter a password and make sure to remember it.

  3. In the left panel, expand Servers / PostgreSQL 9.5.

  4. Right click Login/Group Roles and select Create / Login/Group Role.

  5. Under General tab set Name=meveo.

  6. Under Description tab set Password=meveo.

  7. Under Privileges tab toggle Can login and Superuser.

  8. Hit Save.

  9. Back in the left panel, right click on Databases and select Create / Database.

  10. Under database tab set Database=meveo, Owner=meveo.

  11. Hit Save.

Wildfly and Keycloak Installation

Option 1 - Installing as Standalone Serversw.

Edit this section Report an issue
Keycloak

  1. Download and extract Keycloak to your PC. Let’s call the folder where you extracted the files KEYCLOAK_HOME.

  2. Open the file KEYCLOAK_HOME/standalone/configuration/standalone.xml.

  3. Find this line <socket-binding-group name="standard-sockets" default-interface="public" port-offset="${jboss.socket.binding.port-offset:0}"> and replace the port-offset:0 with port-offset:1. This means 1 will be added to all default ports. Making the oauth url available at port 8081.

  4. To start the server run KEYCLOAK_HOME\bin\standalone.exe.

  5. Try accessing http://localhost:8081 from your web browser.

  6. Create an initial admin user by entering a username and password and proceed to login. You should be able to arrive at the Keycloak admin interface.

  7. In the left panel, hover on Master and click Add Realm.

  8. In the right panel, click Select a file and choose meveo-realm.json file. Meveo Realm

  9. Click create. The Meveo realm should be created and it should now be the selected realm.

  10. Back in the left panel, click Import / Select a file and select meveo-users-0.json file. Meveo Users

  11. Hit import.

To check if meveo realm is correctly configured:

  • Click the Users menu and you should see 9 users.

  • Click the Clients menu and you should see meveo-web.

In the eclipse section, we will discuss how we can integrate Keycloak so we can start it from there.

Wildfly

  1. Download the PostgreSQL driver.

  2. Download and extract Wildfly into your PC. Let’s call the folder where you extracted the files WILDFLY_HOME.

  3. Inside WILDFLY_HOME/modules folder create this folder hierarchy org/postgresql/main.

  4. Navigate to this folder.

  5. Copy and paste the PostgreSQL driver (postgresql-42.2.4.jar) here.

  6. Create a new file module.xml with the content below.

<?xml version='1.0' encoding='UTF-8'?>
<module xmlns="urn:jboss:module:1.1" name="org.postgresql">
    <resources>
        <resource-root path="postgresql-42.2.4.jar"/>
    </resources>

    <dependencies>
        <module name="javax.api"/>
        <module name="javax.transaction.api"/>
    </dependencies>
</module>
Add the Keycloak Adapter to Wildfly

  1. Download the Keycloak Adapter with the same version as the downloaded Keycloak Server.

  2. Copy the downloaded file into WILDFLY_HOME and extract.

  3. Run command prompt and navigate to WILDFLY_HOME\bin folder.

  4. Open WILDFLY_HOME\bin\adapter-install-offline.cli and change the standalone to standalone-full.

  5. Execute: jboss-cli.bat --file=adapter-install-offline.cli.

  6. A success message should be shown.

Add System Properties

At the end of extensions tag add the following properties.

<system-properties>
    <property name="jboss.as.management.blocking.timeout" value="900"/>
    <property name="meveo.instance.name" value="demo"/>
    <property name="java.net.preferIPv4Stack" value="true"/>
    <property name="meveo.keycloak.url" value="http://localhost:8081/auth"/>
    <property name="meveo.keycloak.secret" value="afe07e5a-68cb-4fb0-8b75-5b6053b07dc3"/>
    <property name="meveo.keycloak.realm" value="meveo"/>
    <property name="meveo.keycloak.client" value="meveo-web"/>
    <property name="meveo.admin.server.name" value="localhost"/>
    <property name="meveo.admin.port.number" value="5432"/>
    <property name="meveo.admin.database.name" value="meveo"/>
    <property name="meveo.admin.database.driver" value="postgresql"/>
    <property name="meveo.admin.database.username" value="postgres"/>
    <property name="meveo.admin.database.password" value="<your-postgresql-admin-password>"/>
    <property name="jboss.tx.node.id" value="meveo-default"/>
    <property name="meveo.keycloak.fixed-hostname" value="localhost"/>
    <property name="resteasy.preferJacksonOverJsonB" value="true"/>
</system-properties>

*Note that we are using the postgres admin account here.

Add a Datasource

  1. Open the file WILDFLY_HOME\standalone\configuration\standalone.xml.

  2. Search for "subsystem xmlns="urn:jboss:domain:datasources".

  3. Add the following datasource configuration.

<xa-datasource jndi-name="java:jboss/datasources/MeveoAdminDatasource" pool-name="meveo" enabled="true" use-java-context="true" use-ccm="false">
    <xa-datasource-property name="ServerName">
        ${meveo.admin.server.name}
    </xa-datasource-property>
    <xa-datasource-property name="PortNumber">
        5432
    </xa-datasource-property>
    <xa-datasource-property name="DatabaseName">
        meveo
    </xa-datasource-property>
    <driver>postgresql</driver>
    <xa-pool>
        <min-pool-size>10</min-pool-size>
        <max-pool-size>200</max-pool-size>
        <prefill>false</prefill>
        <use-strict-min>false</use-strict-min>
        <flush-strategy>FailingConnectionOnly</flush-strategy>
    </xa-pool>
    <security>
        <user-name>${meveo.admin.database.username:meveo}</user-name>
        <password>${meveo.admin.database.password:meveo}</password>
    </security>
    <validation>
        <valid-connection-checker class-name="org.jboss.jca.adapters.jdbc.extensions.postgres.PostgreSQLValidConnectionChecker"/>
        <validate-on-match>true</validate-on-match>
        <background-validation>false</background-validation>
        <use-fast-fail>true</use-fast-fail>
        <exception-sorter class-name="org.jboss.jca.adapters.jdbc.extensions.postgres.PostgreSQLExceptionSorter"/>
    </validation>
    <timeout>
        <blocking-timeout-millis>60000</blocking-timeout-millis>
        <idle-timeout-minutes>15</idle-timeout-minutes>
    </timeout>
    <statement>
        <share-prepared-statements>true</share-prepared-statements>
    </statement>
</xa-datasource>

Add the PostgreSQL driver as well in the drivers section:

<driver name="postgresql" module="org.postgresql">
    <driver-class>org.postgresql.Driver</driver-class>
    <xa-datasource-class>org.postgresql.xa.PGXADataSource</xa-datasource-class>
</driver>
Add Infinispan Cache

Search for "subsystem xmlns="urn:jboss:domain:infinispan" and add the cache container below.

<cache-container name="meveo">
    <local-cache name="meveo-multiTenant-cache"/>
    <local-cache name="meveo-price-plan"/>
    <local-cache name="meveo-usage-charge-template-cache"/>
    <local-cache name="meveo-charge-instance-cache"/>
    <local-cache name="meveo-counter-cache"/>
    <local-cache name="meveo-edr-cache">
        <object-memory size="100000"/>
    </local-cache>
    <local-cache name="meveo-access-cache"/>
    <local-cache name="meveo-cft-cache"/>
    <local-cache name="meveo-cet-cache"/>
    <local-cache name="meveo-notification-cache"/>
    <local-cache name="meveo-balance"/>
    <local-cache name="meveo-reservedBalance"/>
    <local-cache name="meveo-usageChargeInstanceWallet"/>
    <local-cache name="meveo-running-jobs"/>
    <local-cache name="unique-crt">
        <expiration interval="300000" lifespan="300000"/>
    </local-cache>
    <local-cache name="endpoints-results">
        <expiration interval="604800000" lifespan="604800000"/>
    </local-cache>
    <local-cache name="meveo-es-index-cache"/>
    <local-cache name="meveo-crt-cache"/>
    <local-cache name="meveo-rows-page-cache"/>
</cache-container>
Download Meveo Properties

  1. Download this file Meveo properties file.

  2. Make sure to make the necessary changes depending on your local configuration. See keys like meveo.log.file, binary.storage.path and providers.rootDir.

  3. Copy this file into WILDFLY_HOME\standalone\configuration.

Create a Wildfly Admin User

  1. Open a command prompt.

  2. Navigate to WILDFLY_HOME\bin.

  3. Run add-user.bat.

    1. Select management User

  4. Enter your desired user account.

  5. An "admin" account already exists, so you must update it instead.

  6. Enter any String for group.

Login to Wildfly Server

  1. Open your favorite browser.

  2. Enter the url localhost:8080.

  3. Click Administration Console.

  4. Login using your newly created account.

A completely configured file is available for reference here.

Eclipse

  1. Download the eclipse installer.

  2. Run the installer and select the Eclipse for JavaEE developers.

Install JBoss Tools Plugin

  1. Run Eclipse IDE.

  2. Open menu Help / Eclipse Marketplace.

  3. In the Find text field enter "jboss".

  4. Find JBoss Tools and click Install.

  5. Don’t install all the components, select or filter maven, egit and jboss as.

Add both the Keycloak and Wildfly Server for Debugging

  1. Open the Server tab by clicking Window / Show View / Other and filter for server.

  2. Select servers, a new tab should open.

  3. Right click on the server panel, select New / Server and select Wildfly 15.

  4. Click Next, select Create a new runtime.

  5. Click Next, and browse the directory where you installed Wildfly - WILDFLY_HOME.

  6. In the Configuration file field select standalone-full.xml. This is the one we modified earlier.

  7. Click Next and then Finish.

*Do the same with Keycloak.

Now you can start running either the Keycloak and Wildfly server in debug mode by right clicking on it and selecting Debug. You can click the Debug icon too.

Cloning the Meveo Project

This is done inside Eclipse IDE. Since we have installed egit component from JBoss Tools plugin, we can use it to checkout from Github.

  1. Open Window / Show View / Other and filter for git.

  2. Select both Git Repositories and Git Staging. Two new panels should open.

  3. Open Git Repositories.

  4. Right click and then select Clone a Git Repository or click the green icon in the top right corner with the same label.

  5. In the URI enter git@github.com:meveo-org/meveo.git, click Next.

  6. A selection of branch that you wanted to checkout should appear. By default all branches are selected. Click Next.

  7. Select the directory where you want to checkout the project, click Finish.

  8. Once the cloning is done, meveo project should appear in your Git Repositories.

  9. Right click on the meveo repository and select Import Maven Projects.

  10. Make sure that all projects are selected. You can select a working set (use for grouping projects) and then hit finish.

  11. Meveo projects should be visible in your Package or Project explorer, whichever is open.

  12. Now you can start coding.

Deploying Meveo to Wildfly

  1. Open the server tab once again.

  2. Select Add and Remove.

  3. Select meveo-admin-web, click Finish.

  4. Debug or start the server.

  5. Open the console log from Window / Show View / Console.

  6. If no error is shown, you should be able to access meveo from the URL http://localhost:8080/meveo.

  7. Login using the account meveo.admin / meveo.