MintCHM

MintHCM

Is an open-source software, which means it is freely available for download and installation on your own server.

Human Capital Management

It encompasses a comprehensive set of practices for the recruitment, management, and administrative aspects of human resources processes, often also referred to as Human Resources Management (HRM).

Purpose

The purpose of this wiki entry is to provide an example on integrating NGINX with MintHCM, ensuring a seamless and efficient setup.

This article assumes the following:

• NGINX has been installed
• Your NGINX default site is configured for your needs.
• MintHCM has already been installed and configured in your web directory on the server.

Additional Notes

• This setup is compatible with both Peppermint (based on Debian or Devuan) and can be applied to Debian or Devuan directly, with the only variation being the init systems used by each distribution. The steps outlined here are universally applicable, making it a versatile solution for all these platforms.

• By default, MintHCM is documented to use Apache, primarily due to its reliance on the .htaccess feature. The '.htaccess file is a configuration file used by Apache-based web servers to manage and customize the behavior of the server at a directory level.

• NGINX does not have a direct equivalent to Apache's .htaccess files. To achieve similar functionality, you need to set the NGINX configuration directives. This involves placing them within the server or location blocks of the NGINX configuration file.

Configure NGINX

On Peppermint, which is based on Debian or Devuan, the NGINX configuration files are typically located in the following directories:

• Main Configuration File: Usually found at /etc/nginx/nginx.conf
• Site Configuration Files: Often located in /etc/nginx/sites-available/ and symlinked to /etc/nginx/sites-enabled/
• Other Configuration Files: Additional configuration files might be found in /etc/nginx/conf.d/

For these steps you only need to work with the sites-available In many NGINX installations, a default configuration file is provided in the sites-available directory, often named default. This file serves as a template or example configuration.

A common best practice is to define your standard server block settings in the default configuration file and then include separate .conf files for specific locations or sites. This approach keeps your configuration organized and allows you to reuse common settings across multiple server blocks.

To get MinCHM working NGINX:

1. Create a file named mintchm.conf touch /etc/nginx/sites-available/mintchm.conf
2. Use your preferred text-editor to edit the mintchm.conf nano /etc/nginx/sites-available/mintchm.conf

Now you can add these entries in to the mintchm.conf This is heavily commented for explanation they can be removed as needed

# Define a location block for the /mintchm URI
location /mintchm {
    # Set the alias to the directory where the MintCHM application files are located
    alias /var/www/html/mintchm;

    # Specify the default index file to serve
    index index.php;

    # Try to serve the requested URI, or fallback to index.php if not found
    try_files $uri $uri/ /mintchm/index.php$is_args$args;

    # Handle PHP files specifically within this location
    location ~ \.php$ {
        # Pass PHP requests to the PHP FastCGI Process Manager (FPM) via a Unix socket
        # Here you can see I am using 8.2
        fastcgi_pass unix:/run/php/php8.2-fpm.sock;
        
        # Specify the default index file for FastCGI
        fastcgi_index index.php;

        # Include standard FastCGI parameters
        include fastcgi_params;

        # Set the SCRIPT_FILENAME parameter for PHP processing
        fastcgi_param SCRIPT_FILENAME $request_filename;

        # Set PHP configuration values for file uploads
        fastcgi_param PHP_VALUE "upload_max_filesize=6M \n post_max_size=8M";
    }

    # Static file handling for common file types (images, CSS, JS, etc.)
    location ~* \.(jpg|jpeg|gif|png|css|js|ico|xml)$ {
        # Disable access logging for these file types
        access_log off;

        # Disable logging of not found errors for these file types
        log_not_found off;

        # Set caching expiration for these files to 360 days
        expires 360d;
    }

    # Deny access to specific MintCHM API and asset paths
    # Return a 403 error if tried
    location ^~ /mintchm/api/ {
        deny all;
        return 403;
    }

    location ^~ /mintchm/assets/ {
        deny all;  
        return 403;
    }

    location ^~ /mintchm/kanban/ {
        deny all;  
        return 403;  
    }

    location ^~ /mintchm/legacy/ {
        deny all;  
        return 403;
    }

    location ^~ /mintchm/vue/ {
        deny all;  
        return 403;
    }
}

Explanation of what we are doing

Location Block for /mintchm

• Purpose: This block defines how requests to the /mintchm path should be handled.
• Alias: The alias directive points to the actual directory where the MintCHM application files are stored (/var/www/html/mintchm).
• Index File: The index directive specifies that index.php should be served as the default file when a directory is accessed.

File Handling Logic with try_files

• Try Files: The try_files directive attempts to serve the requested URI directly. If that fails, it tries appending a trailing slash and finally falls back to serving index.php, passing any query string arguments ($is_args$args) along

PHP Processing Block

• PHP Requests: The nested location ~ \.php$ block handles requests for PHP files.
• FastCGI Configuration: It uses fastcgi_pass to route requests through PHP-FPM, specifying the socket used for communication.
• Parameters: It includes standard FastCGI parameters and sets specific parameters like SCRIPT_FILENAME, which tells PHP which file to execute. It also configures upload limits.

Static File Handling

• Caching Strategy: The block for static files (images, CSS, JavaScript) disables logging and sets an expiration time of 360 days, which helps improve performance by allowing browsers to cache these assets. You can change that time to what ever if best for your environment.

Security Measures

• Deny Access: Several locations are explicitly denied access (e.g., /mintchm/api/, /mintchm/assets/). This is a security measure to prevent unauthorized access to sensitive parts of the application.