Curl Installer Deployment Guide

The shell script installer for OpenPets, accessible via curl.

🚀 Quick Install Command

curl -fsSL https://pets.raggle.co/install | bash

Or with explicit GitHub URL:

curl -fsSL https://raw.githubusercontent.com/raggle-ai/raggle-repo/main/core/openpets/install.sh | bash

---

📝 Installer Details

Script Location: install.shPackage: openpets (from npm) Install Directory: ~/.openpets

---

🛠️ How It Works

Installation Process

1. Checks dependencies (Node.js 18+, npm)
2. Downloads package from npm registry (openpets)
3. Installs to ~/.openpets/
4. Creates binaries in ~/.openpets/bin/
   • pets - Main CLI
   • pets-mcp - MCP server
5. Updates PATH in shell config
6. Verifies installation

Directory Structure

~/.openpets/
├── bin/
│   ├── pets        # CLI wrapper
│   └── pets-mcp    # MCP server wrapper
└── lib/
    └── node_modules/
        └── openpets/  # npm package

---

⚙️ Configuration

Package Name

In install.sh:

PACKAGE_NAME="openpets"

Why no @ scope?

• Simpler for global installs
• Matches CLI command name
• Easier for users to remember

Install Location

INSTALL_DIR="$HOME/.openpets"
BIN_DIR="$INSTALL_DIR/bin"
LIB_DIR="$INSTALL_DIR/lib"

Binary Wrappers

~/.openpets/bin/pets:

#!/usr/bin/env node
const path = require('path');
const fs = require('fs');

const libDir = path.join(__dirname, '..', 'lib', 'node_modules', 'openpets');
const cliPath = path.join(libDir, 'cli.ts');

if (fs.existsSync(cliPath)) {
  require('tsx/cli').main([cliPath, ...process.argv.slice(2)]);
} else {
  const jsPath = path.join(libDir, 'cli.js');
  if (fs.existsSync(jsPath)) {
    require(jsPath);
  } else {
    console.error('Error: CLI entry point not found');
    process.exit(1);
  }
}

~/.openpets/bin/pets-mcp: Similar wrapper for MCP server.

---

🌐 Domain Setup

Option 1: Custom Domain with Redirect

Configure redirect for https://pets.raggle.co/install:

Cloudflare Pages (_redirects):

/install.sh https://raw.githubusercontent.com/raggle-ai/raggle-repo/main/core/openpets/install.sh 200
/install /install 200

Netlify (netlify.toml):

[[redirects]]
  from = "/install"
  to = "https://raw.githubusercontent.com/raggle-ai/raggle-repo/main/core/openpets/install.sh"
  status = 200
  force = true

Vercel (vercel.json):

{
  "redirects": [
    {
      "source": "/install",
      "destination": "https://raw.githubusercontent.com/raggle-ai/raggle-repo/main/core/openpets/install.sh",
      "permanent": false
    }
  ]
}

Option 2: Host Script Directly

Upload install.sh to your web server:

# Copy to web root
cp install.sh /var/www/pets.raggle.co/install

# Or to another static hosting provider
cp install.sh /path/to/static-site/install.sh

Then users can:

curl -fsSL https://pets.raggle.co/install.sh | bash

---

🧪 Testing

Test Script Locally

# Download and inspect
curl -fsSL https://pets.raggle.co/install -o test-install.sh
cat test-install.sh

# Run locally
bash test-install.sh

# Or with specific version
VERSION=1.0.4 bash test-install.sh

Test Installation

# Install
curl -fsSL https://pets.raggle.co/install | bash

# Verify
pets --version
pets list
pets-mcp --help

# Cleanup
rm -rf ~/.openpets
# Remove PATH entry from ~/.zshrc or ~/.bashrc

ShellCheck Validation

shellcheck install.sh

---

🔧 Customization

Install Specific Version

VERSION=1.0.3 curl -fsSL https://pets.raggle.co/install | bash

Silent Installation

curl -fsSL https://pets.raggle.co/install | bash -s -- --silent

Custom Install Directory

Modify install.sh:

# Allow override via environment variable
INSTALL_DIR="${OPENPETS_INSTALL_DIR:-$HOME/.openpets}"

Then:

OPENPETS_INSTALL_DIR=/usr/local/openpets curl -fsSL https://pets.raggle.co/install | bash

---

🎨 Installer Features

Dependency Checking

check_dependencies() {
    if ! command -v node >/dev/null 2>&1; then
        echo "Error: Node.js is required but not installed."
        exit 1
    fi

    local node_version=$(node --version | sed 's/v//' | cut -d'.' -f1)
    if [ "$node_version" -lt 18 ]; then
        echo "Warning: Node.js 18+ recommended."
    fi
}

Version Detection

check_version() {
    if command -v pets >/dev/null 2>&1; then
        local installed_version=$(npm list -g --depth=0 | grep "openpets" | sed 's/.*@//')
        echo "Version $installed_version already installed"
    fi
}

Shell Configuration

Automatically adds to PATH:

# For zsh
echo 'export PATH="$HOME/.openpets/bin:$PATH"' >> ~/.zshrc

# For bash
echo 'export PATH="$HOME/.openpets/bin:$PATH"' >> ~/.bashrc

# For fish
echo 'fish_add_path $HOME/.openpets/bin' >> ~/.config/fish/config.fish

---

📊 Analytics (Optional)

Track Installations

Add to install.sh:

# Send anonymous analytics
curl -s "https://analytics.pets.raggle.co/install?version=$VERSION&os=$os&arch=$arch" > /dev/null 2>&1 || true

Count via GitHub

GitHub tracks raw file requests:

• Insights → Traffic → Popular content

---

🔄 Updating Installer

After npm Publish

The installer automatically uses the latest npm version:

npm install "$PACKAGE_NAME$version_arg" --no-save

No changes needed unless:

• Package name changes
• Installation structure changes
• New features added

Testing Changes

# Test locally
bash install.sh

# Test from GitHub
bash <(curl -fsSL https://raw.githubusercontent.com/raggle-ai/raggle-repo/main/core/openpets/install.sh)

---

🆘 Troubleshooting

Common Issues

"Command not found: pets"

# Restart shell or source config
source ~/.zshrc  # or ~/.bashrc

"Node.js not found"

# Install Node.js
# macOS
brew install node

# Ubuntu/Debian
curl -fsSL https://deb.nodesource.com/setup_20.x | sudo -E bash -
sudo apt-get install -y nodejs

"Permission denied"

# Ensure install directory is writable
mkdir -p ~/.openpets
chmod 755 ~/.openpets

"npm WARN deprecated"

• This is normal for dependency warnings
• Installer continues despite warnings

---

📝 User Documentation

Installation Instructions

Include in README:

### Quick Install

Install OpenPets with a single command:

```bash
curl -fsSL https://pets.raggle.co/install | bash

After installation:

• pets --help - Show help
• pets list - List installed pets
• pets-mcp - Start MCP server

Uninstall

rm -rf ~/.openpets
# Remove PATH entry from shell config

---

🎯 Best Practices

Security

✅ DO:

• Use https:// URLs
• Include integrity checks
• Show what will be installed
• Allow inspection before running

❌ DON'T:

• Run as root/sudo
• Install to system directories
• Skip dependency checks

User Experience

✅ DO:

• Show progress indicators
• Provide clear error messages
• Auto-detect shell
• Support common shells (bash, zsh, fish)

❌ DON'T:

• Require manual PATH setup
• Show excessive output
• Fail silently

---

📋 Deployment Checklist

• [ ] Script tested locally
• [ ] ShellCheck passes
• [ ] Works on macOS
• [ ] Works on Linux
• [ ] Domain redirect configured
• [ ] Installation page updated
• [ ] Documentation updated
• [ ] Version detection works
• [ ] PATH auto-setup works
• [ ] Uninstall instructions provided

---

🆘 Support

• Installation Guide
• Setup Instructions
• Troubleshooting