Difference between revisions of "Process:Installation guide"

Revision as of 09:04, 27 November 2023

Info
Process Name	Installation guide
Process Type	⧼ev-Technical Process⧽
Related Processes	Installation guide MintHCM v4
Related Modules

MintHCM Installation Guide

Add a Process Step

Short Description

The MintHCM Installing Guide is a technical document that provides detailed instructions on how to install and configure the software.

The guide covers everything from system requirements to database configuration and user setup. It is a comprehensive technical resource that provides you with the information you need to set up and configure the software effectively.

Requirements

To run MintHCM, your system must have

PHP 7.4 - 8.0
MySQL 5.7, 8.0 or Percona 8.0
ElasticSearch 7.9

Other versions are not supported!

MintHCM is compatible with Chromium, Firefox, and Edge web browsers. Unfortunately, we do not support IE, but you can still test and use it by yourself.

Preparing for installation

To install MintHCM you will need Linux or Windows platform, a web server with PHP installed and a database.

The first step towards installation is downloading MintHCM to your server and preparing files to be installed. To do so, follow the steps:

Download MintHCM zip file from https://minthcm.org/download/
Copy the zip file to your server
Unzip it in the directory of your choice
Change files permissions in that directory accordingly with your platform demands

For Ubuntu Linux/Apache it will be:

cd ../<yourMintHCMdirectory>
sudo chown -R www-data:www-data .
sudo chmod -R 755 .

where www-data are default user and group for Ubuntu Linux/Apache. However, it might have been changed on your server. Use the actual system user and group.

Be sure that .htaccess file has correct privileges (the same as other files) because it is necessary to installation process.

Installation of MintHCM

Once you have your files prepared, you can start actual installation. To do so, follow the steps below:

1. Open your web browser and enter the following URL to start the installation wizard.

https://my-server-or-domain.com/my-minthcm-directory

The installation wizard will start now.

2. On the first screen you have to accept the licence agreement. After that you can click the next button.

MintHCM - Installation - License

3. In a moment another screen with system environment information will appear.

MintHCM - Installation - System Environment

4. Enter basic database configuration and administrator user data on the next screen.

If the database and MintHCM are on the same server, enter 'localhost' in the Host Name field. If the database is on a different server, enter the hostname or IP address of the database server in the Host Name field.

MintHCM - Installation - Database configuration

MintHCM Database User is by default set to root. If you want to choose another user, change it here.

5. Set up your ElasticSearch connection. System needs it to displays data in list and in Global Search.

MintHCM - Installation - ElasticSearch configuration

6. Set up your administrator user name and password, so you can log in MintHCM later.

You have to provide Site URL. Usually in SiteURL field you should enter URL from your current browser tab to the „#” sign (characters after the „#” sign should not be entered). Here, you can check dummy data. The option will install Demo Data on instance. It can be helpfull if you do not want empty system.

MintHCM - Installation - Site configuration

7. If everything was alright with data provided, installation will begin. It may take a while

MintHCM - Installation - Installation in progress

8. After installation is completed, you will see the last screen. Among others, it provides information of total time of installation and memory use.

MintHCM - Installation - Finish

After clicking the button Go to login, the installation is complete and you can log in to your MintHCM instance as an administrator with the username and password you set up earlier.

9. Adding crontab

It's important to set up a Crontab to allow MintHCM to run background tasks on your server. It's necessary in order to index data to ElasticSearch. Edit your web server user's crontab file after the installation is completed.

To do so, you have to edit your web server user's crontab file. You can open it with a command:

sudo crontab -e -u www-data (or another actual user)

Now you have to add the following line to the crontab file:

*    *    *    *    *     cd /var/www/<dir_to_your_instance>/legacy; php -f cron.php > /dev/null 2>&1

Information about Crontab edition may be also found in Schedulers in Administration panel of MintHCM after installation.

Note that Windows or other systems have different background processes mechanisms.

Troubleshooting

Troubleshooting MintHCM3

Mentioned in other articles

@@ Line 1: / Line 1: @@
 {{Process-infobox
-|Process-name=Installation guide MintHCM v3
+|Process-name=Installation guide
 |Process-type=Technical Process
 |Related Processes=Installation guide MintHCM v4
@@ Line 9: / Line 9: @@
 }}
 ==Requirements==
-To run MintHCM, your system must have '''PHP 7.1 (only!) and MySQL 5.6 - 5.7 or MariaDB 10.0 - 10.3 installed'''. Other versions are not supported!
+To run MintHCM, your system must have
+* PHP 7.4 - 8.0
+* MySQL 5.7, 8.0 or Percona 8.0
+* ElasticSearch 7.9
+Other versions are not supported!
 MintHCM is compatible with Chromium, Firefox, and Edge web browsers. Unfortunately, we do not support IE, but you can still test and use it by yourself.
@@ Line 27: / Line 32: @@
 <syntaxhighlight lang="bash">
 cd ../<yourMintHCMdirectory>
-sudo chown -R www-data:www-data *
+sudo chown -R www-data:www-data .
-sudo chmod -R 755 *
+sudo chmod -R 755 .
 </syntaxhighlight>
 where www-data are default user and group for Ubuntu Linux/Apache. However, it might have been changed on your server. '''Use the actual system user and group.'''
+Be sure that .htaccess file has correct privileges (the same as other files) because it is necessary to installation process.
 ==Installation of MintHCM==
@@ Line 36: / Line 43: @@
 Once you have your files prepared, you can start actual installation. To do so, follow the steps below:
-. Open your web browser and '''enter the following URL''' to start the installation wizard.
+'''1. Open your web browser and enter the following URL to start the installation wizard.'''
   https://my-server-or-domain.com/my-minthcm-directory
@@ Line 42: / Line 49: @@
 The installation wizard will start now.
-. On the first screen you have to '''accept the licence agreement.''' After that you can click the next button.
+'''2. On the first screen you have to accept the licence agreement. After that you can click the next button.'''
-[[File:MintHCM - Installation - Start.png|900px|thumb|center|MintHCM - Installation - Start]]
-. In a moment another screen with system environment information will appear.
-[[File:MintHCM - Installation - System Environment.png|900px|thumb|center|MintHCM - Installation - System Environment]]
-It's important to set up a '''Crontab''' to allow MintHCM to run background tasks on your server.
-Edit your web server user's crontab file after the installation is completed.
-To do so, you have to '''edit your web server user's crontab file'''. You can open it with a command:
+[[File:MintHCM Installation - License.png|900px|thumb|center|MintHCM - Installation - License]]
-<syntaxhighlight lang="bash">
-sudo crontab -e -u www-data (or another actual user)
-</syntaxhighlight>
-Now you have to '''add the following line''' to the crontab file:
-<syntaxhighlight lang="bash">
-*    *    *    *    *     cd /var/www/MintHCM/MintHCM; php -f cron.php > /dev/null 2>&1
-</syntaxhighlight>
-Information about Crontab edition may be also found in Schedulers in [[Process:Administration_Guide|Administration panel]] of MintHCM after installation.
+'''3. In a moment another screen with system environment information will appear.'''
-Note that Windows or other systems have different background processes mechanisms.
+[[File:MintHCM4 - Installation - System Environment.png|900px|thumb|center|MintHCM - Installation - System Environment]]
-. Enter basic database configuration and administrator user data on the next screen.
+'''4. Enter basic database configuration and administrator user data on the next screen.'''
 If the database and MintHCM '''are on the same server, enter 'localhost'''' in the Host Name field.
 If the database is on a '''different server, enter the hostname or IP address''' of the database server in the Host Name field.
-[[File:minthcm detabase configuration.png|900px|thumb|center|MintHCM - Installation - Database configuration]]
+[[File:MintHCM4 - Installation - Database configuration.png|900px|thumb|center|MintHCM - Installation - Database configuration]]
 MintHCM Database User is by default set to root. If you want to choose another user, change it here.
-. Set up your administrator user name and password, so you can log in MintHCM later.
+'''5. Set up your ElasticSearch connection. System needs it to displays data in list and in [[Global Search]].'''
+[[File:MintHCM4 - Installation - ElasticSearch.png|900px|thumb|center|MintHCM - Installation - ElasticSearch configuration]]
-Here, you can '''configure basic global settings''' such as email server settings, branding (including logo of your company), system settings (i.e. time and data format) and security options.
+'''6. Set up your administrator user name and password, so you can log in MintHCM later.'''
-All of those settings may be configured after the installation as well.
-. If everything was alright with data provided, installation will begin. '''It may take a while.
+You have to provide Site URL. Usually in SiteURL field you should enter URL from your current browser tab to the „#” sign (characters after the „#” sign should not be entered).
-'''
+Here, you can check '''dummy data'''. The option will install Demo Data on instance. It can be helpfull if you do not want empty system.
-[[File:MintHCM - Installation - Installation in progress.png|900px|thumb|center|MintHCM - Installation - Installation in progress]]
-. After installation is completed, you will see the last screen. Among others, it provides information of total time of installation and memory use.
+[[File:MintHCM4 - Installation - Site configuration.png|900px|thumb|center|MintHCM - Installation - Site configuration]]
-[[File:MintHCM - Installation - Finish.png|900px|thumb|center|MintHCM - Installation - Finish]]
+'''7. If everything was alright with data provided, installation will begin. It may take a while'''
-After clicking the finish button, t'''he installation is complete''' and you can log in to your MintHCM instance as an administrator with the username and password you set up earlier.
+[[File:MintHCM4 - Installation - Processing.png|900px|thumb|center|MintHCM - Installation - Installation in progress]]
-==Troubleshooting==
+'''8. After installation is completed, you will see the last screen. Among others, it provides information of total time of installation and memory use.'''
-Here you can find instructions on troubleshooting common errors that may occur during the installation process of MintHCM software. It includes solutions for errors such as permission errors, invalid database host/username/password, and missing config.php file.
+[[File:MintHCM4 - Installation - Finish.png|900px|thumb|center|MintHCM - Installation - Finish]]
-If you can't find your problem below, '''check out our support forum''' here: https://minthcm.org/support/
+After clicking the button ''Go to login'', '''the installation is complete''' and you can log in to your MintHCM instance as an administrator with the username and password you set up earlier.
-You may also describe your problem and '''get help by sending an email''' to contact@minthcm.org
-===Permissions error===
+'''9. Adding crontab'''
-[[File:MintHCM - Installation  - Permissions error.png|900px|thumb|center|Permissions error]]
+It's important to set up a '''Crontab''' to allow MintHCM to run background tasks on your server.
+It's necessary in order to index data to ElasticSearch.
+Edit your web server user's crontab file after the installation is completed.
-This may occur, when files permissions were not change before the installation. '''Check your file permissions''' in MintHCM installation files directory, if necessary run commends provided below and start installation again.
+To do so, you have to '''edit your web server user's crontab file'''. You can open it with a command:
 <syntaxhighlight lang="bash">
-sudo chown -R www-data:www-data *
+sudo crontab -e -u www-data (or another actual user)
-sudo chmod -R 755 *
 </syntaxhighlight>
+Now you have to '''add the following line''' to the crontab file:
-or if this will not work, try:
 <syntaxhighlight lang="bash">
-sudo chown -R www-data:www-data .
+*    *    *    *    *     cd /var/www/<dir_to_your_instance>/legacy; php -f cron.php > /dev/null 2>&1
-sudo chmod -R 755 .
 </syntaxhighlight>
-===Database could not be established===
+Information about Crontab edition may be also found in Schedulers in [[Process:Administration_Guide|Administration panel]] of MintHCM after installation.
-"The provided database host, username, and/or password is invalid, and a connection to the database could not be established. Please enter a valid host, username and password"
+Note that Windows or other systems have different background processes mechanisms.
-[[File:Database Configuration.png]]
+==Troubleshooting==
-This error is most probably caused by invalid data provided by user, such as database host name or password. To solve this, '''double check your host, user name, password, etc.''' Also, check if your MintHCM Database user matches the actual user you can and want to use in this instance of MintHCM.
-===Config.php file is missing===
-[[File:MintHCM - Installation - Config.php error.png|900px|thumb|center|MintHCM - Installation - Config.php error]]
-This error may also be caused by file permission restrictions. '''Check the file permissions''' in the MintHCM installation files directory and '''restart the installation if necessary'''. You can also create config.php file manually.
-To do so, just create config.php file in your MintHCM instance directory, paste the code form the installer and save the file. After that, you can go to your instance (i.e. through URL https://my-server-or-domain.com/my-minthcm-directory). The instance should be running and you should see basic configuration options after logging in.
-===Specified key was too long; max key length is 1000 bytes===
-'''Cause'''
-There is a known bug with MySQL related to MyISAM, the UTF8 character set and indexes that you can check here.
-'''Resolution'''
-* Make sure MySQL is configured with the InnoDB storage engine.
-* Change the storage engine used by default so that new tables will always be created appropriately:
-<syntaxhighlight lang="sql">
-set GLOBAL storage_engine='InnoDb';
-</syntaxhighlight>
-* For MySQL 5.6 and later, use the following:
-<syntaxhighlight lang="sql">
-SET GLOBAL default_storage_engine = 'InnoDB';
-</syntaxhighlight>
-===System displays Warnings and Notices===
-You have to disable displaying errors in php settings (php.ini).
-Usually the file is located ''/etc/php7.X/fpm/php.ini''
-You can also check the location in phpinfo.
-You have to change line:
-<syntaxhighlight lang="bash">
-display_errors = Off
-</syntaxhighlight>
-After that, restart php.
+[[Process:Installation_guide#Troubleshooting|Troubleshooting MintHCM3]]
 {{Process-links}}