macOS Setup Guide

Complete installation and configuration guide for macOS systems

Prerequisites

Before installing POSTrack 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)
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
1

Download Official Installer

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

2

Run the Installer

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

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
3

Install Node.js 22

nvm install 22
nvm use 22
nvm alias default 22

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)

2

Install MySQL

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

4

Create Database

# Connect to MySQL
mysql -u root -p

# Create database
CREATE DATABASE postrack_db;

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

Step 4: Install POSTrack Server

1

Navigate to Server Directory

cd /path/to/inventory-manager/server
2

Install Dependencies

npm install
3

Create Environment File

nano .env

Add the following configuration:

# Database Configuration
            
DB_HOST=localhost
            
DB_PORT=3306
            
DB_NAME=postrack_db
            
DB_USERNAME=root
            
DB_PASSWORD=your_mysql_password
            
            

# JWT Configuration
            
JWT_SECRET=your-super-secure-jwt-secret-key-change-this-in-production
            
JWT_EXPIRES_IN=24h
            
            

# Server Configuration
            
PORT=3000
            
NODE_ENV=development
            
            

# CORS Configuration
            
ALLOWED_ORIGINS=http://localhost:5000,http://localhost:3000
            
            

# Rate Limiting
            
RATE_LIMIT_MAX=1000
            
AUTH_RATE_LIMIT_MAX=1000
            
API_RATE_LIMIT_MAX=1000
            
            

# Logging
            
LOG_LEVEL=info
4

Set Up Database

# Run migrations
npm run db:migrate

# Seed initial data
npm run db:seed
5

Start the Server

npm run dev

Step 5: Install POSTrack Client

1

Navigate to Client Directory

cd /path/to/inventory-manager/client
2

Install Dependencies

npm install
3

Configure API Endpoint

nano src/config/config.ts

Update the configuration:

export const baseUrl = "http://localhost:3000";
export const apiUrl = `${baseUrl}/api`;
4

Start the Client

npm run dev

Step 6: Access the Application

Open your web browser and navigate to:

http://localhost:5000

Default Login Credentials

Use these credentials to log in for the first time:

  • Email: admin@example.com
  • Password: admin123

Important

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

Step 7: 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: 'POSTrack-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

Troubleshooting

Common Issues

  • Permission denied: Use 
    sudo
    for system-wide installations
  • Command not found: Check if Homebrew is in your PATH
  • Port already in use: Use 
    lsof -i :3000
    to find the process
  • MySQL connection failed: Verify MySQL is running with 
    brew services list | grep mysql

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 logs
tail -f /path/to/inventory-manager/server/logs/combined.log

# Reset Homebrew
brew doctor

Getting Help

If you encounter issues not covered in this guide, check the Troubleshooting page for more detailed solutions.