MacOS - Installation Guide

This guide provides comprehensive instructions for setting up the PrestaShop Enterprise Developer Tools on macOS systems. Follow these steps carefully to ensure a proper installation and configuration.

System Requirements

Minimum Requirements

  • Operating System: macOS 15 (Sequoia) or later
  • RAM: 8 GB minimum (16 GB recommended)
  • Storage: 10 GB free disk space minimum
  • Architecture: Apple Silicon (M1/M2/M3)
  • Network: Internet connection for downloading tools and accessing repositories

Required Software

Before installing the Enterprise Developer Tools, you’ll need:

  • Docker Desktop for Mac
  • Git version control system
  • Homebrew package manager (recommended)
  • PrestaShop Enterprise Platform account
  • GitLab SSH access

Prerequisites Setup

Step 1: Install Xcode Command Line Tools

The Xcode Command Line Tools provide essential development utilities for macOS.

  1. Install Command Line Tools:

    xcode-select --install

  2. Accept the license agreement when prompted

  3. Verify installation:

    xcode-select -p

    You should see a path like /Applications/Xcode.app/Contents/Developer or /Library/Developer/CommandLineTools

Note: If you have Xcode installed from the App Store, the Command Line Tools are included. You can skip this step if Xcode is already installed.

Homebrew is the most popular package manager for macOS and simplifies software installation.

  1. Install Homebrew:

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

  2. Follow the installation prompts and enter your password when requested

  3. Add Homebrew to your PATH (for Apple Silicon Macs):

    echo 'eval "$(/opt/homebrew/bin/brew shellenv)"' >> ~/.zshrc
source ~/.zshrc

  4. Verify Homebrew installation:

    brew --version
Apple Silicon vs Intel: Homebrew installs to /opt/homebrew on Apple Silicon Macs and /usr/local on Intel Macs. The installer handles this automatically.

Step 3: Install Docker Desktop

Docker Desktop provides the containerization platform needed for the Enterprise Developer Tools.

Download and Install

  1. Download Docker Desktop:

    • Visit Docker Desktop for Mac
    • Choose the appropriate version:
      • Apple Silicon: Mac with Apple chip
      • Intel: Mac with Intel chip

  2. Install Docker Desktop:

    • Open the downloaded .dmg file
    • Drag Docker to the Applications folder
    • Launch Docker from Applications

  3. Complete setup:

    • Docker will request permission to install helper tools
    • Enter your password when prompted
    • Accept the Docker Subscription Service Agreement

  4. Verify Docker installation:

    docker --version
docker run --rm hello-world

Configure Docker Desktop

  1. Open Docker Desktop preferences:

    • Click the Docker icon in the menu bar
    • Select “Preferences” or “Settings”

  2. Recommended settings:

    • Resources > Memory: Allocate at least 4 GB (8 GB recommended)
    • Resources > Disk: Ensure sufficient space for containers
    • General: Enable “Start Docker Desktop when you log in”
Performance Note: Docker Desktop may impact system performance. Consider adjusting resource allocation based on your Mac’s specifications.

Step 4: Install Git

Git is essential for source code management and SSH access to repositories.

  1. Install Git:

    brew install git

  2. Verify Git installation:

    git --version

Alternative: Install Git from Official Installer

  1. Download Git for macOS:

  2. Install using the package installer

Configure Git

  1. Set your identity (replace with your information):

    git config --global user.name "Your Name"
git config --global user.email "your.email@example.com"

  2. Configure Git for better collaboration:

    # Set default branch name
git config --global init.defaultBranch main

# Set pull behavior to rebase
git config --global pull.rebase true

# Enable credential helper for macOS
git config --global credential.helper osxkeychain

# Improve diff display
git config --global diff.tool vimdiff

Step 5: Generate SSH Keys

SSH keys provide secure authentication to GitLab repositories without passwords.

Generate the SSH Key

  1. Create SSH key pair:

    ssh-keygen -t ed25519 -C "Mac $(hostname)"

  2. Configure the key generation:

    • File location: Press Enter to accept the default path (/Users/$USER/.ssh/id_ed25519)
    • Passphrase: Enter a secure passphrase or press Enter to skip
    • Note the output: The system will show where your keys are saved: 
      Your public key has been saved in /Users/<username>/.ssh/id_ed25519.pub

Set Up SSH Agent

macOS includes a built-in SSH agent, but you may need to configure it:

  1. Start SSH agent and add your key:

    eval "$(ssh-agent -s)"
ssh-add --apple-use-keychain ~/.ssh/id_ed25519

  2. Configure SSH to use the keychain (create or edit ~/.ssh/config):

    touch ~/.ssh/config
echo "Host *
  AddKeysToAgent yes
  UseKeychain yes
  IdentityFile ~/.ssh/id_ed25519" >> ~/.ssh/config

Copy the Public Key

  1. Display and copy the public key:

    cat ~/.ssh/id_ed25519.pub

  2. Or copy directly to clipboard:

    cat ~/.ssh/id_ed25519.pub | pbcopy

Add Key to GitLab

  1. Login to GitLab:

    • Visit GitLab Login
    • Use your enterprise.prestashop.com credentials

  2. Navigate to SSH Keys:

  3. Add the new key:

    • Click “Add new key”
    • Paste your public key content in the “Key” field
    • Add a descriptive title (e.g., “MacBook Pro Development Machine”)
    • Remove the expiration date (set to “No expiration”)
    • Click “Add key”

Test SSH Connection

  1. Test GitLab SSH connection:

    ssh -T git@git.hyperlane.co

  2. Expected response: You should see a welcome message from GitLab confirming successful authentication.

Keychain Integration: The SSH key will be stored in your macOS keychain, so you won’t need to enter the passphrase repeatedly.

Step 6: Install Additional Tools (Optional)

These tools can enhance your development experience:

Install Node.js and npm

Useful for some PrestaShop development tasks:

# Install Node.js LTS using Homebrew
brew install node

# Verify installation
node --version
npm --version

Install Visual Studio Code

For code editing and development:

# Install VS Code using Homebrew
brew install --cask visual-studio-code

# Or download from https://code.visualstudio.com/

Install Other Development Tools

# Install useful development tools
brew install wget curl jq tree

# Install database clients (optional)
brew install mysql-client postgresql

Installation

Download and Install Enterprise Developer Tools

  1. Create and navigate to your working directory:

    mkdir -p ~/prestashop-development
cd ~/prestashop-development

  2. Download the binary:

    curl -O "https://assets.prestashop3.com/enterprise/tools/macos/ps-enterprise.zip"

  3. Extract the files:

    unzip ps-enterprise.zip

  4. Clean up:

    rm ps-enterprise.zip

  5. Make executable and install system-wide:

    chmod +x ps-enterprise
./ps-enterprise install

  6. Handle macOS security prompt:

    • macOS may show a security warning about an unidentified developer
    • Go to System Settings > Privacy & Security
    • Click “Allow Anyway” next to the ps-enterprise application
    • Or run: sudo spctl --master-disable (temporarily disable Gatekeeper)

  7. Restart your terminal or source your shell profile:

    # For zsh (default on macOS)
source ~/.zshrc

# For bash
source ~/.bashrc

  8. Verify installation:

    ps-enterprise -v
macOS Security: You may need to authorize the application in System Settings > Privacy & Security after installation.

First Startup and Configuration

Initial Setup Process

  1. Navigate to your project directory:

    cd ~/prestashop-development
# Or create a new project directory
mkdir MyPrestaShopProject && cd MyPrestaShopProject

  2. Run the initial setup:

    ps-enterprise

Authentication Process

  1. Web Authentication:

    • A web browser will automatically open
    • If not, the terminal will display a URL to visit manually
    • Login using your PrestaShop Enterprise Platform credentials
    • Email: Same as your enterprise.prestashop.com account
    • Password: May differ from your enterprise.prestashop.com password

  2. Complete authentication and return to the terminal

Configuration Setup

  1. Project and Environment Selection:

    • Select your target project from the list
    • Choose the environment you want to work with
    • Configure any specific settings as prompted

  2. Local Environment Configuration:

    • The tool will automatically configure your local environment
    • Docker containers will be set up with proper permissions
    • Database connections will be established

  3. macOS-specific configurations:

    • File sharing permissions for Docker volumes
    • Network settings for local development
    • Keychain integration for credentials
First Startup Note: The initial setup may take 5-10 minutes as Docker downloads necessary images and configures the environment. This is normal behavior.

Verification and Testing

Test Your Installation

  1. Check all components:

    # Test ps-enterprise
ps-enterprise -v

# Test Docker
docker --version
docker run --rm hello-world

# Test Git
git --version

# Test Homebrew (if installed)
brew --version

# Check system architecture
uname -m

  2. Verify SSH connection:

    ssh -T git@git.hyperlane.co

    You should see a welcome message from GitLab.

  3. Test Docker functionality:

    # This should work without issues
docker ps
docker images

Common Issues and Solutions

Docker Issues

Problem: “Docker Desktop is not running”

# Solution: Start Docker Desktop
open -a Docker

# Or from command line
open /Applications/Docker.app

Problem: Docker containers running slowly

# Solution: Check Docker Desktop resources
# Go to Docker Desktop > Settings > Resources
# Increase Memory and CPU allocation

SSH Issues

Problem: SSH key not being recognized

# Check SSH agent
ssh-add -l

# Add key to agent
ssh-add --apple-use-keychain ~/.ssh/id_ed25519

# Test with verbose output
ssh -vT git@git.hyperlane.co

Problem: “Host key verification failed”

# Add GitLab to known hosts
ssh-keyscan git.hyperlane.co >> ~/.ssh/known_hosts

macOS-specific Issues

Problem: “ps-enterprise” command not found after installation

# Check if installation path is in PATH
echo $PATH

# Manually add to PATH (add to ~/.zshrc)
export PATH="$PATH:/usr/local/bin"

Problem: Gatekeeper blocking execution

# Remove quarantine attribute
sudo xattr -r -d com.apple.quarantine /path/to/ps-enterprise

# Or temporarily disable Gatekeeper
sudo spctl --master-disable

Network Issues

Problem: Cannot connect to repositories or download packages

# Check network connectivity
ping google.com

# Check DNS resolution
nslookup git.hyperlane.co

# Reset DNS cache
sudo dscacheutil -flushcache

Performance Optimization

macOS-specific Optimizations

  1. Optimize Docker performance:

    # Enable BuildKit for faster builds
echo 'export DOCKER_BUILDKIT=1' >> ~/.zshrc
echo 'export COMPOSE_DOCKER_CLI_BUILD=1' >> ~/.zshrc
source ~/.zshrc

  2. Increase file descriptor limits:

    # Add to ~/.zshrc
echo 'ulimit -n 65536' >> ~/.zshrc
source ~/.zshrc

  3. Configure Git for better performance:

    # Enable parallel processing
git config --global core.preloadindex true
git config --global core.fscache true

# Enable file system monitoring
git config --global core.fsmonitor true

System Resource Management

  1. Monitor system resources:

    # Check CPU and memory usage
top -l 1 | head -20

# Check disk usage
df -h

# Check Docker resource usage
docker system df

  2. Optimize Spotlight indexing (exclude development directories):

    • Go to System Settings > Siri & Spotlight > Spotlight Privacy
    • Add your development directories to prevent indexing

Next Steps

After successful installation and configuration:

  1. Explore the tools: Run ps-enterprise --help to see available commands
  2. Set up your first project: Use ps-enterprise to clone and configure a shop
  3. Read the documentation: Familiarize yourself with the Command Reference
  4. Configure your IDE: Set up your preferred development environment
  5. Install useful extensions: Consider VS Code extensions for PrestaShop development

Getting Help

If you encounter issues:

  1. Check system logs:

    # Check system logs
log show --predicate 'process == "ps-enterprise"' --last 1h

# Check Docker logs
docker system events

  2. Verify prerequisites: Ensure all components are properly installed

  3. Restart services: Try restarting Docker Desktop and your terminal

  4. Contact support: Reach out to your PrestaShop Enterprise support team

Troubleshooting Commands

Quick reference for common troubleshooting commands:

# System information
sw_vers
uname -a
sysctl hw.memsize hw.ncpu

# Docker information
docker info
docker system df
docker system prune

# Network connectivity
ping -c 4 git.hyperlane.co
curl -I https://assets.prestashop3.com

# Process information
ps aux | grep docker
ps aux | grep ps-enterprise

# File permissions and SSH
ls -la ~/.ssh/
ssh-add -l

# Homebrew information (if installed)
brew doctor
brew list

Useful macOS Shortcuts

Development-related shortcuts that can improve your workflow:

# Quick navigation
alias ll='ls -la'
alias la='ls -A'
alias l='ls -CF'

# Git shortcuts
alias gs='git status'
alias ga='git add'
alias gc='git commit'
alias gp='git push'

# Docker shortcuts
alias dps='docker ps'
alias di='docker images'
alias dc='docker compose'

# Add these to your ~/.zshrc file

Summary

You now have a complete macOS development environment for PrestaShop Enterprise development. The setup includes:

  • ✅ Xcode Command Line Tools with essential development utilities
  • ✅ Homebrew package manager for easy software installation
  • ✅ Docker Desktop with optimized performance settings
  • ✅ Git with SSH key authentication and keychain integration
  • ✅ PrestaShop Enterprise Developer Tools with proper macOS permissions
  • ✅ System optimizations for development workflows

Your macOS machine is ready for PrestaShop Enterprise development!