macOS Setup Guide

Complete installation and configuration guide for macOS systems

Prerequisites

Before installing InveTrack 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 invetrack_db; # Create user (optional but recommended) CREATE USER 'invetrack'@'localhost' IDENTIFIED BY 'your_password'; GRANT ALL PRIVILEGES ON invetrack_db.* TO 'invetrack'@'localhost'; FLUSH PRIVILEGES; EXIT;

Step 4: Install InveTrack 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=invetrack_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

# OpenAI Configuration (Optional - for AI-powered reports)
# OPENAI_MODEL=gpt-4o-mini

AI Features

The OpenAI API key is configured through the application settings after login, not in the .env file. The OPENAI_MODEL variable is optional and defaults to 'gpt-4o-mini' if not specified.

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: Configure OpenAI API Key (Optional)

InveTrack includes AI-powered features that generate intelligent reports and insights. To enable these features, you need to configure an OpenAI API key.

AI Features Available

With OpenAI API key configured, you can access:

  • Demand Forecasting: AI-powered predictions for inventory demand
  • Price Optimization: Intelligent pricing recommendations to maximize revenue
  • Product Performance Analysis: AI-generated insights on product trends
  • Cross-sell Recommendations: Suggestions for complementary products
  • Slow Moving Products: AI analysis of inventory that needs attention
  • Stockout Impact Analysis: Predictions on the impact of stockouts
1

Get Your OpenAI API Key

If you don't have an OpenAI API key yet, follow these steps:

  1. Visit https://platform.openai.com
  2. Sign up for an account or log in if you already have one
  3. Navigate to API Keys section in your account settings
  4. Click "Create new secret key"
  5. Give your key a name (e.g., "InveTrack Production")
  6. Copy the API key immediately (you won't be able to see it again)

Important

Keep your API key secure and never share it publicly. OpenAI charges based on usage, so monitor your API usage regularly.

2

Configure API Key in InveTrack

After completing the client setup and logging into the application:

  1. Log in to InveTrack using the default admin credentials
  2. Navigate to Settings from the main menu
  3. Look for the "OpenAI API Key" or "AI Configuration" section
  4. Paste your OpenAI API key into the designated field
  5. Click "Save" to store the configuration

Note

The API key is stored securely in the database and is associated with your company. Each company can have its own API key configuration.

3

Verify AI Features

To verify that the API key is working correctly:

  1. Navigate to the Reports or Analytics section
  2. Try generating an AI-powered report (e.g., Demand Forecast or Price Optimization)
  3. If configured correctly, the report should generate successfully
  4. If you see an error, double-check that the API key is correct and has sufficient credits

Troubleshooting

If AI features are not working:

  • Verify the API key is correctly copied (no extra spaces)
  • Check your OpenAI account has available credits
  • Ensure your API key has not been revoked or expired
  • Check the application logs for detailed error messages

Step 6: Install InveTrack 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 7: 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 8: 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: 'invetrack-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.