Windows - Installation Guide

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

System Requirements

Minimum Requirements

  • Operating System: Windows 10 version 2004 or later, or Windows 11
  • RAM: 8 GB minimum (16 GB recommended)
  • Storage: 10 GB free disk space minimum
  • Network: Internet connection for downloading tools and accessing repositories

Required Software

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

  • Windows Subsystem for Linux 2 (WSL2)
  • Docker Desktop for Windows
  • Git for Windows
  • PrestaShop Enterprise Platform account
  • GitLab SSH access

Prerequisites Setup

Step 1: Install Windows Subsystem for Linux (WSL2)

WSL2 is required for Docker Desktop to function properly on Windows.

  1. Open PowerShell as Administrator

    • Right-click on the Start button
    • Select “Windows PowerShell (Admin)” or “Terminal (Admin)”

  2. Install WSL2 with Ubuntu:

    wsl.exe --install ubuntu

  3. Restart your computer when prompted

Note: If you encounter issues with WSL2 installation, ensure that virtualization is enabled in your BIOS settings and that the Windows Subsystem for Linux feature is enabled in Windows Features.

Step 2: Install Docker Desktop

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

  1. Download Docker Desktop:

  2. Install with default settings:

    • Run the installer as Administrator
    • Accept all default configuration options
    • Ensure “Use WSL 2 instead of Hyper-V” is selected

  3. Restart your computer after installation

  4. Verify Docker installation:

    • Open PowerShell (regular mode, not admin)
    • Test Docker: 
      docker run --rm hello-world
    • If you see “Hello from Docker!” → installation successful
    • If you get an error → proceed to user permissions configuration

Step 3: Configure Docker Permissions (If Needed)

If your administrator account differs from your user account, you may need to configure permissions:

  1. Open Computer Management as Administrator:

    • Right-click “This PC” → “Manage”
    • Or search for “Computer Management” in Start menu

  2. Navigate to User Groups:

    • Expand “Local Users and Groups”
    • Click on “Groups”
    • Find and double-click “docker-users”

  3. Add your user:

    • Click “Add…”
    • Type your username
    • Click “Check Names” to verify
    • Click “OK”

  4. Apply changes:

    • Sign out of Windows
    • Sign back in
    • Test Docker again with docker run --rm hello-world

Step 4: Install Git for Windows

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

  1. Download Git for Windows:

  2. Install with recommended settings:

    Important Configuration Options:

    • ✅ Check “Add a Git Bash Profile to Windows Terminal”

      • This enables Git Bash integration with Windows Terminal

    • Default Editor: Select your preferred editor

      • Recommended: Notepad or Visual Studio Code

    • Initial Branch Name: “Let Git decide” (recommended)

    • PATH Environment:

      • Select “Git from the command line and also from 3rd-party software”

    • SSH Executable:

      • Select “Use bundled OpenSSH”

    • HTTPS Transport Backend:

      • Select “Use the native Windows Secure Channel library”

    • Line Ending Conversions:

      • Select “Checkout Windows-style, commit Unix-style line endings”

    • Terminal Emulator:

      • Select “Use MinTTY”

    • Default Behavior for git pull:

      • ✅ Select “Rebase” (important for clean history)

    • Credential Helper:

      • Select “Git Credential Manager”

  3. Complete installation and restart your terminal

Step 5: Generate SSH Keys

SSH keys are required for secure access to GitLab repositories.

Generate the SSH Key

  1. Open PowerShell (non-administrator mode)

  2. Access Git Bash:

    • Click the dropdown arrow (▼) next to the “+” in PowerShell
    • Select “Git Bash” from the dropdown menu

  3. Generate SSH key pair:

    ssh-keygen -t ed25519 -C "PC Windows"

  4. Configure the key:

    • File location: Press Enter to accept default path
    • Passphrase: Enter a secure passphrase or press Enter to skip
    • Note the output: Save the path shown in the message: 
      Your public key has been saved in /c/Users/<username>/.ssh/id_ed25519.pub

Copy the Public Key

  1. Display and copy the public key:

    cat /c/Users/<username>/.ssh/id_ed25519.pub

    Replace <username> with your actual Windows username

  2. Copy the entire output to your clipboard

  3. Close Git Bash when done

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., “Windows Development Machine”)
    • Remove the expiration date (set to “No expiration”)
    • Click “Add key”
Security Note: Keep your private key secure and never share it. The public key is safe to share and is what gets added to GitLab.

Step 6: Retrieve User and Group IDs

Docker containers need proper user permissions, which require your WSL user and group IDs.

  1. Open Git Bash in PowerShell (as done in Step 5)

  2. Get your User ID:

    id -u

    Important: Write down this number - you’ll need it during first startup

  3. Get your Group ID:

    id -g

    Important: Write down this number as well

  4. Close Git Bash

Example: Your IDs might look like 1000 (user) and 1000 (group). These numbers are used to ensure proper file permissions between Windows and the Docker containers.

Installation

Download and Install Enterprise Developer Tools

  1. Open PowerShell in your desired working directory

  2. Download the binary:

    Invoke-WebRequest -Uri "https://assets.prestashop3.com/enterprise/tools/windows/ps-enterprise.zip" `
                  -OutFile "ps-enterprise.zip"

  3. Extract the files:

    Expand-Archive -Path "ps-enterprise.zip" `
               -DestinationPath (Get-Location) -Force

  4. Clean up:

    Remove-Item -Path "ps-enterprise.zip"

  5. Install system-wide:

    ./ps-enterprise.exe install

  6. Restart PowerShell to refresh the PATH

  7. Verify installation:

    ps-enterprise.exe -v

First Startup and Configuration

Initial Setup Process

  1. Create your project directory:

    mkdir MyPrestaShopProject
cd MyPrestaShopProject

  2. Run the initial setup:

    ps-enterprise

Windows Security Prompts

During the first startup, Windows will show security prompts:

  1. Node.js JavaScript Runtime:

    • Prompt: “Do you want to allow this app to make changes to your device?”
    • Action: Click “Allow” or “Autoriser”

  2. Docker Backend:

    • Prompt: “Do you want to allow this app to make changes to your device?”
    • Action: Click “Allow” or “Autoriser”

Web Authentication

  1. Browser authentication:

    • A web browser will automatically open
    • 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 PowerShell

User Configuration

  1. User ID Configuration:

    • When asked “Is user right?”: Type “N” and press Enter
    • Enter the User ID you noted in Step 6
    • Enter the Group ID you noted in Step 6

  2. Complete setup:

    • Follow the remaining configuration prompts
    • Select your project and environment
    • Configure any additional settings as needed
First Startup Note: The initial setup may take 10-15 minutes as Docker downloads necessary images and Windows configures security permissions. 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 WSL
wsl --list --verbose

  2. Verify SSH connection:

    # In Git Bash
ssh -T git@git.hyperlane.co

    You should see a welcome message from GitLab.

Common Issues and Solutions

Docker Issues

Problem: “Docker daemon is not running”

# Solution: Start Docker Desktop
# Check if Docker Desktop is running in system tray
# If not, start it from Start menu

Problem: Permission denied errors

# Solution: Add user to docker-users group (see Step 3)
# Or run PowerShell as Administrator temporarily

WSL Issues

Problem: WSL2 not working

# Check WSL status
wsl --status

# Update WSL if needed
wsl --update

# Set default version to WSL2
wsl --set-default-version 2

SSH Issues

Problem: SSH key not working

# In Git Bash, check SSH agent
ssh-add -l

# Add key if needed
ssh-add ~/.ssh/id_ed25519

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

Getting Help

If you encounter issues:

  1. Check the logs: Look at PowerShell output for error messages
  2. Verify prerequisites: Ensure all components are properly installed
  3. Restart services: Try restarting Docker Desktop and PowerShell
  4. Contact support: Reach out to your PrestaShop Enterprise support team

Summary

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

  • ✅ WSL2 with Ubuntu
  • ✅ Docker Desktop with proper permissions
  • ✅ Git with SSH key authentication
  • ✅ PrestaShop Enterprise Developer Tools
  • ✅ Proper user and group ID configuration

Your Windows machine is ready for PrestaShop Enterprise development!