What you operate

Product capability

• Images, PDFs, local/hosted video and audio
• Live/snapshot websites and code mockups
• Contextual comments, voice notes, attachments
• Versions, batches, advanced compare
• Workflows, Guided Review, quality checks
• Protected delivery, approvals, evidence exports
• Intake, automation, planning, Insights
• API, webhooks, OIDC, privacy, audit controls by license

Use the right manual

This manual is self-contained for operators and users. If your workspace is on proofbetter.io and you do not administer its server, use the hosted manual.

Minimum requirements

Choose a self-hosted license

Confirm the published catalog and agreement before purchase. Each annual key is for one installation and binds to the first installation ID/domain.

Pre-install checklist

• DNS resolves to the intended server and a valid TLS certificate is active.
• Empty MySQL/MariaDB database and least-privileged application user are ready.
• Archive checksum and unzip -t pass before extraction.
• .htaccess, config/.htaccess, and storage/.htaccess will be preserved.
• Transactional email credentials and DNS-authentication plan are ready.
• Off-server recovery destination and five-minute cron access are available.
• Optional license key is stored securely for installer entry.

Upload and extract

1. Verify the archive.

   Compare its published SHA-256 checksum and run unzip -t proofbetter-v3.0.0-server-install.zip.

2. Extract into the HTTPS document root.

   Prefer SFTP. Preserve hidden files, assets/vendor/pdfjs/, and vendor/.

3. Set conservative permissions.

   Use directories around 0750 and files 0640/0644 as the host requires. Never use 0777.

4. Allow PHP to write private configuration and storage.

   Make config/ and the required storage/ subfolders writable by the PHP user.

Run the protected installer

1. Open https://your-host.example/install.php.
2. For a remote request, retrieve storage/.install-key through SFTP/FTP or the hosting file manager and paste the one-time value into the unlock screen. Localhost and CLI setup do not require it.
3. Enter the empty database host/name/user/password, canonical HTTPS URL, organization, first administrator, and optional annual license key.
4. Review preflight, then install. The app writes protected config/config.php, creates/migrates the schema, and seeds only required records.
5. Sign in, verify Home, and immediately remove or rename install.php after acceptance.

Writable storage areas

ProofBetter uses uploads, previews, derivatives, comment-attachments, captions, snapshots, branding, social, mail, and backups. Missing feature folders are created with private permissions when first used.

Local evaluation only

cd /path/to/proofbetter
php -S 127.0.0.1:8787 router.php
# Open http://127.0.0.1:8787/index.php?r=login

Local preview uses the bundled SQLite demo database only for development. Production should use MySQL/MariaDB and HTTPS.

Complete the launch checklist

• Workspace name, locale, time zone, retention, and interface mode saved.
• Email provider configured; test message delivered and authenticated.
• Brand preset/colors and client-facing logo verified on desktop/mobile.
• Operations system check returns the expected six dependencies.
• Full-site recovery package created, verified, preflighted, and copied off server.
• Five-minute cron scheduled under the same PHP/runtime context.
• Protected guest review tested with download off and verification on.
• install.php removed/renamed and direct storage/config access denied.

Use starter data only on an empty workspace

Settings → Maintenance → Starter demo package adds two fictional clients, two projects, two proofs, and guided comments. It refuses to install over existing work. The guarded workspace reset creates and verifies a full recovery package before preserving the current administrator and clearing workspace data.

Home, My reviews, and search

Home shows launch readiness, proof status, attention filters, and activity. My reviews is the focused reviewer queue. Press Ctrl/Cmd + K for quick actions and global search across accessible proofs, comments/transcripts, projects, and clients.

Create the hierarchy

1. Create the Client with primary contact details.
2. Create a Project, select the client, and set owner/status/schedule.
3. Create the Proof with title, reference, due date, workflow, context, tags, and custom fields.
4. Add one or more Assets, then version each asset independently.

Role boundaries

Create the proof container

1. Choose New proof.

   Open Home or Proofs.

2. Enter metadata.

   Title, project, due date, workflow, and reviewer context.

3. Choose Upload, Media, Website, or Code.
4. Create and inspect.

   Verify the source, stage, permissions, and preflight.

Source reference

Website Review setup

1. Open Settings → Website review.
2. For a live authorized staging site, copy the generated Review setup script before </body>, publish, and reload the proof.
3. For static copies, confirm the worker status reads ready, enable the feature, then queue a capture.
4. Use Interact to operate, Review to inspect marks, and Mark up to draw.

Visual markup

1. Choose Pointer to select existing markup or Pin, Rectangle, Arrow, Freehand, or Text highlight to create it.
2. Choose a color, mark the exact target, and write the associated comment.
3. Add mentions, validated links, files, or an audio note; set label/priority/assignee/due date when authorized.
4. Post, then click the card or mark to verify two-way navigation.

Replay GIF

Media-specific controls

• PDF: scroll/page jump, rotation, measurement, text interaction, page-anchored marks, JSON/XFDF/FDF import.
• Local video: play/seek/volume/speed/fullscreen, frame step, SMPTE, J/K/L, Pause + comment, time ranges and looping, VTT/SRT captions.
• Local audio: waveform and keyboard seeking, range comments, Pause + comment without irrelevant frame controls.
• Hosted media: synchronized YouTube/Vimeo; supported Spotify/SoundCloud APIs; selected-time fallback where exact provider control is unavailable.
• Website/code: Interact, Review, Mark up; bridge anchors live-site marks; snapshot mode gives full-page scroll-safe markup.

Voice notes and transcription

Recording requires HTTPS or localhost. Live browser transcription depends on browser support. Optional post-recording transcription sends the temporary validated audio to the configured fixed provider endpoint, returns editable text, and does not retain the transcription upload. The reviewer can listen, edit, remove, or post.

Versions and batches

1. Select the asset, then Add proof source for its next version.
2. Use Add asset for another batch item; mark it required or optional.
3. Review open feedback and use Carry open comments only for issues that still apply.
4. Use Side, Overlay, Swipe, Blink, Difference, or synchronized local-media compare.

Workflow templates

1. Create a template, then add/reorder/remove stages.
2. Choose sequential/parallel behavior, deadlines, reminders, locks, manual/automatic handoff, and completion.
3. Configure view/comment/decide/manage/download permissions per reviewer/stage.
4. Assign the template to a proof. Later template edits do not rewrite that proof’s saved stage history.

Guided Review and quality

Set Guided Review globally under Interface or override it per proof. Reviewers see overview, required/optional progress, resume state, feedback context, and final decision destination. Editors can preview without impersonation. Preflight, reviewer-specific checklists, decision reasons, quorum, and blocking rules keep approval explicit.

Replay GIF

Comment lifecycle

Reply, react, resolve, reopen, edit with revision history, relate dependencies, bulk-manage, assign, prioritize, and set due dates. Comments can include protected files, validated links, audio, transcript text, and precise media/page/location context.

Decision and evidence

1. Complete required checklist items and address blockers.
2. Choose Make decision and select an allowed result/reason.
3. Supply a note when the reason requires it and confirm.
4. Export the review summary, approval CSV/print view, completion PDF, or completion ZIP manifest.

Send a protected review

1. Choose the proof and version.
2. Enter recipient, expiry, and message.
3. Choose watermark, email verification, and download permission.

   Original download is off by default.

4. Send, verify delivery, and test in a private window.

Intake and automation

1. Create a request form with only essential required fields and share its protected public URL.
2. Review a submission, select client/project/template, and convert it into a proof.
3. Use proof templates for workflow, checklist, due offset, priority, tags, custom fields, and reminders.
4. Use narrow automation conditions and inspect job history before retrying.
5. Use expiring read-only API tokens, HMAC-signed outgoing webhooks, or protected inbound endpoints—never administrator credentials.

Reports and Insights

Reports status/client segments open their underlying proofs. Insights exposes approval cycle, comments per proof, versions per proof, on-time completion, client workload, reviewer throughput, and completion exports. Every detail view supports role-scoped search, status filtering, proof navigation, and formula-safe CSV.

Workspace and brand

Set organization name, locale, time zone, retention, Simple/Advanced interface, Guided Review default, upload sources/limits, checklists, decision reasons, and sharing metadata. Brand presets and three focused color roles flow to app/email output; contrast guards reject unreadable combinations. Social cards accept validated 1200×630 imagery while review pages remain no-index.

Users and permissions

1. Invite the email and assign Administrator, Manager, Editor, Reviewer, or Client.
2. Client requires one client workspace; editors/reviewers need explicit visible proof assignment.
3. Grant view/comment/decide/manage/download individually, using inherited client/project rules only where predictable.
4. Disable the account or revoke sessions when access ends.

2FA, SSO, privacy, and governance

• Enable TOTP and store eight recovery codes off-browser; optionally require 2FA for the workspace.
• OIDC company sign-in uses authorization code, PKCE, state, nonce, verified email, invited-account matching, and SSRF-safe public HTTPS discovery/targets.
• Personal data export and confirmed deletion obey deletion windows and legal holds.
• Support access is explicit and time-limited. Audit events are tamper-evident and retained by policy.

Choose a delivery path

Configure and test

1. Open Master settings → Email delivery.
2. Choose the provider and enter sender identity plus required secrets. Leave a secret field blank later to keep the encrypted saved value.
3. Optionally configure SMTP fallback after API/Microsoft failure; test primary and fallback independently.
4. Publish SPF, DKIM, and DMARC for the From domain.
5. Send a test to a monitored inbox and verify delivery, authentication results, reply behavior, and sanitized outbox status.
6. Configure signed provider events where supported and monitor bounce/retry activity.

Failure behavior

A primary API/Microsoft failure can retry through configured SMTP once. If both fail, the outbox records a sanitized error and uses the normal bounded retry delay. Never expose raw provider responses containing secrets to workspace users.

Schedule the runner

*/5 * * * * /usr/bin/php /absolute/path/to/proofbetter/cron.php

# Run once while testing:
/usr/bin/php /absolute/path/to/proofbetter/cron.php

Use the production PHP binary, user, environment, and file permissions. Alert on non-zero exit and inspect the hosting/PHP error log plus Operations.

Install static website capture

cd /absolute/path/to/proofbetter/workers
PLAYWRIGHT_BROWSERS_PATH=0 npm install
PLAYWRIGHT_BROWSERS_PATH=0 npx playwright install chromium

1. Confirm Node.js 20+, npm, and a compatible Chromium environment.
2. Run setup under the same server user that cron uses.
3. Open Settings → Website review and confirm Static Copy reads Ready.
4. Queue a public HTTPS capture and verify it becomes Snapshot Ready.

Configure FFmpeg and transcription

FFmpeg is optional; when unavailable, authorized source streaming remains. Verify its path/codecs and regenerate derivatives after correcting a failure. Post-recording transcription is optional: store the provider key encrypted, choose model/language hint, test a short recording, and understand the 25 MB validated-audio and session-rate boundaries.

Supervise jobs

Jobs track retry limit, progress, worker lock, heartbeat, idempotency key, dead-letter time, and cancellation time. Correct the dependency before manual retry. Exhausted jobs move to Needs attention; dismiss only after the underlying work is intentionally abandoned.

Enable only after readiness

1. Configure email, SPF, DKIM, DMARC, and a monitored sender; send a real test.
2. Schedule cron.php every five minutes and verify protected storage is writable.
3. Open Plan & billing → Commercial controls.
4. Set the demo sales inbox and post-demo offer delay, percentage, and validity. Enable the offer and Private 30-minute demo, then save.
5. Submit a controlled address, validate the six-digit code, confirm the timer begins after acceptance, then expire the workspace. Verify cleanup and the one recipient-locked offer at the configured delay.

Lifecycle and data boundary

The demo request retains a limited name/email/status and operational tombstone after cleanup to enforce the one-use rule. It contains no active review content. Promotion records retain an HMAC and scope; the email outbox contains the displayed code under normal email retention.

Control discounts and special access

Use Plan & billing → Discounts & secure access codes. Presets create 10%, 15%, 20%, 25%, or 30-day Studio offers; Custom settings can restrict family, plan, interval, recipient, dates, and total uses. Generated plaintext is shown once. Disable a code instead of deleting its history. PayPal discounts are verified against the configured Plan ID and exact server-calculated override, while free-access codes create auditable, expiring complimentary grants.

Monitor cleanup

The five-minute cron run reports demo records cleaned or awaiting retry. Remote object deletion failures remain cleanup_pending and retry on later runs. Investigate repeated pending records before disk or object-store usage grows.

Protected local storage

• Keep storage/ blocked from direct web access; files stream only through authorization-checked routes.
• Back up the full tree with the database and application version; relationships depend on both.
• Confirm reverse proxies pass Range for local audio/video seeking.
• Monitor uploads, previews, derivatives, captions, snapshots, branding, social media, attachments, mail previews, and backups separately.

S3-compatible storage

1. Open Master settings → Platform and enter public service endpoint, region, bucket, and protected credentials.
2. Run the object-storage readiness test before switching.
3. Confirm per-client keyring/metadata-scrubbing policy and quotas.
4. Upload, stream, and delete a non-confidential test object; verify recovery includes required configuration.

Custom domains

1. Create DNS for the intended hostname and terminate valid HTTPS.
2. Add the domain in Platform settings and complete verification.
3. Confirm the organization mapping; hostname never replaces normal authorization.
4. Test login, protected file streaming, guest review, email links, and webhook/API base URLs.

Choose a package scope

Packages include a machine-readable manifest, per-file SHA-256, archive checksum, and recovery guide. Server config, application key, mail previews, Node modules, nested backups, and other excluded runtime material are handled by documented secure procedures.

Create, verify, and take off server

1. Open Settings → Maintenance and create a Full-site package.
2. Choose Verify. Do not trust the package until every manifest entry passes.
3. Run Restore preflight and read its included RECOVERY.txt.
4. Download the private no-store archive to encrypted off-server storage.
5. Configure daily/weekly scheduled packages and retention. Manual packages are never silently pruned.
6. Optionally configure encrypted WebDAV/S3-compatible delivery with a separate 16+ character passphrase stored outside the server.

Rehearse recovery

At least quarterly, restore into an empty HTTPS staging root and empty database, sign in, open multiple proof types, verify protected media/comments/email/cron, and record the restore drill. Never discover missing extensions or credentials during an incident.

Move to another server

1. Build and verify a Full-site package.
2. Choose Move server.

   Download installer.php and the matching randomly named ZIP; store the one-time key privately. It is shown for one hour and the installer expires after seven days.

3. Prepare an empty destination.

   Empty HTTPS web root and empty MySQL/MariaDB database; never rename the ZIP.

4. Open the destination installer.

   Enter the key, confirm all preflight items, final URL, and new database details, then Verify and restore.

5. Accept and clean.

   Sign in, test proofs/media/comments/email/cron, then remove installer and uploaded ZIP immediately.

Upgrade beside the current release

1. Create, verify, preflight, and download a Full-site package.
2. Upload v3.0.0 into a new adjacent folder; do not overwrite the live folder.
3. Copy only protected production config/config.php and the complete storage/ tree.
4. Point a staging hostname at the new release. Opening the app runs idempotent database migrations.
5. Run smoke/security/commercial/release checks, test all media and roles, then switch traffic.
6. Keep the old version folder and verified package through the rollback window. Roll back application and data consistently if required.

Run the six dependency checks

1. Open Operations and choose Run system check.
2. Review Application, Database, Background jobs, Email delivery, Protected storage, and Recovery.
3. Open any incident created by a warning; fix the dependency, then rerun. Healthy checks automatically resolve matching incidents.
4. Review queued/running/retry/Needs attention jobs and intervene only after diagnosing the dependency.

Replay GIF

Release readiness

Open Release Readiness and confirm application version, verified recovery, schema/migration preflight, rollback plan, and the complete deployment checklist. The feature does not perform an unsafe automatic update; it makes the prerequisites visible.

Activate

1. Retrieve the key only from the authenticated billing center after verified Stripe one-time completion or confirmed PayPal capture.
2. Enter it during install or in the protected license configuration flow.
3. Confirm the HTTPS activation endpoint, random installation ID, and canonical domain.
4. Run cron and confirm the last successful license validation appears in operational status.

Renew or move

Annual renewal extends updates and validity under the customer agreement. A server/domain move requires an authorized activation reset plus the verified backup/migration procedure. Keep the full key out of tickets, email, logs, screenshots, and client-visible settings.

Short activation outages

Define the contractual validation-grace policy before production. A brief activation-service interruption should not unexpectedly remove client review access; investigate connectivity and last-success time before resetting anything.

Production hardening

• Force HTTPS, keep HSTS, security headers, CSP, opener, permissions, and no-index protections intact.
• Block direct config/ and storage/ access; keep display_errors off.
• Use random application/database keys, least privilege, encrypted credentials, and restrictive file ownership.
• Do not add unsafe-eval to the main CSP; the Spotify frame has its own narrow policy.
• Keep signed webhook/OTP/reset/rate-limit boundaries and private-network target validation enabled.
• Require 2FA for privileged staff and use time-limited support access.

Cadence

Common failures

Evidence to collect

• UTC/local time, route, user role, proof reference/version/source type
• Relevant PHP/web-server/cron/job error without secrets
• Operations dependency state and incident/job ID
• Browser/OS and reproducible steps
• Package/application/database version and recent change
• Screenshot with unrelated client data redacted

Useful commands

# Verify PHP and required modules
php -v
php -m

# Run scheduled work once
php /absolute/path/to/proofbetter/cron.php

# Test the clean archive
unzip -t proofbetter-v3.0.0-server-install.zip

# Local application smoke suite (source tree only)
php tests/smoke.php

Custom deployments

Use a root HTTPS installation on port 443 with a device-trusted certificate and the mobile-connect update. An anonymous GET to index.php?r=mobile.capabilities must return application/json with product proofbetter and mobile_api 1, without redirecting. Back up and merge the new route into the existing entry point before authenticated routing; no database migration is required. Preserve native-client purchase suppression and the compact login layout. ONBOARDING-30006.md documents that compatibility endpoint; the newer MOBILE-REVIEW-30007.md documents the review patch.

In the app, choose Settings → Connect to your server, enter the administrator-supplied address, Check server, then confirm Sign out and connect. Switching clears old local sessions, cache, history and device unlock before selecting the new exact origin. It does not delete server accounts. Subdirectories, alternate ports and IPv6 literals are not supported. Never relax TLS. Local or VPN hosts must already be reachable; allow local-network permission if prompted and select the Android 17+ local-network option for LAN hosts. No scanning or VPN setup is performed.

Mobile markup and recording

Deploy the matching index.php, app/views.php, app/bootstrap.php, assets/js/app.js and assets/css/app.css together. The phone review provides visible markup tools and Proof / Comments / Decide navigation. Failed posts retain the current draft and recording; replies return to their saved location. No schema migration is needed. Native build 30007 adds the corrected signed-in toolbar and Android microphone consent/permission.

Keep HTTPS and microphone=(self) enabled. The media-src policy includes self and blob: so local voice previews can play without opening remote media origins. Post-recording transcription needs an administrator-configured provider key; test recording, preview playback and transcription separately. Live recognition is browser-dependent. Unposted audio stays only in the current page, not durable offline storage. Do not claim transcription readiness while its provider is unconfigured.

Push configuration and verification

Custom-server connections support the authenticated in-app activity inbox. This release's remote push integration is for ProofBetter Cloud only: its APNs/FCM tokens and private keys are not shared with self-hosted operators, and Cloud alerts are disabled while a custom server is selected. A separately branded remote-push distribution needs its own coordinated identity, signing, credentials and server integration. Local notification tests do not prove remote delivery. Keep signing and push keys outside public packages and webroots.

Updates and recovery

Web changes load on the next workspace reload. Native changes require a new signed app build with an increased platform build number. Preserve the Android upload key and Apple signing materials separately from deployables; back up them privately. Server recovery must include the database, uploads, configuration, and mobile token/outbox tables. Treat device tokens and backups as confidential.

The review-safety update adds report/block moderation and verified account erasure. Administrators should review Safety center promptly and monitor pending erasure file cleanup. Keep current deletion receipts independently of old archives. New migration kits reject stale or missing erasure checkpoints and leave destinations quarantined for operator activation. Stop source writes and workers, reconcile the current receipts and follow the supplied RECOVERY-AND-ERASURE.md before switching traffic. Old downloaded installers cannot be retroactively revoked and must not be used for activation. Source loss requires isolated, manually verified recovery; no automatic replay of historical erasures is provided.