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 with a commercial certificate from Certum
• Windows may show a security warning on first run - this is normal
• No additional dependencies required

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.