macOS Setup Guide

Complete installation and configuration guide for macOS systems

Prerequisites

Before installing ManageX on macOS, ensure you have:

  • macOS 10.15 (Catalina) or later
  • Administrator privileges
  • At least 4GB of RAM (8GB recommended)
  • 2GB of free disk space
  • Internet connection for downloading dependencies
  • Xcode Command Line Tools (will be installed automatically)

Step 1: Install Homebrew

1

Install Homebrew

Homebrew is the recommended package manager for macOS. Install it by running: 

/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

What is Homebrew?

Homebrew is a free and open-source software package management system that simplifies the installation of software on macOS.

2

Add Homebrew to PATH

Add Homebrew to your shell profile:

# For Intel Macs
echo 'eval "$(/usr/local/bin/brew shellenv)"' >> ~/.zprofile
eval "$(/usr/local/bin/brew shellenv)"

# For Apple Silicon Macs (M1/M2/M3)
echo 'eval "$(/opt/homebrew/bin/brew shellenv)"' >> ~/.zprofile
eval "$(/opt/homebrew/bin/brew shellenv)"
3

Verify Homebrew Installation

brew --version

Step 2: Install Node.js

1

Install Node.js via Homebrew

brew install node
2

Verify Installation

node --version
npm --version

You should see Node.js version 18.x or higher and npm version 8.x or higher.

Note

ManageX requires Node.js 16 or higher. Node 18+ is recommended for better performance and security.

1

Download Official Installer

Visit https://nodejs.org and download the macOS installer (.pkg file)

Download the LTS version (Long Term Support) which is recommended for production use.

2

Run the Installer

Double-click the downloaded .pkg file and follow the installation wizard

  • Accept the license agreement
  • Choose the default installation path
  • Install npm package manager (included by default)
3

Verify Installation

node --version
npm --version
1

Install NVM (Node Version Manager)

curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.0/install.sh | bash
2

Reload Shell Configuration

source ~/.zshrc

Or restart your terminal.

3

Install Node.js 18+

nvm install 18
nvm use 18
nvm alias default 18

Note

You can install any Node.js version 16 or higher. Version 18+ is recommended.

Step 3: Install MySQL

1

Install MySQL via Homebrew

brew install mysql
2

Start MySQL Service

brew services start mysql
3

Secure MySQL Installation

mysql_secure_installation

Follow the prompts to set root password and configure security options.

1

Download MySQL Installer

Visit https://dev.mysql.com/downloads/mysql/ and download the macOS installer (.dmg file)

Select "MySQL Community Server" and choose the macOS installer.

2

Install MySQL

Mount the .dmg file and run the installer package. Follow the installation wizard.

  • Choose "Developer Default" setup type
  • Set root password (remember this password!)
  • Configure MySQL as a service
4

Create Database

# Connect to MySQL
mysql -u root -p

# Create database
CREATE DATABASE managex_db;

# Create user (optional but recommended)
CREATE USER 'managex'@'localhost' IDENTIFIED BY 'your_password';
GRANT ALL PRIVILEGES ON managex_db.* TO 'managex'@'localhost';
FLUSH PRIVILEGES;
EXIT;

Step 4: Install ManageX Server

1

Navigate to Server Directory

cd /path/to/manage-x/server

Replace the path with your actual project location.

2

Install Dependencies

npm install

This will install all required Node.js packages including Express.js, Sequelize, JWT, and other dependencies.

3

Create Environment File

nano .env

Add the following configuration:

Example .env File

# NODE Configuration
PORT=3000     
NODE_ENV=development

# Database Configuration
DB_HOST=localhost
DB_NAME=managex_db
DB_USERNAME=root
DB_PASSWORD=your_password
DB_DIALECT=mysql

# JWT Configuration
JWT_SECRET=your-super-secret-jwt-key-change-in-production
JWT_REFRESH_SECRET=your-refresh-secret-key-change-in-production
JWT_EXPIRES_IN=24h
JWT_REFRESH_EXPIRES_IN=7d

# Demo Mode Configuration
IS_DEMO=0

Security Note

Change the JWT_SECRET and JWT_REFRESH_SECRET to strong, unique values in production. Use a password manager to generate secure secrets.

IS_DEMO Configuration

Set IS_DEMO=0 for production (runs only non-demo seeders) or IS_DEMO=1 for development/testing (runs all seeders including demo data). See the IS_DEMO Configuration section in the home page for more details.

4

Run Database Migrations

npm run db:migrate

This will create all necessary tables in your MySQL database.

5

Seed Initial Data

npm run demo

This will create default roles, users, organization, and configuration data. The IS_DEMO setting in your .env file determines whether demo seeders are included. See the home page documentation for details.

Note

The npm run demo command respects the IS_DEMO environment variable. For production, use IS_DEMO=0 to skip demo data.

6

Start the Server

npm run dev

You should see output indicating the server is running on port 3000 (or the port specified in your .env file).

Step 5: Access the Application

Open your web browser and navigate to:

http://localhost:3000

Default Login Credentials

Use these credentials to log in for the first time:

  • Email: superadmin@managex.com
  • Password: SuperAdmin@123

Important

Change the default password immediately after your first login for security reasons.

First Steps After Login

After logging in, you should:

  • Update your profile and password
  • Configure your organization settings
  • Set up additional users and roles as needed
  • Configure system settings according to your business needs

Step 6: Production Setup with PM2

1

Install PM2 Globally

npm install -g pm2
2

Create PM2 Configuration

Create ecosystem.config.js in the server directory: 

module.exports = {
  apps: [{
    name: 'managex-server',
    script: './bin/www',
    instances: 1,
    autorestart: true,
    watch: false,
    max_memory_restart: '1G',
    env: {
      NODE_ENV: 'production',
      PORT: 3000
    }
  }]
};
3

Start with PM2

pm2 start ecosystem.config.js
pm2 save
pm2 startup

The last command will generate a startup script. Follow the instructions it provides.

4

Useful PM2 Commands

# View running processes
pm2 list

# View logs
pm2 logs managex-server

# Restart application
pm2 restart managex-server

# Stop application
pm2 stop managex-server

# Monitor resources
pm2 monit

Troubleshooting

Quick Fixes

  • Permission denied: Use sudo for system-wide installations when necessary
  • Command not found: Check if Homebrew is in your PATH and restart terminal
  • Port already in use: Use lsof -i :3000 to find the process, then kill it with kill -9 <PID>
  • MySQL connection failed: Verify MySQL is running with brew services list | grep mysql
  • Node modules not found: Ensure you're in the correct directory and run npm install
  • Migration/Seeder errors: Ensure database exists, MySQL is running, and IS_DEMO is set correctly

Useful Commands

# Check Node.js version
node --version

# Check MySQL status
brew services list | grep mysql

# Check running processes
ps aux | grep node

# Check port usage
lsof -i :3000

# View PM2 logs
pm2 logs

# Reset Homebrew
brew doctor

Need More Help?

For detailed troubleshooting steps, common error solutions, and advanced diagnostics, see the Complete Troubleshooting Guide.