Difference between revisions of "Process:Installation guide"

From MintHCM Wiki

(→‎Database could not be established)
 
(15 intermediate revisions by 3 users not shown)
Line 1: Line 1:
 
{{Process-infobox
 
{{Process-infobox
−
|Process-name=Installation guide
+
|Process-name=MintHCM Installation Guide
 
|Process-type=Technical Process
 
|Process-type=Technical Process
−
|Short Description=The MintHCM Installing Guide is a technical document that provides detailed instructions on how to install and configure the software.
+
|Related Processes=Installation guide MintHCM v3
 +
|Short Description=This guide covers the installation process for MintHCM version 4.x onwards.
 +
}}
 +
For instructions for previous releases please visit [[Process:Installation_guide_MintHCM_v3|MintHCM 3.x Installation Guide]].
 +
<br>
 +
For instructions for running on Docker please visit [[Process:Running_on_Docker|Deploy MintHCM on Docker]].
 +
==Requirements==
 +
Before installing MintHCM, ensure that your system meets the following requirements:
 +
* '''Web Server''':
 +
** Linux or Windows machine running Apache2
 +
* '''PHP''':
 +
** 7.4 - 8.0
 +
* '''Database''' (one of the following):
 +
** MySQL 5.7 or 8.0
 +
** Percona 8.0
 +
** MariaDB 10
 +
* '''ElasticSearch''':
 +
** 7.9
  
−
The guide covers everything from system requirements to database configuration and user setup.
+
<br>
−
It is a comprehensive technical resource that provides you with the information you need to set up and configure the software effectively.
+
===== Apache2 Configuration: =====
−
}}
+
* Required Modules: Rewrite and Headers
−
==Requirements==
+
* AllowOverride: Ensure that AllowOverride All is set within the <Directory> directive for MintHCM in your Apache configuration. This allows the use of .htaccess files for additional configuration.
−
To run MintHCM, your system must have '''PHP 7.1 and MySQL 5.6-5.7 or MariaDB 10 installed'''. Other versions are not supported!
+
For example:
 +
<pre>
 +
<VirtualHost *:80>
 +
    DocumentRoot /var/www/minthcm
 +
 
 +
    <Directory /var/www/minthcm>
 +
        Options Indexes FollowSymLinks
 +
        AllowOverride All
 +
        Require all granted
 +
    </Directory>
 +
 
 +
    # ... other configurations ...
  
−
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.
+
</VirtualHost>
 +
</pre>
 +
<br>
 +
===== Browser compatibility =====
 +
MintHCM offers a user-friendly interface accessible through the following web browsers:
 +
* Chromium
 +
* Firefox
 +
* Edge
 +
<br>
 +
While we strive to provide the best user experience on these browsers, Internet Explorer (IE) is not supported. However, you are welcome to test and use it at your discretion.
  
−
==Preparing for installation==
+
==Getting started==
  
−
To install MintHCM you will need Linux or Windows platform, a web server with PHP installed and a database.  
+
===== Download MintHCM =====
 +
Download the latest release of MintHCM zip file from the official website: https://minthcm.org/download/
 +
<br>
  
−
The first step towards installation is downloading MintHCM to your server and preparing files to be installed. To do so, follow the steps:
+
===== Copy the zip file to your server =====
 +
Copy the downloaded zip file to your server using your preferred method (e.g., SCP, FTP).
 +
<br>
  
−
# Download MintHCM zip file from https://minthcm.org/download/
+
===== Unzip the files =====
−
# Copy the zip file to your server
+
Navigate to the directory where you want to install MintHCM and unzip the downloaded file.
−
# 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:
 
 
<syntaxhighlight lang="bash">
 
<syntaxhighlight lang="bash">
−
cd ../<yourMintHCMdirectory>
+
cd /path/to/your/MintHCMdirectory
−
sudo chown -R www-data:www-data *
+
unzip MintHCM.zip
−
sudo chmod -R 755 *
+
</syntaxhighlight>
 +
 
 +
===== Change file permissions =====
 +
Adjust file permissions based on your platform's requirements. For Ubuntu Linux with Apache, use the following commands:
 +
<syntaxhighlight lang="bash">
 +
cd /path/to/your/MintHCMdirectory
 +
sudo chown -R www-data:www-data .
 +
sudo chmod -R 755 .
 
</syntaxhighlight>
 
</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.'''
+
Note: Replace www-data:www-data with the actual user and group on your server if they differ from Linux/Apache defaults. This ensures proper ownership and permissions for MintHCM files.
  
−
==Installation of MintHCM==
+
== Installation process ==
  
−
Once you have your files prepared, you can start actual installation. To do so, follow the steps below:
+
'''Open the Installation Wizard'''
  
−
1. Open your web browser and '''enter the following URL''' to start the installation wizard.
+
Open your web browser and enter the following URL to initiate the installation wizard:
  
 +
<syntaxhighlight lang="bash">
 
  https://my-server-or-domain.com/my-minthcm-directory
 
  https://my-server-or-domain.com/my-minthcm-directory
 +
</syntaxhighlight>
  
−
The installation wizard will start now.  
+
The installation wizard will commence automatically, guiding you through the setup process. Follow the on-screen instructions to configure MintHCM for your environment.
  
−
2. On the first screen you have to '''accept the licence agreement.''' After that you can click the next button.  
+
===== 1. Accept the License Agreement =====
 +
On the first screen, you need to accept the license agreement. After that, you can click the "Next" button.
  
−
[[File:MintHCM - Installation - Start.png|900px|thumb|center|MintHCM - Installation - Start]]
+
[[File:MintHCM Installation - License.png|900px|thumb|center|MintHCM - Installation - License]]
  
−
3. In a moment another screen with system environment information will appear.  
+
===== 2. System Environment Check =====
  
−
[[File:MintHCM - Installation - System Environment.png|900px|thumb|center|MintHCM - Installation - System Environment]]
+
[[File:MintHCM4 - 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.  
+
===== 3. Database Configuration =====
−
Edit your web server user's crontab file after the installation is completed.
+
On this screen, you'll provide essential database configuration details and administrator user data. Follow these steps:
  
−
To do so, you have to '''edit your web server user's crontab file'''. You can open it with a command:
+
'''Host Name:'''
−
<syntaxhighlight lang="bash">
+
* If the database and MintHCM are on the same server, enter 'localhost' in the Host Name field.
−
sudo crontab -e -u www-data (or another actual user)
+
* If the database is on a different server, enter the hostname or IP address of the database server in the Host Name field.
−
</syntaxhighlight>
+
<br>
−
Now you have to '''add the following line''' to the crontab file:
+
'''Database User:'''
−
<syntaxhighlight lang="bash">
+
* The MintHCM Database User is set to 'root' by default. If you prefer to use another user, update this field accordingly.
−
*    *    *    *    *    cd /var/www/MintHCM/MintHCM; php -f cron.php > /dev/null 2>&1
+
<br>
−
</syntaxhighlight>
+
'''Note:'''
 +
* If you are unsure about the database server's hostname or IP address, consult your server administrator or hosting provider.
 +
* Choosing a secure and unique Database User is recommended for enhanced security.
 +
 
 +
[[File:MintHCM4 - Installation - Database configuration.png|900px|thumb|center|MintHCM - Installation - Database configuration]]
  
−
Information about Crontab edition may be also found in Schedulers in [[Process:Administration_Guide|Administration panel]] of MintHCM after installation.
+
Once you've entered the necessary information, proceed to the next step in the installation process.
  
−
Note that Windows or other systems have different background processes mechanisms.  
+
===== 4. ElasticSearch Connection =====
  
−
4. Enter basic database configuration and administrator user data on the next screen.
+
Configure your ElasticSearch connection (make sure that it's running) to enable MintHCM to display data in lists and in the Global Search feature.
  
−
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 - ElasticSearch.png|900px|thumb|center|MintHCM - Installation - ElasticSearch configuration]]
  
−
MintHCM Database User is by default set to root. If you want to choose another user, change it here.  
+
===== 5. Site Configuration =====
  
−
5. Set up your administrator user name and password, so you can log in MintHCM later.
+
* SiteURL (Optional):
 +
** Optionally, you can change the prefilled SiteURL field if you decide to run MintHCM in a custom directory. This is useful if MintHCM is not installed in the root directory of your web server.
 +
* Create a username and password for your administrator account.
 +
* Populate with Dummy Data (Optional):
 +
** Decide whether you want your Mint installation to be populated with dummy data for demonstration purposes. This can be helpful for testing and exploring MintHCM features.
  
−
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.
+
[[File:MintHCM4 - Installation - Site configuration.png|900px|thumb|center|MintHCM - Installation - Site configuration]]
−
All of those settings may be configured after the installation as well.  
 
  
−
6. If everything was alright with data provided, installation will begin. '''It may take a while.
+
After configuring the administrator username and password, proceed to the next step in the installation process.
−
'''
 
−
[[File:MintHCM - Installation - Installation in progress.png|900px|thumb|center|MintHCM - Installation - Installation in progress]]
 
  
−
7. After installation is completed, you will see the last screen. Among others, it provides information of total time of installation and memory use.  
+
===== 6. Installation =====
  
−
[[File:MintHCM - Installation - Finish.png|900px|thumb|center|MintHCM - Installation - Finish]]
+
If all the provided data is correct, the installation process will begin. Please be patient as this may take a few minutes.
  
−
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.
+
Note:
 +
* During this phase, MintHCM is configuring and setting up the necessary components. The duration may vary based on server resources and network conditions.
 +
* Avoid interrupting the installation process to ensure a successful setup.
  
−
==Troubleshooting==
+
[[File:MintHCM4 - Installation - Processing.png|900px|thumb|center|MintHCM - Installation - Installation in progress]]
  
−
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.  
+
Once the installation is completed, you will proceed to the next step in the process.
  
−
If you can't find your problem below, '''check out our support forum''' here: https://minthcm.org/support/
+
===== 7. Completion =====
−
You may also describe your problem and '''get help by sending an email''' to contact@minthcm.org
+
The installation is now complete, and you can log in as an administrator using the username and password you set up earlier.
  
−
===Permissions error===
+
[[File:MintHCM4 - Installation - Finish.png|900px|thumb|center|MintHCM - Installation - Finish]]
  
−
[[File:MintHCM - Installation  - Permissions error.png|900px|thumb|center|Permissions error]]
+
===== 8. Adding Crontab for MintHCM =====
 +
After completing the installation, it's crucial to set up a Crontab to enable MintHCM to run background tasks, especially for indexing data to ElasticSearch. Follow these steps to add a Crontab entry:
  
−
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.
+
* Open the Crontab Editor:
 
<syntaxhighlight lang="bash">
 
<syntaxhighlight lang="bash">
−
sudo chown -R www-data:www-data *
+
sudo crontab -e -u www-data # Use the actual user if not www-data
−
sudo chmod -R 755 *
 
 
</syntaxhighlight>
 
</syntaxhighlight>
  
−
or if this will not work, try:
+
* Add the Crontab Entry:
−
 
 
 
<syntaxhighlight lang="bash">
 
<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>
 
</syntaxhighlight>
 +
This line schedules the execution of the MintHCM background tasks every minute.
  
−
===Database could not be established===
+
* Note:
 +
** Adjust the path /var/www/<dir_to_your_instance>/legacy to the actual path where your MintHCM instance is installed.
 +
** Ensure that the user specified (e.g., www-data) has the necessary permissions to execute the Crontab entry.
 +
After adding the Crontab entry, MintHCM will automatically run background tasks, including data indexing to ElasticSearch.
  
−
"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"
+
* Additional Information:
  
−
[[File:Database Configuration.png]]
+
** You can find information about Crontab setup in the Schedulers section of the [[Process:Administration_Guide|Administration panel]] within MintHCM after installation.
  
−
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.
+
* Note for Windows or Other Systems:
  
−
===Config.php file is missing===
+
** Windows and other operating systems may have different mechanisms for managing background processes. Refer to the respective documentation for your system.
  
−
[[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.
+
==Troubleshooting==
−
 
 
−
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}}
 
{{Process-links}}

Latest revision as of 14:37, 21 December 2023

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

Short Description

This guide covers the installation process for MintHCM version 4.x onwards.


For instructions for previous releases please visit MintHCM 3.x Installation Guide.
For instructions for running on Docker please visit Deploy MintHCM on Docker.

Requirements

Before installing MintHCM, ensure that your system meets the following requirements:

  • Web Server:
    • Linux or Windows machine running Apache2
  • PHP:
    • 7.4 - 8.0
  • Database (one of the following):
    • MySQL 5.7 or 8.0
    • Percona 8.0
    • MariaDB 10
  • ElasticSearch:
    • 7.9


Apache2 Configuration:
  • Required Modules: Rewrite and Headers
  • AllowOverride: Ensure that AllowOverride All is set within the <Directory> directive for MintHCM in your Apache configuration. This allows the use of .htaccess files for additional configuration.

For example: 

<VirtualHost *:80>
    DocumentRoot /var/www/minthcm

    <Directory /var/www/minthcm>
        Options Indexes FollowSymLinks
        AllowOverride All
        Require all granted
    </Directory>

    # ... other configurations ...

</VirtualHost>


Browser compatibility

MintHCM offers a user-friendly interface accessible through the following web browsers:

  • Chromium
  • Firefox
  • Edge


While we strive to provide the best user experience on these browsers, Internet Explorer (IE) is not supported. However, you are welcome to test and use it at your discretion.

Getting started

Download MintHCM

Download the latest release of MintHCM zip file from the official website: https://minthcm.org/download/

Copy the zip file to your server

Copy the downloaded zip file to your server using your preferred method (e.g., SCP, FTP).

Unzip the files

Navigate to the directory where you want to install MintHCM and unzip the downloaded file. 

cd /path/to/your/MintHCMdirectory
unzip MintHCM.zip
Change file permissions

Adjust file permissions based on your platform's requirements. For Ubuntu Linux with Apache, use the following commands: 

cd /path/to/your/MintHCMdirectory
sudo chown -R www-data:www-data .
sudo chmod -R 755 .

Note: Replace www-data:www-data with the actual user and group on your server if they differ from Linux/Apache defaults. This ensures proper ownership and permissions for MintHCM files.

Installation process

Open the Installation Wizard

Open your web browser and enter the following URL to initiate the installation wizard: 

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

The installation wizard will commence automatically, guiding you through the setup process. Follow the on-screen instructions to configure MintHCM for your environment.

1. Accept the License Agreement

On the first screen, you need to accept the license agreement. After that, you can click the "Next" button.

MintHCM - Installation - License
2. System Environment Check
MintHCM - Installation - System Environment
3. Database Configuration

On this screen, you'll provide essential database configuration details and administrator user data. Follow these steps:

Host Name:

  • 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.


Database User:

  • The MintHCM Database User is set to 'root' by default. If you prefer to use another user, update this field accordingly.


Note:

  • If you are unsure about the database server's hostname or IP address, consult your server administrator or hosting provider.
  • Choosing a secure and unique Database User is recommended for enhanced security.
MintHCM - Installation - Database configuration

Once you've entered the necessary information, proceed to the next step in the installation process.

4. ElasticSearch Connection

Configure your ElasticSearch connection (make sure that it's running) to enable MintHCM to display data in lists and in the Global Search feature.


MintHCM - Installation - ElasticSearch configuration
5. Site Configuration
  • SiteURL (Optional):
    • Optionally, you can change the prefilled SiteURL field if you decide to run MintHCM in a custom directory. This is useful if MintHCM is not installed in the root directory of your web server.
  • Create a username and password for your administrator account.
  • Populate with Dummy Data (Optional):
    • Decide whether you want your Mint installation to be populated with dummy data for demonstration purposes. This can be helpful for testing and exploring MintHCM features.
MintHCM - Installation - Site configuration

After configuring the administrator username and password, proceed to the next step in the installation process.

6. Installation

If all the provided data is correct, the installation process will begin. Please be patient as this may take a few minutes.

Note:

  • During this phase, MintHCM is configuring and setting up the necessary components. The duration may vary based on server resources and network conditions.
  • Avoid interrupting the installation process to ensure a successful setup.
MintHCM - Installation - Installation in progress

Once the installation is completed, you will proceed to the next step in the process.

7. Completion

The installation is now complete, and you can log in as an administrator using the username and password you set up earlier.

MintHCM - Installation - Finish
8. Adding Crontab for MintHCM

After completing the installation, it's crucial to set up a Crontab to enable MintHCM to run background tasks, especially for indexing data to ElasticSearch. Follow these steps to add a Crontab entry:

  • Open the Crontab Editor:
sudo crontab -e -u www-data  # Use the actual user if not www-data
  • Add the Crontab Entry:
*    *    *    *    *     cd /var/www/<dir_to_your_instance>/legacy; php -f cron.php > /dev/null 2>&1

This line schedules the execution of the MintHCM background tasks every minute.

  • Note:
    • Adjust the path /var/www/<dir_to_your_instance>/legacy to the actual path where your MintHCM instance is installed.
    • Ensure that the user specified (e.g., www-data) has the necessary permissions to execute the Crontab entry.

After adding the Crontab entry, MintHCM will automatically run background tasks, including data indexing to ElasticSearch.

  • Additional Information:
    • You can find information about Crontab setup in the Schedulers section of the Administration panel within MintHCM after installation.
  • Note for Windows or Other Systems:
    • Windows and other operating systems may have different mechanisms for managing background processes. Refer to the respective documentation for your system.


Troubleshooting

Troubleshooting MintHCM3

Mentioned in other articles

Retrieved from "https://wiki.minthcm.org/index.php?title=Process:Installation_guide&oldid=6281"