Installation and licensing

Install PageDesigner, run its migrations, configure licensing and hosted features, and understand optional theme integration.

This guide is for the Paymenter owner or system administrator. A normal page editor can start at Quickstart and page management.

Before you installCopy Anchor Link

Confirm that you have:

• Administrator access to Paymenter.
• A PageDesigner release ZIP from an authorized source.
• A PageDesigner license key and, if supplied, the associated account email or ID.
• A current database backup.
• A supported Paymenter installation and the PHP version required by that Paymenter release.
• Outbound HTTPS access from the Paymenter server if you intend to activate licensing, browse Hosted models, use the hosted AI path, share packages, or download marketplace content.
• License Key join discord to get one if you dont have it.

Install the ZIPCopy Anchor Link

Configure hosted access and licensingCopy Anchor Link

Open PageDesigner's extension settings.

Enable component library and MarketplaceCopy Anchor Link

Turn on Enable component library and Marketplace when this installation should use Hosted features. Published pages continue to render locally if this is later disabled, but management features that require a valid entitlement become unavailable.

License keyCopy Anchor Link

Enter the PageDesigner license key. The browser does not receive this key. PageDesigner uses it server-to-server and stores a SHA-256 hash with the locally verified license grant.

Account email or IDCopy Anchor Link

Enter the account reference only when the license is associated with one or your provider asks you to use it.

Install nameCopy Anchor Link

Use a friendly identifier such as Production billing or Staging portal. It helps distinguish licensed installations.

Public server IPCopy Anchor Link

Set Public server IP when the server is behind NAT, CloudPanel, a reverse proxy, or another setup where PHP sees a loopback or private address.

• Enter the public egress address seen by the Hosted service.
• Do not enter 127.0.0.1, ::1, or an RFC1918 private address.
• If you move the installation to another server, release or deactivate the old install slot before activating the new environment.

Update channel and cache optionsCopy Anchor Link

Save the extension settings. The next licensed management operation performs or refreshes the server-to-server check-in as required.

How license decisions affect the productCopy Anchor Link

An active license is required for page management, custom components, Hosted models, marketplace operations, sharing/imports, the built-in AI agent, direct custom AI providers, MCP tokens and MCP requests, and update checks.

Paymenter permissions apply in addition to the license.

flowchart TD
    A[Administrator starts a PageDesigner management operation] --> B{Matching Paymenter permission?}
    B -- No --> C[Access denied]
    B -- Yes --> D{Valid signed grant or allowed offline grace?}
    D -- Yes --> E[Operation continues]
    D -- No --> F[Management operation blocked]
    F --> G[Already-published local pages still render]

An online response that reports an expired, suspended, revoked, invalid, mismatched, or install-limited license blocks immediately. A Hosted outage may use a previously verified signed grant only until its offline-grace deadline.

The editor needs no frontend buildCopy Anchor Link

The PageDesigner ZIP contains the editor runtime, GrapesJS, CodeMirror, formatting helpers, language files, and its asset manifest. The editor:

• does not need a root npm install;
• does not use a public CDN for its core scripts, styles, or fonts;
• does not require a theme edit;
• is served through an extension-owned allow-list route.

This is different from the optional integration below.

Optional FlyonUI and Iconify integrationCopy Anchor Link

Selected interactive published components can receive richer FlyonUI behavior and Iconify styling when the active theme includes those libraries. PageDesigner does not edit the theme automatically. Without this integration, published components use the extension's built-in graceful fallback, but some enhanced interactions or styles are unavailable.

Run these commands from the Paymenter project root:

npm install flyonui
npm install -D @iconify/tailwind4 @iconify-json/tabler

In the active theme CSS, after @import 'tailwindcss';, add:

@plugin 'flyonui';
@plugin '@iconify/tailwind4';
@import '../../../node_modules/flyonui/variants.css';
@source '../../../node_modules/flyonui/dist/index.js';

In the active theme JavaScript, add:

import 'flyonui/flyonui';

Then rebuild the active theme:

npm run build

For the underlying theme workflow, see the Paymenter theme asset documentation.

Configure the AI providerCopy Anchor Link

PageDesigner can use the licensed hosted AI path or a direct OpenAI-compatible provider.

To use a direct provider, configure:

• Use a custom OpenAI-compatible AI endpoint.
• Custom AI endpoint URL — a base URL such as https://api.openai.com/v1 or a full /chat/completions URL.
• Custom AI API key — stored in PageDesigner settings and used by the Paymenter server, never sent to the browser.
• Custom AI model — the exact model ID exposed by the provider.
• Custom AI timeout — 30 to 180 seconds.

Saving a non-empty custom AI API key enables the direct provider and gives it priority over the hosted AI proxy. Hosted components and marketplaces remain separate.

Production endpoints must use HTTPS. Temporarily allow HTTP direct AI provider exists only for local or test environments and should remain off in production.

The AI workflow is queue-backed. Ensure Paymenter's configured Laravel queue worker is running; one model response is checkpointed per job, and a job can run for up to five minutes to accommodate the provider timeout.

Verify the installationCopy Anchor Link

1. Open Extensions → Page Designer.
2. Create a test page and leave Published off.
3. Open the editor.
4. Add a basic component, edit its text, and save.
5. Open Preview.
6. Open the Model Marketplace and confirm it reports either a connected Hosted manifest or the local downloaded cache.
7. If AI is configured, send a Read only request such as “Review the page hierarchy without changing anything.”
8. Delete the test page only after the checks are complete.

Upgrade safelyCopy Anchor Link

1. Back up the Paymenter database.
2. Retain the current ZIP.
3. Upload the new release ZIP through the extension manager.
4. Run the extension upgrade/migration lifecycle.
5. Re-enable the extension if the manager disabled it.
6. Open the Page Designer list and test one draft in the editor.
7. Verify a published page on the storefront.
8. Review the Model Marketplace, AI status, and MCP token list if you use those features.

Do not delete ext_page_designer_* tables to troubleshoot an upgrade. For rollback, restore the matching database backup and reinstall the previous ZIP.

UninstallingCopy Anchor Link

The extension's uninstall lifecycle can roll back its migrations. That can remove stored PageDesigner data. Export or back up anything you need before uninstalling.

Disabling PageDesigner is safer than uninstalling when you are investigating a problem. Confirm how your Paymenter version treats extension deletion and migration rollback before proceeding.

Installation troubleshootingCopy Anchor Link

Page Designer is missingCopy Anchor Link

• Confirm the ZIP contains the expected PageDesigner extension directory.
• Confirm the extension is enabled.
• Run the install/upgrade lifecycle again.
• Clear Paymenter application and route caches using the maintenance process appropriate for your installation.
• Check the application log for extension boot or migration errors.

A table is missingCopy Anchor Link

Do not create tables manually. Re-run the PageDesigner install/upgrade lifecycle so the bundled migrations execute in order.

Hosted features say unconfiguredCopy Anchor Link

Confirm Enable component library and Marketplace is on, the license key is saved, the Paymenter application URL is correct, and the server can make outbound HTTPS requests.

Activation reports an install or IP mismatchCopy Anchor Link

Check the public application URL and Public server IP. If the installation was moved, release the previous install slot or contact the license provider.

The AI panel stays queuedCopy Anchor Link

Verify the Laravel queue worker is running and processing the configured default queue. Review the failed-jobs and application logs before resubmitting a large request.