MintHCM on AWS User Guide

Overview

MintHCM is a free open source Human Capital Management and HR platform built on the proven SuiteCRM and SugarCRM lineage. It manages employee records, organisational structure and positions, recruitment and candidates, time off and leave, timesheets, projects and HR reporting from a single self-hosted application, giving an organisation full ownership of its HR data.

This image runs MintHCM as a self-contained appliance on the instance: an Apache and PHP 8.2 application container serving the MintHCM code on port 80, a Percona Server 8.0 database, and an internal Elasticsearch index that powers list views and Global Search. The three services are orchestrated with Docker Compose and start automatically on boot.

The image ships with no installed application and no credentials. On the first boot of every deployed instance a one-shot service generates a fresh administrator password, a fresh database password and a fresh site secret, runs the MintHCM installation headlessly with those secrets, sets the site URL to the instance address, and writes the administrator password to /root/minthcm-credentials.txt with mode 0600 so that only the root user can read it. Two instances launched from the same Amazon Machine Image never share credentials, and the stock default password never exists on any launched instance. The Elasticsearch index is bound to the loopback interface only.

The MintHCM application version is pinned into the image, so every instance installs the same release offline with no dependency on external download servers. The Percona data directory lives on a dedicated EBS volume at /var/lib/minthcm/db, and the Elasticsearch index and application state on a second dedicated EBS volume at /var/lib/minthcm/app, each separate from the operating system disk and independently resizable.

Prerequisites

Before you deploy this image you need:

• An Amazon Web Services account where you can launch EC2 instances
• IAM permissions to launch instances, create security groups, and subscribe to AWS Marketplace products
• An EC2 key pair in the target Region for SSH access to the instance
• A VPC and subnet in the target Region, with a security group allowing inbound port 22 from your management network and inbound ports 80 and 443 from the networks your HR users will reach MintHCM on
• The AWS CLI (version 2) installed locally if you plan to deploy from the command line

Connecting to your instance

Connect over SSH as the default login user for your operating system variant. MintHCM is served on port 80.

Step 1: Launch the Instance from the AWS Marketplace

Sign in to the AWS Management Console, open the EC2 service, and select Launch instance. Under Application and OS Images choose AWS Marketplace AMIs and search for MintHCM. Select the cloudimg listing and choose Select, then Continue on the subscription summary.

Pick an instance type of m5.large or larger. MintHCM runs a PHP application, a database and an Elasticsearch index together on the instance, so memory matters; m5.large (8 GiB) is the recommended minimum. Choose your EC2 key pair under Key pair (login). Under Network settings select your VPC and subnet, and either create or select a security group that allows inbound port 22 from your management network and inbound ports 80 and 443 from the networks your HR users use. Leave the root volume at the default size or larger.

Select Launch instance. First boot performs the MintHCM installation, which takes a few minutes after the instance state becomes Running and the status checks pass. Once complete, the sign-in page is served on port 80.

Step 2: Launch the Instance from the AWS CLI

The following block launches an instance from the cloudimg MintHCM Marketplace AMI into an existing subnet and security group. Replace <ami-id> with the AMI ID shown on the Marketplace listing, <key-name> with your EC2 key pair name, <subnet-id> with your subnet ID, and <security-group-id> with a security group that opens ports 22, 80, and 443 as described above.

aws ec2 run-instances \
  --image-id <ami-id> \
  --instance-type m5.large \
  --key-name <key-name> \
  --subnet-id <subnet-id> \
  --security-group-ids <security-group-id> \
  --block-device-mappings '[{"DeviceName":"/dev/sda1","Ebs":{"VolumeSize":40,"VolumeType":"gp3"}}]' \
  --metadata-options 'HttpTokens=required,HttpEndpoint=enabled' \
  --tag-specifications 'ResourceType=instance,Tags=[{Key=Name,Value=minthcm}]'

Step 3: Connect and Retrieve Initial Credentials

Connect over SSH as ubuntu, using your key pair and the instance's public IP:

ssh -i /path/to/your-key.pem ubuntu@your-instance-public-ip

Then read the per-instance credentials file. It is created on first boot with mode 0600, readable only by root:

sudo cat /root/minthcm-credentials.txt

The file lists the generated administrator and database credentials for this instance:

minthcm.url=http://<instance-public-ip>/
minthcm.admin.user=admin
minthcm.admin.pass=<generated-per-instance>
minthcm.db.user=root
minthcm.db.pass=<generated-per-instance>

If the file still shows a placeholder note, first boot has not finished the installation yet; wait a minute and read it again.

Step 4: Verify the Stack is Running

The appliance runs as three Docker containers managed by Docker Compose. Confirm they are up:

sudo docker ps --format 'table {{.Names}}\t{{.Image}}\t{{.Status}}'

NAMES                   IMAGE                                                  STATUS
minthcm-minthcm-web-1   minthcm/minthcm:latest                                 Up 38 minutes
minthcm-minthcm-db-1    percona/percona-server:8.0                             Up 38 minutes (healthy)
minthcm-minthcm-es-1    docker.elastic.co/elasticsearch/elasticsearch:7.16.3   Up 38 minutes

Confirm the web application answers on port 80:

curl -I http://127.0.0.1/

HTTP/1.1 200 OK
Server: Apache/2.4.58 (Ubuntu)

Step 5: First Sign-in

Browse to http://<instance-public-ip>/ and sign in with the admin username and the password from /root/minthcm-credentials.txt.

For production use, put MintHCM behind HTTPS (Step 9) before signing in over the public internet, so the credentials are never sent in clear text.

Step 6: Managing Employees, Candidates and Positions

MintHCM organises its HR data into modules reached from the top navigation: Employees, Candidates, Positions, Organizational Units, Leave, Timesheets and more. Each record carries contact details, related documents, meetings, tasks and org-structure relationships. The screenshot below shows a candidate record with its contact information and related panels.

Positions describe your organisational structure — each position has a status, a supervised unit and relationships to the employees who hold it.

Step 7: Administration

Open the Administration panel to manage users and roles, configure OAuth2 clients, define organisational units, and set system-wide options such as locale, languages, currencies and search.

Create a named user account for each HR team member under User Management rather than sharing the administrator login, and assign roles to control which modules and records each user can see.

Step 8: Change the Administrator Password

The administrator password is generated per instance. To change it, sign in as admin, open Administration → User Management, select the admin user, choose Edit, and set a new password under the password fields. Store the new password securely; the file at /root/minthcm-credentials.txt records only the original generated password.

Step 9: Enable HTTPS

For production use, terminate TLS in front of MintHCM. The simplest approach is to place the instance behind an AWS Application Load Balancer with an ACM certificate, forwarding HTTPS on 443 to the instance on port 80 within your VPC. Alternatively, install a reverse proxy such as nginx or Caddy on the instance with a Let's Encrypt certificate for your domain, proxying to http://127.0.0.1:80. After putting MintHCM behind HTTPS, update the site URL in Administration → System Settings to the https:// address so generated links use HTTPS.

Step 10: Storage Layout

The database and the search index each live on their own dedicated EBS volume, separate from the operating system disk, so each tier can be resized independently:

df -h /var/lib/minthcm/db /var/lib/minthcm/app

Filesystem      Size  Used Avail Use% Mounted on
/dev/nvme1n1     20G  305M   19G   2% /var/lib/minthcm/db
/dev/nvme2n1     20G   49M   19G   1% /var/lib/minthcm/app

To grow a tier, expand the corresponding EBS volume in the EC2 console, then grow the filesystem on the instance with resize2fs.

Step 11: Backups and Maintenance

Back up the database with a logical dump from the Percona container, and snapshot the two data volumes for a full point-in-time copy:

# Logical database dump
DBPASS=$(sudo grep '^DB_PASS=' /opt/minthcm/.env | cut -d= -f2-)
sudo docker exec minthcm-minthcm-db-1 sh -c "mysqldump -uroot -p'$DBPASS' minthcm" > minthcm-backup.sql

For a full copy, take EBS snapshots of the /var/lib/minthcm/db and /var/lib/minthcm/app volumes. The appliance containers restart automatically on reboot; to restart them manually run cd /opt/minthcm && sudo docker compose restart.

Screenshots

MintHCM sign-in:

A candidate record:

The administration panel:

A position record:

Support

This image is published by cloudimg with 24/7 technical support by email and chat. We can help with MintHCM deployment, upgrades, HR module configuration, recruitment and leave workflows, Elasticsearch indexing, email, and database administration. MintHCM is licensed under the GNU Affero General Public License version 3 (AGPL-3.0) and is shipped unmodified.