F fyuhls
Documentation

fyuhls v0.1.2 Documentation, Installation Guide, and Admin Setup

This page is intended for site owners installing and configuring fyuhls on Linux-based hosting. It covers the base install flow, storage setup, core admin sections, and the main support paths included in the script.

For the object-storage model, upload lifecycle, deduplication behavior, and API direction, see the fyuhls wiki pages Storage Nodes, Uploads and Downloads, and Public API.

Installation Steps for fyuhls

  1. Confirm the server meets the base requirements first: Linux hosting, PHP 8.2+, MySQL or MariaDB, PDO MySQL, OpenSSL, cURL, sockets, and clean URL support such as Apache mod_rewrite.
  2. Adjust your PHP upload limits before launch if you plan to support larger files. A practical baseline for 2GB+ uploads is upload_max_filesize = 256M, post_max_size = 300M, max_execution_time = 3600, and memory_limit = 512M.
  3. Extract the downloaded package on your computer first so you can see the full project layout.
  4. Create an application folder above your public web root and upload the full script there, including public, src, config, storage, vendor, and docs.
  5. Point your domain or subdomain document root to the installed project's public/ directory. In cPanel or DirectAdmin this usually means changing the path to something like /home/yourusername/domain.com/fyuhls/public.
  6. Create a MySQL database and a MySQL user with access to that database before running the installer. The installer does not create them for you.
  7. Visit /install.php and complete the install form with database credentials and admin account details. The installer now generates a safe hidden config path outside the webroot automatically and shows it for reference.
  8. After install, run /post_install_check.php to verify the environment.
  9. Remove install.php, post_install_check.php, and the schema file after setup if you prefer a hardened surface. The app blocks them after install, but removal is still best practice.
  10. Configure cron, storage, email, packages, uploads, downloads, monetization, security, and SEO in the admin area.

Important Notes

  • The installer expects the database and database user to exist already.
  • The script targets Linux-based hosting environments, not Windows hosting.
  • The hidden config path is generated automatically outside the public web directory. Keep that file outside the webroot and readable by PHP.
  • Use the post-install check page before opening the site to real users.
  • If SMTP is configured, test it from the admin area before relying on email workflows.
  • If you plan to use rewards or payouts, review monetization and cron settings after the install finishes.
  • If you plan to accept very large files, raise your PHP upload and execution limits before launch.

Control Panel Install Notes

  • cPanel: Use Domains to update the document root so it points to the installed project's public/ directory, such as /home/yourusername/domain.com/fyuhls/public.
  • DirectAdmin: Use Domain Setup to change the public directory or document root to the installed project's public/ directory, such as /home/yourusername/domain.com/fyuhls/public.
  • If your panel auto-prefixes paths, verify the final saved path in the file manager before continuing.
  • The most common install mistake is saving the wrong folder path. Double-check the exact final path in your hosting file manager.

Installer and Security Notes

  • Point the domain to the installed project's public/ directory, such as /home/yourusername/domain.com/fyuhls/public.
  • Keep the generated hidden config file outside the public web directory whenever possible.
  • If you need to reinstall, remove config/database.php before running the installer again.
  • Do not share the encryption key stored in the hidden config file. If it is lost, encrypted data cannot be recovered.

Recommended Upload Limits for 2GB+ Files

  • upload_max_filesize = 256M
  • post_max_size = 300M
  • max_execution_time = 3600
  • memory_limit = 512M
  • upload_max_filesize: the largest single upload request PHP will accept. With fyuhls this acts as the maximum chunk size, not the final file size.
  • post_max_size: the maximum full POST request size PHP will accept. Keep it a bit larger than upload_max_filesize.
  • max_execution_time: the number of seconds a PHP request can run before it times out. A higher value helps slower large uploads finish cleanly.
  • memory_limit: the maximum RAM a PHP process may use while handling uploads, validation, thumbnails, and other request work.

fyuhls supports chunked uploads, so these PHP values are request and chunk baselines rather than the final file-size limit. The actual upload ceiling can still be 2GB, 10GB, or higher depending on your package limits, script settings, and available storage.

Document Root Reminder

The most common installation mistake is pointing the domain at the wrong folder.

  • The project root should stay outside the public web root when possible.
  • Point the domain to the installed project's public/ directory, such as /home/yourusername/domain.com/fyuhls/public.
  • If your host cannot point the document root properly, fix that before running the installer.

Suggested First-Run Checklist After Installation

Task Why It Matters
Check System Status Confirms writable paths, PHP extensions, database health, and schema status.
Review Config Hub Lets you set site rules for uploads, downloads, storage, email, SEO, cron, and security.
Create Packages Controls upload limits, storage limits, remote upload access, and user plan behavior.
Configure File Servers Prepares local or object-storage destinations before user uploads begin.
Adjust Upload Limits Prevents large uploads from failing because PHP or hosting limits are still too low.
Test SMTP Needed for verification emails, password resets, and support workflows.
Review Rewards Settings Required if you want PPD, payout methods, or affiliate-driven monetization.
Add Cron / Heartbeat Keeps cleanup, maintenance, rewards processing, and queue-driven tasks running on schedule.
Review SEO Settings Lets you configure titles, metadata templates, sitemap output, robots rules, and verification codes before search engines crawl the site.

Cron and Automation

fyuhls uses a single heartbeat runner for cleanup, maintenance, queue work, and scheduled tasks.

  • Add this cron entry and run it every minute: * * * * * php /home/yourusername/fyuhls/src/Cron/Run.php
  • Without the heartbeat, some cleanup, queue, and monetization tasks will not process automatically.
  • Review the Cron tab in the Config Hub after install so the guidance matches your real server path.
  • The multipart upload system also depends on cron for abandoned upload sessions, stale reservations, checksum jobs, and storage reconciliation.

Email and Rewards Setup

  • Configure SMTP from Admin > Config Hub > Email before relying on password reset or verification emails.
  • Use the built-in test connection and test email tools after saving your mail settings.
  • Configure payout methods, thresholds, rates, and anti-abuse rules from Admin > Config Hub > Monetization.
  • Rewards and affiliate features can stay disabled until you are ready to expose them on the frontend.

Config Hub and Daily Operations

Most day-to-day behavior is controlled from the Config Hub instead of by editing files directly.

General Settings

Use the General area to control the site name, base URL, registration behavior, verification defaults, and maintenance mode.

  • Keep the base URL accurate and avoid a trailing slash mismatch.
  • Review registration and verification defaults before opening the site publicly.
  • Use maintenance mode during major setup, migration, or storage work.

Upload Controls

Adjust guest upload policy, allowed extensions, chunking behavior, duplicate handling, popup flows, and remote-upload rules from one place.

  • Confirm guest upload behavior matches your public landing flow.
  • Review deduplication and chunk sizing before pushing large-file traffic.
  • Test one small, one large, and one duplicate upload after changing upload rules.

Download Rules

Control account-required downloads, guest restrictions, active tracking, delivery paths, wait rules, and concurrency-sensitive behavior.

  • Match delivery mode to your server stack and payout model.
  • Turn on active tracking when package download concurrency matters.
  • Retest logged-in and guest downloads whenever you change delivery or protection rules.

Security Controls

Security settings handle rate limits, trusted proxies, VPN and proxy checks, captcha placement, and two-factor policy.

  • Cloudflare users should sync trusted proxy IPs so the app sees real visitor addresses.
  • Review login and registration throttles before launch.
  • If everyone appears to share one IP, check your proxy trust configuration first.

Email Operations

SMTP setup, test delivery, and template editing all live in one place so verification, recovery, and payout emails stay manageable.

  • Run the built-in connection test before relying on email-driven workflows.
  • Use a sender address authorized by your provider to reduce spam issues.
  • Review mail queue behavior if users report delayed or missing emails.

Storage and Delivery

Add or review file servers, choose delivery methods, test connectivity, and decide how uploads and downloads should route across storage nodes.

  • Use active, read-only, and disabled states intentionally during migrations or cutovers.
  • Test delivery after any credential, endpoint, or handoff change.
  • Keep object-storage CORS aligned with multipart upload needs.

Updater and Releases

Use the built-in updater preview to review what will change, then apply updates with automatic backups and quarantined stale files.

  • Run a preview before applying a release on production.
  • Review the update report and quarantine list if a file was locally modified.
  • Keep your GitHub repo setting pointed at the official fyuhls release source.

Monetization and Rewards

Configure rewards, affiliate behavior, withdrawal methods, fraud thresholds, and package-facing monetization features from the monetization tab.

  • Review payout thresholds and methods before exposing withdrawals to users.
  • Keep rewards fraud settings aligned with your traffic quality tolerance.
  • Disable rewards-related frontend features entirely if your site is storage-only.

SEO Controls

Manage homepage metadata, page templates, sitemap behavior, robots rules, verification codes, and custom head content without editing templates.

  • Set titles and descriptions before search engines crawl the public site.
  • Verify sitemap and robots output after launch-domain changes.
  • Use the built-in health scoring to catch weak defaults.

Cron Jobs and Heartbeat

Use the cron area to confirm the central heartbeat path, verify the runner is healthy, and support cleanup, queue work, maintenance, and background processing.

  • Run the heartbeat every minute on production installs.
  • Check cron status first when remote jobs, mail, cleanup, or payout work appears stuck.
  • Keep the path examples updated to your real server environment.

Admin Area Overview and Configuration Guide

The main admin navigation is built around daily operational areas instead of separate modules.

Bug Report

Open the support area used for technical bug reporting, sanitized support bundles, update checks, and troubleshooting exports.

Dashboard

Shows system summaries, recent activity, quick diagnostics, and shortcuts into the rest of the admin area.

Packages

Defines user limits and capabilities such as upload size, storage quota, and access to premium features.

Users

Manage accounts, package assignments, verification state, balances, and account-level restrictions.

Files

Review uploads, moderation status, ownership, and file details from one central listing.

Live Downloads

Monitor active transfers and spot current usage or abuse patterns in near real time.

Withdrawals

Review and process reward withdrawals when monetization is enabled.

Rewards Fraud

Inspect held earnings, review risk signals, score suspicious traffic, and clear, hold, or reverse questionable reward activity.

Plugins

Reserved for optional webmaster add-ons. Core systems such as rewards and 2FA are no longer treated as plugins.

Config Hub

Central home for general settings, security, email, storage, uploads, downloads, monetization, SEO, and cron guidance.

Resources

Collect partner links, affiliate resources, and operator-facing third-party services that support monetization or infrastructure planning.

SEO Command Center

Manage titles, descriptions, canonicals, sitemap rules, robots.txt behavior, file-page templates, structured data, and verification tags without editing templates by hand.

Requests

Work through contact messages, abuse reports, and DMCA-related requests from a shared review area with queue counts and operational follow-up.

System Status

Health checks, logs, delivery diagnostics, and support export tools for troubleshooting.

Documentation

Access the internal admin docs page and page guides that explain each operational section, setting group, and system workflow.

SEO Command Center

fyuhls includes a built-in SEO area under the Config Hub for admins who want better indexing control without editing theme files.

  • Homepage title, description, H1, and intro overrides
  • Global title and description templates
  • Public file-page title and description templates
  • XML sitemap generation and file-page sitemap inclusion
  • Robots.txt rules for auth pages and internal member pages
  • Structured data for homepage software and FAQ markup

Verification and Search Tools

The SEO area also handles practical search-engine setup tasks that usually require manual theme edits.

  • Google Search Console verification token
  • Bing Webmaster verification token
  • Custom head-code injection for approved analytics or metadata
  • Health scoring for missing metadata, weak defaults, or disabled sitemap rules
  • Built-in guidance on what to fix before launch

Theme Overrides and Branding

fyuhls supports safe frontend overrides so you can brand the site without editing core templates that may change across updates.

  • Copy view files into themes/custom/ when you need a durable override path.
  • Keep branding-level changes out of core files whenever possible.
  • Use admin settings for metadata, text, and behavior changes before editing templates.

Monitoring and Diagnostics

System Status and the built-in support tooling are meant to surface environment issues before they become user-facing failures.

  • Check writable paths, PHP extensions, and schema health before launch.
  • Use delivery and connection tests before assigning production traffic to a storage node.
  • Prefer support bundle exports over raw server-file sharing for troubleshooting.

Storage and File Servers

fyuhls supports local storage, Cloudflare R2, Backblaze B2, Wasabi, and generic S3-compatible providers.

  • Each file server can be marked active, read-only, or disabled.
  • Read-only servers are useful when you want to keep old files downloadable while preventing new uploads there.
  • Use the delivery and connection tests before assigning real traffic to a new storage node.
  • Keep object-storage credentials safe and only store them inside the app's encrypted settings and server configuration paths.
  • The recommended long-term direction is one multipart object-storage path shared across B2, Wasabi, R2, and generic S3-compatible providers.
  • Direct browser multipart uploads also require bucket CORS rules that allow your site origin, `PUT` requests, and expose the `ETag` header.

Delivery Modes

Choose a delivery mode that matches your server stack and reward model.

  • PHP delivery is the most universally compatible option.
  • Nginx completion tracking is the strongest option if you need more reliable PPD completion verification.
  • Direct object-storage delivery can be faster, but PPD may count from download start rather than verified completion depending on the delivery path.
  • CDN redirects are best for public object-storage files when the CDN fronts the same bucket key layout as fyuhls. Private files should stay on signed-origin delivery.

Upload Architecture

fyuhls supports chunked uploads today, but the recommended long-term path for larger installs is direct multipart upload to object storage.

  • Chunking keeps large uploads more reliable and easier to retry.
  • Large production sites should avoid rebuilding full uploads inside PHP where possible.
  • The preferred object-storage path is browser-to-storage multipart transfer with app-managed upload sessions.
  • Background jobs should handle follow-up work such as checksums, scans, and media processing.

Quota and Deduplication

For stronger production behavior, uploads should reserve quota before completion and rely on app-managed checksums rather than provider-specific ETags.

  • Reserve expected bytes at session start, then commit or release them when the upload completes, fails, or expires.
  • Use SHA-256 plus file size as the practical integrity and deduplication key.
  • Store provider ETags for diagnostics, not as the main cross-provider integrity contract.
  • Reuse stored objects safely when checksum and size match an existing stored file.

Public API Overview

The current API layer follows the same upload, quota, and delivery policy used by the main application.

Current API Scope

The current public API now supports account-bound API tokens, multipart upload sessions, a managed-upload shortcut for third-party tools, owner-scoped file metadata, and application-signed download links.

  • Account-bound API token authentication
  • Multipart part-signing, reporting, completion, and abort flows
  • Managed upload setup in one response for easier integrations
  • Owner-scoped file metadata lookup
  • Application-signed download-link generation
  • Shared quota, validation, and delivery rules with the web UI

Full API Guide

The complete API reference now lives on its own page with endpoint descriptions, request flow, production notes, and usage guidance for each supported API feature.

Open API Documentation

Rewards and Payouts

Rewards and payouts are part of the core script. Admins can enable or disable them from the Config Hub.

  • When rewards are disabled, related frontend pages and routes are hidden or gated.
  • Affiliate behavior depends on rewards being enabled.
  • Withdrawal methods and payout notes are stored through the app's encrypted field handling where sensitive data is involved.

Security and 2FA

Two-factor authentication is also part of the core script and can be controlled from the security settings area.

  • Use email verification and login controls before opening registration publicly.
  • Review proxy and VPN policies carefully so public routes remain usable while abuse is still controlled.
  • Use the support bundle export for sanitized troubleshooting instead of sending raw logs around.

Production Best Practices

Area Recommended Direction
Primary Storage Use local storage for smaller installs and S3-compatible object storage for larger production sites.
Large Uploads Use multipart-friendly settings and keep PHP out of the bulk transfer path when possible.
Integrity Use app-managed SHA-256 checksums plus file size rather than provider-specific ETags.
Quota Control Reserve bytes before upload starts and release them automatically on failure or expiry.
Downloads Prefer signed redirects or CDN-backed delivery for object storage, with tracked proxy paths where accounting requires it.
Background Work Run cleanup, reconciliation, scans, and follow-up processing through the heartbeat cron and queued jobs.

Support and Troubleshooting

If a customer or site owner needs help, start with the built-in admin tools before digging into raw server logs.

  • System Status: checks health, paths, services, and visible errors.
  • Post-Install Check: confirms a fresh install is complete and the environment is usable.
  • Support Bundle: generates a sanitized diagnostic JSON export that can be downloaded or emailed.
  • Documentation: review the admin help guidance to make sure the current configuration matches your intended site behavior.

Common Problems

  • Database connection errors during install: verify the database, user, and granted privileges in your hosting panel first.
  • 404 errors on every page except the homepage: check that clean URLs are enabled and the document root points to public/.
  • Internal server errors after upload: confirm PHP 8.2+ is active and the writable storage paths still have correct permissions.
  • SMTP failures: verify the host, port, username, password, and authorized sender address in the Email tab.

If you are distributing the script to customers, keep this documentation page with the package so first-run admins have setup guidance immediately available.

Repository and Release Tracking

Use the GitHub repository for source access, release snapshots, and future updates. The built-in updater supports previews, backups, and quarantined stale files to make upgrades safer.

Open GitHub