V5.0.3 with RHEL / CentOS 7

This page explains how to install ]project-open[ V5.0 on RHEL/CentOS 7 64bit. Please see the discussion thread https://sourceforge.net/p/project-open/discussion/295937/thread/cfa36e81/  on SourceForge. 

Last updated: 2020-04-22 

VMware Virtual Machine

Installing ]po[ requires not only Linux expertise but also some time. As a shortcut, you can use our CentOS 7 virtual machine on http://sourceforge.net/projects/project-open/files/project-open/V5.0/ . This virtual machine has been built following the instructions below and has been exhaustively tested.

Docker Image

There is an experimental(!) installer available for Docker  that can be downloaded from our SourceForge repository .

Base CentOS 7 Installation

Please help us to improve below instructions. To report any bugs please use the SF Community forum . To get professional support please contact us .

Please download CentOS 7 "Minimal Installation" and install with the option "Minimal Install".

After a reboot, login as root an:

  • nmtui
    set the host name to "project-open-v50"
  • nmtui
    setup an network connection: "Edit a connection", select an ethernet interface, edit the configuration, select "Automatically connect" and quit.
  • systemctl restart network
    in order to restart the network manager
  • yum -y install system-config-*
    yum -y group install "System Administration Tools" --setopt=group_package_types=mandatory,default,optional 
    in order to install system administration tools 

To verify network connectivity try to ping some external server, for example: 

ping www.google.com

Install "KDE Plasma Workspaces" Graphical Environment

GNOME 3 on CentOS 7 has a number of important issues, so the ]po[ team recommends to switch to KDE: 

yum -y group install "KDE Plasma Workspaces" "X Window System"
yum -y group install "Graphical Administration Tools" --setopt=group_package_types=mandatory,default,optional
yum -y install net-tools setools policycoreutils-python
ln -sf /lib/systemd/system/graphical.target /etc/systemd/system/default.target

Development Tools

]po[ will need a number of tools for creating systems integration interfaces. 

yum -y group install "Development Tools" --setopt=group_package_types=mandatory,default,optional
yum -y group install "Compatibility Libraries"
yum -y install vim emacs-nox
yum -y install cvs svn git wget libXaw expat expat-devel pango graphviz graphviz-devel ImageMagick
yum -y install libdbi-dbd-pgsql openldap-clients openldap-devel mlocate sharutils psmisc

Perl Libraries

]po[ uses Perl for integration with several external applications: 

yum -y install graphviz-perl perl perl-Archive-Tar perl-Archive-Zip perl-CGI perl-CGI-Session
yum -y install perl-CPAN perl-CPAN-Changes perl-CPAN-Meta perl-CPAN-Meta-Requirements perl-CPAN-Meta-YAML
yum -y install perl-Carp perl-Compress-Raw-Bzip2 perl-Crypt-DES perl-Crypt-OpenSSL-RSA
yum -y install perl-Crypt-OpenSSL-Random perl-Crypt-PasswdMD5 perl-Crypt-SSLeay perl-DBD-Pg
yum -y install perl-DBD-Pg-tests perl-DBI perl-Data-Dumper perl-DateTime perl-Digest-MD5
yum -y install perl-Encode perl-File-Slurp perl-GSSAPI perl-IO-Socket-IP perl-IO-Socket-SSL
yum -y install perl-JSON perl-LDAP perl-LWP-MediaTypes perl-LWP-Protocol-https perl-Net-DNS
yum -y install perl-Net-HTTP perl-Net-SSLeay perl-Params-Check perl-Params-Util perl-Params-Validate
yum -y install perl-Socket perl-TimeDate perl-WWW-Curl perl-YAML perl-core perl-devel perl-gettext
yum -y install perl-libs perl-libwww-perl rrdtool-perl perl-YAML

Install OpenOffice/LibreOffice

]po[ PDF generation functions use OpenOffice "headless" in order to convert ODT templates to PDF:: 
yum -y install libreoffice libreoffice-headless

Optional Environment Configurations 

Include the user "projop" in group "wheel" in order to allow projop to become root via "sudo su -":  Edit /etc/group and add the user "projop" in the line with group "wheel": 

wheel:x:10:projop

Edit /etc/profile to add a few personal shortcuts: 

alias "l=ls -als"
export EDITOR=emacs

Edit /web/projop/.bash_profile and add the following lines: 

export CVSROOT=":pserver:anonymous@cvs.project-open.net:/home/cvsroot"
export CVSREAD="yes"
export CVS_RSH="ssh"
export EDITOR=emacs

alias "l=ls -als"
alias "u=cvs update -PdA > update.stdout 2> update.stderr"
export EDITOR=emacs

Include the hostname (project-open-v50 by default) in /etc/hosts as localhost or with it's fixed IP (if it has a fixed IP...): 

127.0.0.1 localhost project-open-v50

Download Required Files

Please download the following files into your /usr/src/ directory:

Extract the ]po[ Installer Contents 

Please go through the following steps to create a ]po[ user "projop" and to extract the installer into this user's home directory: 

groupadd projop                                                              # create a group called "projop"
mkdir /web/                                                                  # super-directory for all Web servers /web/ by default
useradd -d /web/projop -g projop projop                                      # create user "projop" with home directory /web/projop
cd /web/projop/
tar xzf /usr/src/web_projop-aux-files.5.0.0.0.0.tgz                          # extract auxillary files
tar xzf /usr/src/project-open-Update-5.0.3.0.0.tgz                           # extract the ]po[ product source code - latest
chown -R projop:projop /web/projop                                           # set ownership to all files

cd /usr/local
tar xzf /usr/src/naviserver-4.99.8.tgz                                       # extract the NaviServer binary 64 bit

Setup PostgreSQL 9.2

PostgreSQL 9.2 is part of CentOS 7. Please use exactly this version.

Please install the database using: 

yum -y install postgresql postgresql-server postgresql-contrib postgresql-devel postgresql-odbc postgresql-docs

Configure PostgreSQL startup: 

systemctl enable postgresql
Initialize and start the database: 
/usr/bin/postgresql-setup initdb
systemctl start postgresql

Create a new database user "projop" and the corresponding database: 

su - postgres -c "createuser -s projop"                             # database user "projop" with admin rights
su - projop -c "createdb --encoding=utf8 --owner=projop projop"     # new database
su - projop -c "createlang plpgsql projop"                          # enable PlPg/SQL, may already be installed

You can verify your PostgreSQL installation by typing ("\q" or Ctrl-D for exit): 

su - projop -c psql

Enter "\q" or press Ctrl-D to exit.

Now import the database dump: 

su - projop
psql -f ~/pg_dump.5.0.3.0.0.sql > import.log 2>&1

The import can take up to a minute, depending on your system. Please ignore the ~3.500 error messaging showing up at the beginning (that's because the dump contains instructions to drop any stuff that's left in the DB...). In order to verify the import please execute: 

su - projop
psql -c "select count(*) from users"

.. which should return 198 or a similar number (the number of demo users in the demo company provided as part of the installer).

Please edit the "postgresql.conf" configuration file in /var/lib/pgsql/data/:

  • listen_addresses:
    Please choose between 'localhost' or '*':
    • 'localhost' is the safe option, meaning that the PostgreSQL is only visible for the processes running on the server itself.
    • '*' means that users on other computers may access the database. You need to enable this if you want to connect to the DB via pgAdminIII, or if you want to integration ]po[ with some other systems. In this case you also need to edit the pg_hba.conf in the same folder. Please see the PostgreSQL documentation for details.

  • max_connections:
    • 100 for the VMware appliances for two ]po[ instances ("projop" and "stage"), as each ]po[ instances opens a number of connections during startup.
    • 500 for SaaS production servers

  • shared_buffers:
    How much memory should PostgreSQL get? PG experts recommend between 1/6th and half of the available RAM for high-performance production systems.
    • 512MB - We use this value for the default ]po[ virtual machine, because it may run on only 1GB of RAM.
    • 4096MB - This is the value used in our SaaS production servers.

  • work_mem:
    Please see this blog on PG performance .
    We set it to 64MB up from 64kB, because of potentially large lists of data to be sorted.

  • maintenance_work_mem:
    We use 256MB, if there are >= 2GB of RAM

  • checkpoint_segments: 64

  • timezone and log_timezone:
    Please set to your timezone. We use 'Europe/Madrid' for the VMware appliance.
    Changing the time zone during production operations will lead to duplicate entries when logging hours and tasks being shifted by one day in the Gantt Editor.

Please edit the "pg_hba.conf" configuration file in /var/lib/pgsql/data/:

At the end of the file there should be three uncommented lines: 

local   all             all                                     peer
host    all             all             127.0.0.1/32            trust
host    all             all             ::1/128                 ident
This configuration allows locally running applications (specifically pgAdmin3) to connect to the database without providing a password.

 

Edit the ]po[ configuration file

Please modify /web/projop/etc/config.tcl for the following parameters: 

set servername   "<your_company> \]project-open\[ Server"
set homedir      /usr/local/ns

You can also modify the http port if you know what you are doing. Please note that the port number has to be above 1024 for permission reasons.

Open the Firewall Port 80, 443 (and 8000)

The firewall is enabled by default in CentOS 7, so we will have to punch holes for the ]project-open[ ports 80, 443 and 8000 graphically using system-config-firewall-tui or manually: 

firewall-cmd --add-port=80/tcp --permanent
firewall-cmd --add-port=443/tcp --permanent
firewall-cmd --add-port=8000/tcp --permanent
firewall-cmd --reload

Port 8000 is the direct access to the NaviServer. This port is normally not exposed directly to the user, but only via a reverse proxy. So opening this port is optional, but may be interesting if you are running a reverse proxy (NGINX, Pound) on a different system (Web application firewall, ...) that exposes the service to the end user.

Start ]project-open[ Manually 

/usr/local/ns/bin/nsd -f -t /web/projop/etc/config.tcl -u projop -g projop

]po[ should take a few seconds before the line appears "[...] Notice: nssock: listening on 0.0.0.0:8000".

As a result, you should be able to see 8000 in the list of ports accepting connections: 

netstat -nlp | grep 8000

Please point your favorite Web browser to http://localhost:8000/ and login as "sysadmin@tigerpond.com" / "system". You should see a login page (default admin: "sysadmin@tigerpond.com" / "system") or a configuration wizard. Please do not continue here at the moment, because we still need to fix several issues before ]po[ will run as desired.

You can stop the ]po[ server in the terminal window using Ctrl-C.

Congratulations, great job!

Automate NaviServer Startup

We now have to automate the startup of NaviServer (the application server of ]project-open[) for production use:

Create a new file /usr/lib/systemd/system/projop.service with the following content:  

[Unit]
Description=NaviServer Web Server as user projop
After=postgresql.service network.target
Wants=postgresql.service

[Service]
Type=forking
PIDFile=/web/projop/log/nsd.pid

ExecStartPre=/usr/bin/rm -f /web/projop/log/nsd.pid
ExecStart=/usr/local/ns/bin/nsd -t /web/projop/etc/config.tcl -u projop -g projop &
ExecReload=/bin/kill -s HUP $MAINPID
ExecStop=/bin/kill -s 9 $MAINPID

Restart=always
# Restart=on-abort
# Restart=on-abnormal

KillMode=process

[Install]
WantedBy=multi-user.target

Please execute the following commands in order to activate the configuration: 

systemctl daemon-reload
systemctl enable projop.service
systemctl start projop.service
You can check that NaviServer is running by monitoring it's error file (debugging is switched on by default): 
tail -f /web/projop/log/error.log

Install nginx on Port 80

]project-open[ by default listens on port 8000 and for permission reasons can not listen on port 80. As a workaround you can install a “reverse proxy†server on port 80 that redirects HTTP requests to port 8000.

You can configure Apache for such a purpose, Apsis Pound or or the small Web server ngnix. Ngnix is part of the Red Hat/CentOS 7 distribution system and more convenient than apache2, so this is why we use it by default now. Ngnix is also convenient if you want to run more then one ]po[ or non-]po[ server on your machine, because it allows you to distribute HTTP requests to different back-ends, depending on the HTTP headers etc.

In order to install nginx we need to enable the "epel" repositories with experimental software for CentOS:  

yum -y install epel-release
yum -y install nginx
Assuming that there is no other process listening on port 80 (netstat -nlp | grep 80), please edit /etc/nginx/nginx.conf to look like this (modifying the "server {...}" section): 
user nginx;
worker_processes auto;
error_log /var/log/nginx/error.log;
pid /run/nginx.pid;

events {
    worker_connections 1024;
}

http {
    log_format  main  '$remote_addr - $remote_user [$time_local] "$request" '
                      '$status $body_bytes_sent "$http_referer" '
                      '"$http_user_agent" "$http_x_forwarded_for"';
    access_log          /var/log/nginx/access.log  main;
    sendfile            on;
    tcp_nopush          on;
    tcp_nodelay         on;
    keepalive_timeout   601;
    types_hash_max_size 2048;
    default_type        application/octet-stream;
    include             /etc/nginx/mime.types;
    include             /etc/nginx/conf.d/*.conf;

    server {
        listen 80;
        location / {
            # pass all communication to NaviServer on port 8000
            proxy_pass           http://127.0.0.1:8000;
            # add information about the original IP
            proxy_set_header     X-Forwarded-For $remote_addr;
            # upload files to file storage up to 1G
            client_max_body_size 1024M;
        }

        # error_page    500 502 503 504 /err/50x.html;
        # error_page    404             /err/404.html;
        # location /err/ {
        #     root /usr/share/nginx/html;
        # }

    }
}


Then please perform: 

systemctl enable nginx
systemctl restart nginx
netstat -nlp | grep 80

You should now see nginx listening on port 80.

As a next step you need to tell SELinx to allow nginx to create an outgoing connection to port 8000:

Point your browser to http://localhost:80/ in order to cause a "502 Bad Gateway" error (it is important to cause this error!). Please check your firewall configuration if you don't get a "502" error.
Then execute the following commands: 

cat /var/log/audit/audit.log | grep nginx | grep denied | audit2allow -M mynginx
semodule -i mynginx.pp

Now point your browser again to http://localhost/ and you should see ]po[ in action.

 

Install nginx on Port 443 with TLS

Configuring TLS requires to steps:

  1. Configuring nginx with TLS
  2. Obtaining a valid certificate.

In this tutorial, we are going to work with a self-signed certificate for 2. For a production installation please use Let's Encrypt or a similar service. 

Configure nginx with TLS 

Here is an alternative nginx.conf configuration with HTTPS support, redirecting from HTTP (port 80) to HTTPS (port 443):  

user nginx;
worker_processes auto;
error_log /var/log/nginx/error.log;
pid /run/nginx.pid;

events {
    worker_connections 1024;
}

http {
    log_format  main  '$remote_addr - $remote_user [$time_local] "$request" '
                      '$status $body_bytes_sent "$http_referer" '
                      '"$http_user_agent" "$http_x_forwarded_for"';
    access_log          /var/log/nginx/access.log  main;
    sendfile            on;
    tcp_nopush          on;
    tcp_nodelay         on;
    keepalive_timeout   601;
    types_hash_max_size 2048;
    default_type        application/octet-stream;
    include             /etc/nginx/mime.types;
    include             /etc/nginx/conf.d/*.conf;

    server {
       listen         80;
       return         301 https://$host$request_uri;
    }

    server {
        listen       443 ssl default_server;

        ssl_certificate     /etc/nginx/certificate.crt;
        ssl_certificate_key /etc/nginx/certificate.key;
        ssl_session_cache   shared:SSL:1m;
        ssl_session_timeout 10m;
        ssl_protocols       TLSv1.2;
        ssl_ciphers         HIGH:!aNULL:!MD5;
        ssl_prefer_server_ciphers on;

        location / {
                proxy_pass        http://127.0.0.1:8000;
                proxy_set_header  X-Forwarded-For $remote_addr;
                client_max_body_size 1024M;
        }
        # error_page    500 502 503 504 /err/50x.html;
        # error_page    404             /err/404.html;
        # location /err/ {
        #         root /etc/nginx/err;
        # }
    }
}

 

Create a self-signed certificate

Please execute the following commands as user root: 

openssl req -x509 -nodes -days 3650 -newkey rsa:2048 -keyout /etc/nginx/certificate.key -out /etc/nginx/certificate.crt

Now OpenSSL will ask you about the data of the certificate. Here we will use the following example for a certificate supposed to be for ]project-open[ Business Solutions, S.L.:

  • Country Name: ES (for Spain)
  • State of Province Name: Catalonia
  • Locality Name: Barcelona
  • Organization Name: ]project-open[ Business Solutions, S.L
  • Organizational Unit Name: <empty>
  • Common Name: project-open-v50.project-open.net
  • Email Address: info @project-open.com

Then restart nginx: 

systemctl restart nginx

 

Configure Automatic Backups

You can automate a daily ]po[ backup using our default export-dbs script. Please copy the script (please follow the link for source code) into the file /root/bin/export-dbs. Mark the script as executable, create default backup directories and execute the script: 

mkdir /var/backup                                             # create a global backup directory
chown projop:postgres /var/backup                             # allow projop & PostgreSQL to write backups
chmod g+w /var/backup

mkdir /var/log/backup                                         # create directory for DB related logs
chown postgres:postgres /var/log/backup                       # allow projop & PostgreSQL to write
chmod g+w /var/log/backup
chmod ug+x /root/bin/export-dbs # mark backup script as executable perl /root/bin/export-dbs # execute backup script
Automate the backup by adding the following lines to your crontab: 
29 3 * * * /usr/bin/perl /root/bin/export-dbs > /var/log/postgres/export-dbs.log 2>&1
24 3 * * * /usr/bin/find /var/backup -name '*.tgz' -mtime +6 | xargs rm
25 3 * * * /usr/bin/find /var/backup -name '*.bz2' -mtime +6 | xargs rm

Fix GraphViz Configuration

GraphViz creates GIF and PNG images from textual descriptions. ]po[ uses GraphViz to visualize the state of workflows and similar purposes.

To fix/enable GraphViz, please create a symbolic link for the "dot" tool: 

cd /usr/local/bin/
ln -s /usr/bin/dot

 

Install and Test "Postfix" Email Server

]po[ by default uses Postfix to send out notification emails. To install please use: 

yum -y install postfix postfix-perl-scripts mailx

You can test your email configuration by sending out a test email to yourself: 

echo "test email body" | mail -s "Test Email Subject" <you@your_domain.com>

Then have a look at the last lines of /var/log/maillog 

tail -n 20 /var/log/maillog

You may have to configure a Postfix "relayhost" pointing to your corporate SMTP server or simiar. Please check configure-external-smtp-server for more details.

For a development server you may want to configure a local delivery of all email to the local root account for debugging purposes.

In this case please edit your /etc/postfix/main.cf and add the following three lines: 

luser_relay = root@localhost
local_recipient_maps =
mydestination = pcre:/etc/postfix/mydestinations

Then create the file /etc/postfix/mydestinations and add a single line: 

/.*/      ACCEPT
Then restart Postfix using systemctl restart postifx .

(The solution was taken from this discussion thread .)

 

Enable ]po[ Integration Links

]po[ includes a long list of integration links with external systems including Microsoft Active Directory, SAP FI, SAP PS, Microsoft Navision NAV, SQL-Ledger, SugarCRM, vTiger, Atlassian Jira, TaskJuggler, OCS Inventory NG, CVS, SVN Subversion, Git, Email, and others. Most of these integration links use Perl and Perl libraries as interfaces. Therefore you will need to have working versions of a number of Perl modules installed on your system.

There are two steps necessary in order to install these Perl libraries:

Install Most Perl Libraries via YUM

Most Perl libraries are available from the standard CentOS and "EPEL" repositories as RPMs and installable via YUM. First you need to add the EPEL repositories, if you didn't do this already: 

yum -y install epel-release

After that, you can install additional Perl packages: 

yum -y install perl-MIME-tools
yum -y install perl-Path-Class
yum -y install perl-IO-Socket-INET6

Install Missing Perl Libraries via CPAN

Finally, you will have to manually compile and deploy some Perl libraries that are not available as part of CentOS for whatever reasons.

So we will have to pursue a somehow dirty method here and install the additional Perl packages in system folders that are managed by YUM. In order to do so, we will need to configure CPAN to use the system folders.

1. Cleanup any files from previous installations

  • delete /root/.cpan
  • delete /root/perl5
  • edit /root/.bashrc and check and remove any PERL environment variables
  • logout and login again
  • execute "set | grep -i perl" to check that no environment variables are set 

2. Start CPAN as user "root": 

cpan

  • Answer "no" to the first question ("Would you like to configure as much as possible automatically?") in order to enter into manual configuration. 
  • Answer "sudo" to the next question ("What approach do you want?  (Choose 'local::lib', 'sudo' or 'manual')")
  • Answer <enter> to all remaining questions (just press the Enter key...)

CPAN should write out a page or two of text, select the closest mirror for you and then enter interactive with command prompt waiting for commands. Please enter: 

cpan[1]> install IO::Socket::PortState                  # follow defaults by pressing <Enter> if needed
cpan[3]> quit

Please observe upper/lower case in the commands above.

Now copy PortState.pm to the Perl5 library: 

cp /usr/local/share/perl5/IO/Socket/PortState.pm /usr/share/perl5/vendor_perl/IO/Socket/

This action actually breaks the YUM package system because PortState.pm will remain unmaintained in a YUM controlled directory. However, there have been no practical solution yet coming from discussions with the RHEL/CentOS maintainers for this library which is not available as a RPM.

 

Cleanup and Release Preparation

The following steps cleanup data after a successfull installation. These steps are not necessary for production operation.

Cleanup ]po[ log files: 

cd /web/projop/log
rm *

Cleanup Projop "Desktop" files: 

cd /web/projop/Desktop
rm -r *

Cleanup YUM files: 

yum clean all

Cleanup /tmp: 

cd /tmp
<delete unnecessary files>

Cleanup /var/tmp: 

cd /var/tmp
rm -r abrt
rm -r kdecache-projop

Cleanup /var/spool: 

cd /var/spool
du -sk *
<delete unnecessary files>

Cleanup /var/log: 

cd /var/log
rm *
du -sk *
<delete unnecessary files>
systemctl restart rsyslog.service

Cleanup history files: 

rm /root/.bash_history
rm /web/projop/.bash_history
rm /web/projop/.psql_history

Erase the disk with zeros for better compression of the VM. Please note that the first "dd" command will fail with an "No space left on device" error. Please make sure the PostgreSQL database is not active: 

dd bs=1M count=1000000 if=/dev/zero of=/zero
rm /zero

Run SysConfig -> "Disable everything except SysConfig" in order to prepare the machine for delivery.

 


Upgrade ]project-open[

Please see available updates. Please read the forum and other sources in order to see if it is necessary to upgrade. Please see the V5.0 release notes for information on known issues.

Integration With Other Systems

Please see http://www.project-open.com/en/list-integration-links  for a list of supported integration links with other software packages.

FAQs, Documents and Issues Related CentOS  7

Did you encounter any issues? Did you successfully install ]project-open[?

Please let us know for what purpose you want to use ]project-open[, and we provide you with half a day of free training or consulting if we publish a Success Story together.

If you found an issue please:

  1. Please check the discussion thread https://sourceforge.net/p/project-open/discussion/295937/thread/cfa36e81/  on SourceForge as the first resort.
  2. Search your ~projop/log/error.log file for occurrences of the string “Error:†(upper case “E†and a colon as the last characters). Errors about “translation not found†are OK, but everything else is suspicious.
  3. Please check our FAQ section as a first step.
    Here you will find tips for diagnosing and debugging issues.
  4. Try searching for key words included in your issue here on www.project-open.org  using the search box on the top right of this page.
  5. Please visit our Open Discussions  forum at SourceForge and search for your issue. 
  6. Please check the RHEL/CentOS 6 installer thread .
  7. The ]project-open[ core team provides training, professional support and consulting services. Please contact us   if you want to use ]po[ for more then a dozen of users.
 
  Contact Us
  Project Open Business Solutions S.L.

Calle Aprestadora 19, 12o-2a

08902 Hospitalet de Llobregat (Barcelona)

Spain

 Tel Europe: +34 609 953 751
 Tel US: +1 415 200 2465
 Mail: info@project-open.com

  Links: