Installation manual

The ready-to-use qcadoo MES installation package

We provide ready-to-use installation packages for qcadoo MES. Please visit our Download page and select the latest stable release or an unstable one, if you want to have access to the newest features.

There are only two requirements, that the Java 8 JDK and database have to be already installed.

Requirements

Install the Java 8 JDK

In case of missing Java 8 JDK please go to the Java download page, click the Download JDK button and install JDK. If you have any questions please refer to the Installation Instructions document.

On Linux systems you can also use your default package manager. Just look for the openjdk-8-jdk package. For example on Debian-based systems typing:

sudo apt-get install openjdk-8-jdk

should download all the packages you need.

Do I have a Java 8 JDK installed?

  • Linux/Mac Os X - open terminal and type java -version, Java version information should be presented.
  • Windows - open terminal (type cmd on Start > Run) and type java -version, Java version information should be presented.

 Windows JDK setup

Add Java 8 JDK bin to the PATH variable.

Open Start > Control Panel > System and click Advanced > Environment Variables. Add the location of bin folder of JDK installation for PATH in System Variables. A typical value for PATH is C:\Program Files\Java\jdk1.8.0_version\bin. The PATH variable is a series of directories separated by semi-colons.

What value of the PATH variable do I have?

Open terminal (type cmd on Start > Run) and type echo %PATH%, Java bin path should be included in PATH variable.

Set the JAVA_HOME variable

  • Windows: My Computer > 'Properties' > 'Advanced' > 'Environment Variables' > 'System Variables' > 'New'. Enter the variable name as JAVA_HOME, enter the variable value as the installation path for the Java Development, click 'OK' and click 'Apply Changes'.
  • Linux/MacOS: edit ~/.bash_profile (or create it if it doesn't exist) and add "export JAVA_HOME=<installation path for the Java Development Kit>" (without the "") and "export PATH=$PATH:$JAVA_HOME/bin" lines to it.

Install the database

In this guide we will use the Postgres database.

Can I use another database?

You can use any database supported by the Hibernate Java library. See http://community.jboss.org/wiki/SupportedDatabases for more details.
This will require however some JDBC knowledge do configure it in qcadoo-bin/conf/db.properties file and you will have to supply the appropriate driver to the lib directory.

Also please note that for now we mainly test Qcadoo on the Postgres database.

If the installer asks you for the password for the user postrges please type: postgres123

Thanks to this you won't have to edit the database properties in the next steps.

On Windows download the installer from: http://www.postgresql.org/download/windows

On Mac OS download the appropriate package from: http://www.postgresql.org/download/macosx or the simple version from http://postgresapp.com

To allow access to Postgres on Mac OS you will also have to edit the file /PostgreSQL/9.X/data/pg_hba.conf as a super user and it should look like this:

local   all             all                                     trust
host    all             all             127.0.0.1/32            trust
host    all             all             ::1/128                 trust

The above step is also required on some Linux systems. For example in Fedora this configuration file is /var/lib/pgsql/data/pg_hba.conf

To install on Linux systems you can find it in your package manager. After the installation see if your postgres service is running. On some distributions your have to do additional steps after installation to start it.

For example on Fedora you have to do: service postgresql initdb; service postgresql start

When you're sure that postgres is up and running then you will have to do the following steps as super user to set it up:

  1. Set the password for the user postgres to postgres123 user using:

    sudo passwd postgres
    
  2. Connect to the database using:

    sudo su postgres -c psql
    
  3. In Postgres shell set the password for the postgres user to postgres123 using:

    ALTER USER postgres with PASSWORD 'postgres123';
    
  4. Create the mes database with appropriate locale e.g. en_US.UTF-8 using:

    CREATE DATABASE mes WITH ENCODING 'UTF8' LC_COLLATE 'en_US.UTF-8' LC_CTYPE 'en_US.UTF-8' TEMPLATE template0;
    

Installation

Download the installation package

Go to the qcadoo  MES Open Source to get the installation package (or complete source code if you know how to deal with it).

Unpack the installation package

  • Linux/Mac Os X - open terminal and type unzip qcadoo.zip
  • Windows - double-click on qcadoo.zip

Due to a bug in our startup mechanism:http://issues.qcadoo.org/browse/QCADOOMES-18
you have to unzip qcadoo MES to a directory path with no white chars.

On Windows the safest way to go is to just unzip it to directly to C:/ or D:/

Install the JDBC driver for the database (optional)

Qcadoo MES application is already prepared to working with PostgreSQL database. For other databases there is a need to install JDBC drivers. To do that please download JDBC4 driver and put it into qcadoo/lib directory. Remove qcadoo-bin/lib/postgresql-9.X-XXX.jdbc4.jar file.

What databases are supported

Currently only PostgreSQL 9.5 has been fully tested and is officially supported by qcadoo MES team.

Configure the database

Open qcadoo/qcadoo/db.properties and set the properties:

  • dbDriverClass - name of the driver class (org.postgresql.Driver for PostgreSQL)
  • dbJdbcUrl - database's URL as: jdbc:postgresql[://host:port/]:[database_name] where the host name (either the IP address or a literal name) and the port number are optional, ie. you can use jdbc:postgresql:mes, jdbc:postgresql://localhost/mes or jdbc:postgresql://localhost:5432/mes
  • dbUsername - database's user
  • dbPassword - database's password
  • hibernateDialect - database's dialect (org.hibernate.dialect.PostgreSQLDialect for PostgreSQL)

What the dialect means?

Dialect represents database specific SQL format. Please see list of the dialects for more information.

This is the sample db.properties file:

dbDriverClass=org.postgresql.Driver
dbJdbcUrl=jdbc:postgresql:mes
dbUsername=postgres
dbPassword=postgres123
hibernateDialect=org.hibernate.dialect.PostgreSQLDialect

Set OS-specific configuration options

There are still some configuration options you must check before you can start using qcadoo MES. These options are OS specific.

In the file qcadoo-bin/qcadoo/report.properties please check if the property reportPath points to a valid directory where you want to store generated reports.

Also check if the *Fonts property for your OS points to the right file. For example if you are on a Windows OS check if the file pointed by windowsFonts exists.

Start the application

Before first run!

Before first run, You have to restore clean database schema that We provide with qcadoo MES package (mes-application/webapps/ROOT/WEB-INF/classes/schema/demo_db_en.sql). This is one of the conditions for qcadoo MES to work nice & smooth (smile)

All You have to do is to restore this dump using the following command in BASH (assuming, You have installed postgreSQL as the user postgres, and created database mes with password postgres123):

For linux users

Run before next command: 

sudo su postgres

psql -U postgres mes < path/to/schema/demo_db_en.sql

So, now You are ready to run!

  • Linux/Mac Os X - open terminal and type ./qcadoo-bin/bin/startup.sh
  • Windows - go to the qcadoo/bin folder and double-click on startup.bat

Use the application

Open Your favourite browser and type http://localhost:8080/. Login as superadmin user with password superadmin.

As You can see, there is only a few things visible in the menu. In order to see a whole bunch of features that we provide, go to Administration > Groups, and add all roles to Superadmin or Admin group. Now, log out and log in once again.

Please see User Documentation to find more information.

Access to logs

Logs can be found in directory qcadoo/logs/.

Most of the time you will find information you need in file root.log, for example if your instance started correctly, details of found errors etc.

You should ignore aspects errors and log4j errors from catalina.out - these are just warnings.

Troubleshooting

I've got a browser message that the page cannot be found

It usually means that there was some error on application startup. Please see qcadoo/logs/root.log to get more information.

I've got an error that the port 8080 is already in use

It means that the other application is using port 8080. Please stop the application using shutdown.sh, open the qcadoo-bin/conf/server.xml file and replace all occurrence of 8080 to 8181 (or another port if this one is also used). Save the file and start the application using startup.sh.