macOS Setup Guide

Complete installation and configuration guide for macOS systems

Prerequisites

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

Step 4: Install AsseTrack Server

1

Navigate to Server Directory

cd /path/to/assets-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=assettrack_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 AsseTrack Client

1

Navigate to Client Directory

cd /path/to/assets-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: 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: 'assettrack-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/assets-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.