Panel CommentsAdmin sign in
Documentation

Deployment

Deployment

cPanel and aaPanel

Create a PHP website or subdomain normally, then upload the release contents directly into the directory the panel assigned to that website. Keep that directory as the website directory. Panel Comments does not use a public/ subfolder and does not require a rewrite rule.

The only hosting-panel choices needed are PHP 8.4+ and HTTPS. The host’s existing PHP handler is used; Panel Comments has no PHP port or PHP-FPM socket setting.

Open the website or /install/. The installer detects domain, port, and subfolder automatically and asks for only database and administrator essentials. If panel-config.php already exists, its database settings are used and preserved.

Physical entry points make the application work under ordinary Apache or Nginx configurations:

  • index.php — installation entrance before setup and public project landing afterward
  • install/index.php — setup
  • admin/index.php — administration
  • api/index.php — public API and CORS
  • docs/index.php — public documentation without a rewrite rule
  • integration.php, health.php, feed.php, verify.php, and unsubscribe.php

Pretty URLs may work when a host supplies rewriting, but Panel Comments never depends on them.

Permissions and open_basedir

Recommended modes are 0755 for application directories, 0644 for application files, 0700 for panel-content, and 0600 for its generated files. PHP needs write access to panel-content and, when the web installer creates panel-config.php, the application root during installation.

An open_basedir containing the uploaded application directory and the system temporary directory is sufficient. Panel Comments does not probe a sibling or parent var directory during normal operation.

Files under panel-content are executable PHP guard containers. Direct requests return an empty 404 before PHP reaches configuration, key, cache, log, lock, or encrypted-backup bytes. The bundled .htaccess adds Apache defense in depth, but Nginx does not need a matching deny rule.

Keep display_errors=Off in production. The bundled .user.ini supplies conservative defaults where the host supports per-directory PHP settings.

Unhandled failures are written both to the protected daily file under panel-content/logs/ and to the hosting panel's normal website error log. Search either log for the request ID shown in the error response; mirrored lines begin with [Panel Comments].

Subfolder installs and proxies

Installing at https://example.com/comments/ is supported. Admin links, cookies, APIs, feeds, assets, verification links, and unsubscribe links retain /comments/ automatically.

For an unusual reverse proxy that hides the external scheme, hostname, port, or path, set app.base_url in panel-config.php. Ordinary cPanel and aaPanel installations should leave detection alone. Trusted proxy address ranges can also be configured there when forwarding real client IP addresses.

Background work

The bounded web runner processes durable jobs after a portion of requests, including refreshes for any opt-in anti-spam blocklists, so initial operation does not require cron. A failed refresh keeps the last usable local list. For busy or time-sensitive installations, add the optional once-per-minute command:

* * * * * /usr/local/bin/php /absolute/path/panel-comments/bin/panel cron --budget=50 >/dev/null 2>&1

Queue locking prevents duplicate claims when web and CLI workers overlap.

Cloudflare

Cloudflare proxying is supported. Panel Comments accepts CF-Connecting-IP only when the direct peer is in Cloudflare's official address ranges; the bundled list refreshes automatically.

The complete setup and live checks are inside Admin → Tools → Optimization. That page covers the proxied DNS record, Full (strict) TLS, origin protection, Rocket Loader, WAF behavior, public Cache Rules, hosting-added Set-Cookie, OPcache/APCu/Redis, cron, and pending database updates. This is the primary setup surface—operators do not need to find a separate deployment guide.

Automatic rules with a private OAuth client

An owner can have Panel Comments create and repair its own rules without copying expressions through the Cloudflare dashboard. This is deliberately per installation: there is no shared Panel Comments Cloudflare account, Worker, callback service, or long-lived API token.

  1. Open Manage Account → OAuth clients, choose the account containing Panel Comments, and click Create client. Cloudflare makes it private automatically.
  2. On Configure OAuth client, set Client Name to any recognizable name, Response Type to Code, Grant type to Authorization Code, and Token Authentication Method to Client Secret Basic (client_secret_basic).
  3. Paste the exact address shown in Panel Comments into Redirect (Callback) URLs. It includes the installation subfolder when one is present. Leave Client URL (optional) blank and leave Advanced options unchanged, then click Continue.
  4. On Select permission scopes, search for and add exactly Zone Read, Cache Rules Edit, Config Rules Edit, Account Rulesets Edit, and Account Filter Lists Edit. Cloudflare calls full access Edit on this screen—do not look for permissions ending in “Write.”
  5. Create the client. Copy Cloudflare's 32-character Client ID into Cloudflare Client ID, then copy the longer, one-time Client Secret into Cloudflare Client Secret. Do not swap them. Save both in Panel Comments, then choose Connect and configure Cloudflare.

For troubleshooting only, those five dashboard choices correspond to the OAuth scope IDs zone.read, cache-settings.write, config-settings.write, account-rulesets.write, and account-rule-lists.write. Users should select permissions by the dashboard names in step 4.

The client ID and secret may instead be placed in the optional cloudflare block of panel-config.php; file values take precedence over values saved in the administration interface. The authorization uses PKCE and a short-lived, signed, callback-only cookie. Panel Comments exchanges the returned code, applies the rules, and revokes the access token when the operation finishes. The client secret remains encrypted at rest when saved through the interface.

Automatic setup resolves the active Cloudflare zone containing the Panel Comments hostname and changes only rules carrying this installation's stable references:

  • two Cache Rules for public assets and signed versioned comment reads;
  • one Cache Response Rule that strips hosting-added Set-Cookie only from those cache-safe responses;
  • one Configuration Rule that disables Rocket Loader for the Panel Comments hostname.

Reconnecting repairs changed or missing managed rules and leaves matching rules untouched. Removal deletes only those four references. It does not alter DNS records, SSL/TLS mode, WAF rules, HTTP/3, compression, nameservers, zone-wide settings, or the separate sites that embed Panel Comments. Manual copyable expressions remain on the Optimization page for operators who do not want to create a private OAuth client.

Public discussion GETs become shared-cache eligible only when the widget supplies a signed rv version. Personalized bootstrap, private state, ticket, account, and write responses remain no-store. Keep the full query string and Origin in the Cloudflare cache key.

Updating

  1. Create and verify a backup.
  2. Unpack the release over a staging copy or beside the current directory.
  3. Preserve panel-config.php and panel-content/.
  4. Run php bin/panel migrate and php bin/panel doctor.
  5. Replace the application files and run php bin/panel cache:clear.

For a 0.1 installation, run php bin/panel upgrade:layout before exposing the old application root. It converts the legacy config/key/state and wraps in-root logs and backups. Never replace the generated master key independently of the database.