Installation

Installing Pebble takes about 2 minutes. Seriously.

Requirements

  • PHP 7.4 or higher
  • GD Library (for image processing)
  • Zip extension (for backups)
  • Write permissions on your install directory

Most web hosts have these by default. If not, contact your host.

Install Pebble

1. Download

Get the latest installer from the download page.

You'll get a file named install-pebble-X.X.X.php (where X.X.X is the version number).

2. Upload

Put that installer file on your web server. Doesn't matter where—root directory, subdirectory, wherever your site lives.

3. Run the Installer

Visit it in your browser:

https://yoursite.com/install-pebble-X.X.X.php

The installer will:

  • Check your server (PHP version, extensions, permissions)
  • Detect existing website files
  • Create the pebble/ directory
  • Set up configuration
  • Generate a secure authentication key

Installing on an Existing Website?

If the installer detects existing website files (like index.html or index.php), it will ask you what to do:

  • Skip Example Page (Recommended) — Installs Pebble without creating any example files. Your existing website is preserved.
  • Create Example Page — Overwrites index.html with a Pebble demo page. Only choose this if you want to start fresh.

This protection ensures you won't accidentally overwrite your existing website when installing Pebble.

4. Save Your Auth Key

The installer shows you an authentication key. Copy it somewhere safe. This is how you'll log in to edit content.

You can also find it later in pebble/config.php.

5. Delete the Installer

For security, delete the installer file when you're done. The installer offers to do this automatically, or you can delete it manually via FTP.

What Gets Installed

After installation, you'll have a pebble/ directory:

your-site/
├── pebble/
│   ├── config.php          ← Your settings
│   ├── js/
│   │   ├── pebble.js       ← Main script
│   │   └── admin.js        ← Control panel
│   ├── css/
│   │   ├── pebble.css      ← Editing styles
│   │   └── admin.css       ← Control panel styles
│   ├── data/
│   │   ├── content/        ← Your edits live here
│   │   ├── shared/         ← Shared content
│   │   ├── uploads/        ← Uploaded images
│   │   └── trash/          ← Deleted content (recoverable)
│   └── logs/
│       ├── activity.log    ← Edit history
│       └── errors.log      ← Error logs
└── index.html              ← Your pages (or existing site)

Add Pebble to Your Site

1. Load the Script

Add this to your HTML (before </body>):

<script src="pebble/js/pebble.js"></script>

2. Mark Content as Editable

Add data-pebble attributes to content you want to edit:

<h1 data-pebble="page-title">Welcome to My Site</h1>
<p data-pebble="intro">This text is now editable.</p>

3. Test It

Visit your site and add #login to the URL (e.g., yoursite.com/#login).

Enter your auth key. Click any pebbled content to edit it. Done!

Pebble Pro License Activation

If you purchased Pebble Pro, the installer will prompt you to activate your license:

  1. Enter your license key - The 24-character key from your purchase email
  2. The installer connects to hellopebble.io - Validates your key and binds it to your domain
  3. License file is created - Stored in pebble/license.json

Each Pro license is valid for one production domain. You can change domains up to 3 times through your account dashboard.

Development Environments

Pro features work automatically on development environments without consuming your domain changes:

  • localhost, 127.0.0.1, ::1 - Loopback addresses
  • *.local - mDNS/Bonjour domains (e.g., mysite.local)
  • *.test - IETF-reserved testing TLD (e.g., mysite.test)
  • *.localhost - Reserved localhost subdomains
  • *.example - IETF-reserved documentation TLD

Setting up a local dev domain

Add an entry to your hosts file (/etc/hosts on Mac/Linux, C:\Windows\System32\drivers\etc\hosts on Windows):

127.0.0.1    mysite.local

Then configure your local web server (XAMPP, MAMP, etc.) to serve your project at that domain.

Next Steps