Installation

Butler Sheet Icons offers multiple installation options to suit different use cases and environments. Choose the option that best fits your needs.

🚀 Stand-alone Binaries (Recommended)

The easiest and most common way to use Butler Sheet Icons is with the pre-built binaries. No installation required - just download and run!

Download

Visit the GitHub releases page and download the appropriate binary for your platform:

• Windows: butler-sheet-icons-<version>-win.zip
• macOS: butler-sheet-icons-<version>-arm64-macos.zip (Apple Silicon, M1/M2/M3/M4), butler-sheet-icons-<version>-macos.zip (Intel)
• Linux: butler-sheet-icons-<version>-linux.zip

Platform-Specific Notes

Windows

• The binary is digitally signed by Ptarmigan Labs AB, the publisher Windows shows, from BSI 5.2.1 onwards. 5.0.0 to 5.2.0 were signed with a Certum certificate issued to an individual open source developer, so Windows showed a person's name as the publisher. 4.0.0 and 4.1.0 shipped unsigned
• Windows may show a security warning on first run - this is normal, and a signature does not immediately stop it
• No additional dependencies required

See Windows code signing for how to verify the signature, what it does and does not protect against, and how to build an AppLocker or WDAC rule that keeps matching new releases.

macOS

• The binary is notarized by Apple's standard process
• macOS may show a warning on first run - allow it in System Preferences
• Works on both Intel and Apple Silicon Macs

Linux

• Compatible with most Linux distributions
• May require setting executable permissions: chmod +x butler-sheet-icons-linux
• No additional dependencies required

Verification

After downloading, verify the binary works:

# Windows
.\butler-sheet-icons-win.exe --version

# macOS
./butler-sheet-icons-macos --version

# Linux
./butler-sheet-icons-linux --version

🐳 Docker Container

Perfect for containerized environments, CI/CD pipelines, or when you prefer isolated execution.

Pull the Image

docker pull ptarmiganlabs/butler-sheet-icons:latest

Basic Usage

docker run -it --rm ptarmiganlabs/butler-sheet-icons:latest --help

With Volume Mounts

For saving screenshots and providing certificates:

docker run -it --name butler-sheet-icons \
  -v $(pwd)/img:/nodeapp/img \
  -v $(pwd)/cert:/nodeapp/cert \
  --rm ptarmiganlabs/butler-sheet-icons:latest \
  qscloud create-sheet-icons --help

Docker Compose

Create a docker-compose.yml file:

services:
  butler-sheet-icons:
    image: ptarmiganlabs/butler-sheet-icons:latest
    volumes:
      - ./img:/nodeapp/img
      - ./cert:/nodeapp/cert
    environment:
      - BSI_QSCLOUD_CST_TENANTURL=your-tenant.qlikcloud.com
      - BSI_QSCLOUD_CST_APIKEY=your-api-key
    command: qscloud create-sheet-icons --appid your-app-id

🔧 Node.js Source Installation

For developers, contributors, or when you need to modify the tool. Requires Node.js knowledge.

Prerequisites

• Node.js LTS version (tested against latest LTS)
• npm (comes with Node.js)
• Git (for cloning the repository)

Installation Steps

1. Clone the repository:

   git clone https://github.com/ptarmiganlabs/butler-sheet-icons.git
   cd butler-sheet-icons

2. Install dependencies:

   npm install

3. Run from source:

   node src/butler-sheet-icons.js --help

Development Setup

For development work:

# Install development dependencies
npm install --include=dev

# Run tests
npm test

# Run linting
npm run lint

# Build binaries
npm run build

📁 File Organization

Regardless of installation method, Butler Sheet Icons expects certain file structures:

Default Directory Structure

your-working-directory/
├── butler-sheet-icons      # Binary (or node src/)
├── cert/                   # QSEoW certificates (optional)
│   ├── client.pem
│   └── client_key.pem
└── img/                    # Screenshot output (auto-created)
    ├── cloud/
    └── qseow/

Certificate Setup (QSEoW Only)

For Qlik Sense Enterprise on Windows, you'll need certificates:

1. Export from QMC:

   • Follow Qlik's certificate export guide
   • Export client.pem and client_key.pem

2. Place in cert directory:

   cert/
   ├── client.pem
   └── client_key.pem

3. Specify custom paths using command line options if needed:

   --certfile /path/to/client.pem \
   --certkeyfile /path/to/client_key.pem

🔍 Verification

After installation, verify everything works:

Test Basic Functionality

# Check version
butler-sheet-icons --version

# View help
butler-sheet-icons --help

# List available commands
butler-sheet-icons qscloud --help
butler-sheet-icons qseow --help

Test Browser Installation

# List installed browsers
butler-sheet-icons browser list-installed

# Install a browser (if none installed)
butler-sheet-icons browser install --browser chrome

🚨 Troubleshooting Installation

Common Issues

Binary Not Found

# Make sure it's executable (Linux/macOS)
chmod +x butler-sheet-icons-linux

# Check if it's in your PATH or use full path
./butler-sheet-icons-linux --version

Security Warnings

Windows: Right-click → Properties → Unblock, or run as Administrator initially

macOS: System Preferences → Security & Privacy → Allow anyway

Docker Permission Issues

# Fix volume mount permissions
sudo chown -R $(whoami) ./img ./cert

Node.js Version Issues

# Check Node.js version
node --version

# Should be LTS version (18.x or later)
# Update if necessary

⚙️ Next Steps

Now that Butler Sheet Icons is installed:

1. Quick Start - Try it out with a simple example
2. Configuration - Set up for your environment
3. Examples - See real-world usage scenarios
4. Commands Reference - Explore all available options

---

Having installation issues? Check our Troubleshooting Guide or open an issue on GitHub.