Building Pinguin for Windows on Arm

This guide provides step-by-step instructions for building and running Pinguin on Windows on Arm devices, specifically optimized for the Arm AI Developer Challenge 2025.

Prerequisites

Hardware Requirements

Windows on Arm Device: Snapdragon X Elite, Surface Pro X, or similar
RAM: Minimum 4GB, 8GB+ recommended
Storage: 10GB free space (5GB for models, 5GB for documents)
CPU: Modern Arm64 processor (Snapdragon X Elite, SQ1, SQ2, etc.)

Software Requirements

Windows 11 on Arm (build 22000 or later)
Visual Studio 2022 with C++ build tools (Arm64)
Node.js 18+ (Arm64 build)
Python 3.10+ (Arm64 build)
Git for Windows (Arm64)

Quick Start for Judges

If you're a hackathon judge testing Pinguin, follow these simplified steps:

1. Install Ollama

Visit ollama.com
Download "Ollama for Windows (ARM64)"
Run the installer
Ollama will start automatically in the background

2. Download Pinguin Installer

Go to Pinguin Releases
Download Pinguin-Setup-1.0.0-arm64.exe

3. Install Pinguin

Double-click Pinguin-Setup-1.0.0-arm64.exe
Follow the installation wizard
Launch Pinguin from Start Menu or desktop shortcut

4. First-Run Setup

When you launch Pinguin for the first time:

Welcome Screen: Click "Next"
LLM Setup:
- Recommended: llama3.2:3b (fast, 2GB)
- Alternative: qwen2.5:3b (better reasoning, 2GB)
- Click "Download" - this will take 2-5 minutes
- Wait for "Model Ready" status
Embedding Setup:
- Recommended: nomic-embed-text (fast, 274MB)
- Alternative: mxbai-embed-large (better quality, 670MB)
- Click "Download" - this will take 1-2 minutes
- Wait for "Model Ready" status
Finish: Click "Finish" to start using Pinguin

5. Test the Application

Upload a Document:
- Click "Documents" in sidebar
- Click "Upload Document"
- Recommended: Select a text-based PDF, DOCX, or TXT file for first test
- Wait for processing (10-30 seconds for text-based documents)
- Note: Scanned PDFs with OCR can take 20-30 minutes - use text-based documents for best experience
Ask a Question:
- Go to "Chat" tab
- Type a question about your document
- Press Enter or click Send
- First query may take 1-2 minutes (models loading into memory)
- Subsequent queries: 30-50 seconds depending on complexity
- Watch the AI generate an answer with sources
Verify Arm Optimization:
- Open Task Manager / Activity Monitor
- Check CPU usage during inference
- Note the efficient performance on Arm hardware

Troubleshooting: If the UI doesn't update after sending a message, navigate to another chat and back. See KNOWN_ISSUES.md for complete details and workarounds.

Building from Source

For developers who want to build Pinguin from source:

1. Clone Repository

git clone https://github.com/Kehn-Marv/Pinguin.git
cd Pinguin

2. Install Node.js Dependencies

npm install

This will install all Electron and React dependencies, including Arm64-specific native modules.

3. Setup Python Backend

Windows on Arm

cd backend
python -m venv venv
.\venv\Scripts\activate
pip install -r requirements.txt
cd ..

macOS / Linux

cd backend
python3 -m venv venv
source venv/bin/activate
pip install -r requirements.txt
cd ..

4. Download External Dependencies

Pinguin requires Tesseract (OCR) and Poppler (PDF processing):

Automated Setup (Recommended)

npm run setup-architecture-binaries

This script will:

Detect your Arm architecture
Download Arm64 builds of Tesseract and Poppler
Extract them to extraResources/
Verify installation

Manual Setup

If automated setup fails, download manually:

Tesseract (Windows on Arm)

Download from UB-Mannheim/tesseract
Extract to extraResources/tesseract/win32-arm64/

Poppler (Windows on Arm)

Download from oschwartz10612/poppler-windows
Extract to extraResources/poppler/

macOS (Apple Silicon)

brew install tesseract poppler

Linux Arm64

sudo apt-get install tesseract-ocr poppler-utils

5. Build the Application

Development Build

npm start

This starts Electron in development mode with hot reload.

Production Build

npm run make

This creates a distributable package in the out/ directory.

Build for Windows on Arm

npm run make -- --arch=arm64 --platform=win32

6. Verify Build

After building, test the application:

.\out\Pinguin-win32-arm64\Pinguin.exe

Arm-Specific Optimizations

1. Native Module Compilation

Pinguin uses several native Node.js modules that must be compiled for Arm64:

# Rebuild native modules for Arm64
npm rebuild --arch=arm64

Key native modules:

better-sqlite3: Database operations
electron: Native Electron bindings
Various cryptography modules

2. Python Package Optimization

Some Python packages have Arm-specific wheels:

# Install with Arm64 wheels
pip install --platform manylinux2014_aarch64 --only-binary=:all: numpy

Packages with Arm optimizations:

numpy: BLAS/LAPACK with Arm NEON
chromadb: Vector operations
sentence-transformers: Model inference

3. Ollama Configuration

Ollama automatically detects Arm architecture and uses optimized builds:

# Verify Ollama is using Arm64
ollama --version
# Should show: ollama version x.x.x (arm64)

# Check available models
ollama list

# Pull Arm-optimized models
ollama pull llama3.2:3b
ollama pull nomic-embed-text

4. Performance Tuning

Environment Variables

# Optimize for Arm NEON
export GGML_NEON=1

# Set thread count (adjust for your CPU)
export OMP_NUM_THREADS=8

# Enable Arm-specific optimizations
export OLLAMA_NUM_PARALLEL=2

Model Quantization

Use quantized models for better performance:

llama3.2:3b-q4_0 - 4-bit quantization (faster)
llama3.2:3b-q8_0 - 8-bit quantization (balanced)
llama3.2:3b - Full precision (best quality)

Troubleshooting

Build Issues

Error: Cannot find module 'electron'

npm install --force
npm rebuild electron

Error: Python module not found

cd backend
pip install -r requirements.txt --force-reinstall

Error: Tesseract not found

npm run verify-tesseract
# If fails, run: npm run setup-tesseract

Runtime Issues

Ollama Connection Failed

# Check if Ollama is running
curl http://localhost:11434/api/tags

# If not running, start it
ollama serve

Backend Won't Start

# Check port 8000 is free
netstat -an | grep 8000

# Kill process using port 8000
# Windows: taskkill /F /PID <pid>
# macOS/Linux: kill -9 <pid>

Slow Performance

Use smaller models (3B instead of 7B)
Reduce batch size in settings
Close other applications
Ensure adequate cooling (Arm CPUs can throttle)

Platform-Specific Issues

Windows on Arm

Install Visual C++ Redistributable (Arm64)
Disable antivirus temporarily during build
Run PowerShell as Administrator for scripts

macOS (Apple Silicon)

Install Rosetta 2 for compatibility: softwareupdate --install-rosetta
Grant Full Disk Access to Terminal in System Preferences
Use native Arm64 terminal, not Rosetta

Linux Arm64

Install build essentials: sudo apt-get install build-essential
Update to latest kernel for best Arm support
Check SELinux/AppArmor isn't blocking Electron

Performance Benchmarks

Build Times (on Snapdragon X Elite)

npm install: ~3 minutes
npm run make: ~5 minutes
Total build time: ~8 minutes

Runtime Performance

Startup Time

Cold start: ~4 seconds
Warm start: ~2 seconds

Document Processing

PDF (10 pages): ~5 seconds
PDF with OCR (10 pages): ~30 seconds
DOCX (50 pages): ~8 seconds

Inference Speed (llama3.2:3b)

Tokens per second: 25-40 (CPU only)
Query latency: 2-4 seconds
Embedding generation: ~100ms

Memory Usage

Idle: ~300MB
With 3B model: ~2.5GB
With 7B model: ~5GB
Peak during processing: ~3.5GB

Continuous Integration

Pinguin uses GitHub Actions for automated builds:

# .github/workflows/build-arm.yml
name: Build Arm64
on: [push, pull_request]
jobs:
  build:
    runs-on: [self-hosted, ARM64]
    steps:
      - uses: actions/checkout@v3
      - uses: actions/setup-node@v3
        with:
          node-version: '18'
          architecture: 'arm64'
      - run: npm install
      - run: npm run make

Distribution

Creating Installers

Windows (Squirrel)

npm run makeSquirrel

macOS (DMG)

npm run make -- --targets=@electron-forge/maker-dmg

Linux (AppImage)

npm run make -- --targets=@electron-forge/maker-appimage

Code Signing

For production releases, sign your binaries:

Windows

signtool sign /f certificate.pfx /p password /tr http://timestamp.digicert.com Pinguin.exe

macOS

codesign --deep --force --verify --verbose --sign "Developer ID" Pinguin.app

Resources

Support

For build issues or questions:

Open an issue on GitHub
Email: kehnmarv30@gmail.com
Check Discussions

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Building Pinguin for Windows on Arm

Prerequisites

Hardware Requirements

Software Requirements

Quick Start for Judges

1. Install Ollama

2. Download Pinguin Installer

3. Install Pinguin

4. First-Run Setup

5. Test the Application

Building from Source

1. Clone Repository

2. Install Node.js Dependencies

3. Setup Python Backend

4. Download External Dependencies

5. Build the Application

6. Verify Build

Arm-Specific Optimizations

1. Native Module Compilation

2. Python Package Optimization

3. Ollama Configuration

4. Performance Tuning

Troubleshooting

Build Issues

Runtime Issues

Platform-Specific Issues

Performance Benchmarks

Build Times (on Snapdragon X Elite)

Runtime Performance

Continuous Integration

Distribution

Creating Installers

Code Signing

Resources

Support

FilesExpand file tree

ARM_BUILD_GUIDE.md

Latest commit

History

ARM_BUILD_GUIDE.md

File metadata and controls

Building Pinguin for Windows on Arm

Prerequisites

Hardware Requirements

Software Requirements

Quick Start for Judges

1. Install Ollama

2. Download Pinguin Installer

3. Install Pinguin

4. First-Run Setup

5. Test the Application

Building from Source

1. Clone Repository

2. Install Node.js Dependencies

3. Setup Python Backend

4. Download External Dependencies

5. Build the Application

6. Verify Build

Arm-Specific Optimizations

1. Native Module Compilation

2. Python Package Optimization

3. Ollama Configuration

4. Performance Tuning

Troubleshooting

Build Issues

Runtime Issues

Platform-Specific Issues

Performance Benchmarks

Build Times (on Snapdragon X Elite)

Runtime Performance

Continuous Integration

Distribution

Creating Installers

Code Signing

Resources

Support