Beta notice: fyuhls is still a beta release. You should expect errors, rough edges, and incomplete behavior. It is not intended to be treated as a fully polished or fully functional production website at this time.
If you find bugs or broken flows, please send them through the built-in Bug Report area using the sanitized error log export so the issue can be reviewed safely and reproduced faster. You can also e-mail logs to fyuhls.script@gmail.com and I will support best I can when available. Keep in mind, this is a passion project, not a full time job.
Welcome to the Ultimate High-Performance File Hosting Script. Built on a modern PHP 8.2+ MVC architecture, fyuhls is aimed at operators who want a self-hosted file hosting platform with real control over storage, packages, uploads, downloads, monetization, diagnostics, and admin operations.
- Generated unique per-install
app_keyvalues, added runtime warnings for older installs still using insecure defaults, and auto-rotated the key when the hidden config file is writable. - Hardened installer and trust-boundary behavior by enforcing HTTPS outside local development, generating safe hidden config paths automatically, and restricting hidden config targets to absolute
.phpfiles outside the webroot and config directories. - Tightened proxy, host, and URL trust handling so trusted base URLs, password reset links, verification links, payment/share links, secure-cookie behavior, and forwarded HTTPS detection no longer trust arbitrary request hosts or unsafe proxy headers.
- Revalidated authenticated users against the database on every request and moved maintenance-mode and VPN-block admin bypass checks onto that revalidated auth path.
- Strengthened plugin and upload safety by confining plugin autoload paths to the expected plugin base, requiring real MIME detection, and adding extra storage
.htaccessdefense-in-depth for legacy PHP handlers. - Standardized CSRF, validation, and other security-sensitive error exits onto proper HTTP status codes and shared 4xx handling, rotated CSRF tokens after successful verification, and limited CSRF debug logging to debug mode.
- Added direct endpoint throttling for signed/public downloads, abuse reports, forgot-password requests, contact and DMCA forms, plus an extra IP-wide login spray limit on top of the username-specific login limiter.
- Hardened payment and transfer edges with fresher Stripe callback validation, replay tracking, safer transaction transitions, and cleaner remote-upload errors that keep sensitive transport details in logs instead of user-facing responses.
- Whitelisted admin ad-slot keys, required clean absolute
https://CDN download origins, restricted configurable Nginx completion log paths to safe absolute log-style files with matching runtime validation, and limited updater downloads to trusted GitHub hosts. - Expanded default Apache hardening headers with Permissions-Policy, COOP/CORP, and X-Permitted-Cross-Domain-Policies, and moved HSTS delivery into
.htaccess.
- Reworked the one-click updater around a local manifest of core-owned release files, structured JSON preview/apply reports under
storage/cache/, and guarded overwrite backups understorage/update_backups/. - Added preview and apply flows that show pending updates, quarantine stale unchanged core files under
storage/update_quarantine/, and leave locally modified stale files alone instead of blindly overwriting or deleting them. - Tightened release archive handling by sticking to the latest release archive flow, validating ZIP entries before extraction, handling directory/file shape conflicts more safely during apply, and documenting an explicit
/storage/deny block in the Nginx example config.
- Refactored the public download page and download state pages onto a shared internal rendering path while keeping existing routes, signed-link behavior, and package-driven gating compatible with live installs.
- Moved shared download-page data preparation into a dedicated service and reusable partials so countdown, captcha, share links, ads, streaming blocks, and state messages can evolve together without rewriting the controller each time.
- Expanded bulk workflows with bulk copy, selection summaries, single-click public/private actions, and toast notifications with undo for move and trash.
- Improved in-page discovery and control with search, type/visibility/status filter chips, largest-first sorting, visible-item selection shortcuts, and keyboard shortcuts for search, trash, permanent delete, move, rename, select-all, and clear selection.
- Reduced full-page refreshes by letting trash, move, folder creation, and permanent delete update the current view live instead of forcing a reload.
- Added double-click inline rename, unified dropdown/context/mobile action handling, and fixed asset cache-busting by switching file-manager CSS and JS versioning from
time()tofilemtime(). - Added a sidebar storage quota bar with warning states near capacity, upgraded daily download bandwidth into a visual progress bar, and fixed trash handling so soft-deleted folders appear correctly and drag-out restore works as expected.
- Reworked the admin dashboard into a more action-focused control center with a new top-left default layout for Support and Diagnostics, cleaner widget spacing, and improved readability in dense cards like Top Content and System Automation.
- Added an Attention Needed strip and a What changed today summary for recent errors, overdue automation, moderation backlog, storage pressure, SMTP gaps, and daily movement.
- Made key operational metric chips clickable, added light healthy/warning/danger state styling, and introduced a Reset layout button to restore the default widget order and collapse state.
- Advanced Features (Beta)
- What You'll Need Before Starting
- Hosting Partnerships & Testing
- Server Requirements
- Configuring for Large Uploads (10GB+)
- Step 1 - Extract and Upload the Files
- Step 2 - Point Your Domain to the Application
- Step 3 - Create a Database
- Step 4 - Run the Installer
- Step 5 - Post-Install Configuration
- Safe Template Customization
- Troubleshooting
- Security Reminders
- Full-Coverage AES-256 Encryption: 100% of sensitive user data (IPs, Emails, Filenames, Payment Details) is stored using AES-256 encryption with a fresh random IV per value.
- Multi-Server Object Storage Architecture: Connect Local, Backblaze B2, Cloudflare R2, Wasabi, and generic S3-compatible nodes through one storage layer with setup guidance in the admin area.
- Direct Multipart Upload Pipeline: Large uploads use direct-to-storage multipart sessions instead of PHP-side chunk assembly, with resumable sessions, quota reservations, and signed part URLs.
- Public API + Personal API Tokens: Account-bound API tokens support multipart uploads, managed upload shortcuts, owner-scoped file metadata, and application-controlled download links.
- Core Rewards + Two-Factor Security: Rewards (PPD/PPS/Affiliate) and TOTP-based two-factor authentication are built into the script and can be enabled or disabled from the admin area.
- Centralized Email System: Professional transaction emails (Verification, Password Resets, Payments) with a built-in Mail Queue and Template Editor.
- Smart Task Scheduler: A centralized "Heartbeat" manager handles cleanup, security syncs, and maintenance from a single server cron.
- Trusted Proxy + Security Controls: Built-in proxy/IP hardening, VPN/proxy blocking, Cloudflare trusted proxy syncing, and admin-controlled security policies.
- High-Performance Delivery: Signed download redirects, optional CDN redirects for public object-storage files, and native support for X-Accel-Redirect (Nginx), X-SendFile (Apache), and X-LiteSpeed-Location (LiteSpeed).
- Sanitized Support Exports: Admins can generate a plain JSON support bundle with secrets and sensitive values redacted before sharing.
Estimated installation time: 15 minutes
| What You Need | Where to Get It |
|---|---|
A domain name (e.g. myfiles.com) |
Your domain registrar (PorkBun, CloudFlare, etc.) |
| A VPS or Shared hosting account | Your hosting provider |
| Your MySQL database details | You'll create these in Step 3 |
| SMTP Details (Host, Port, User) | Your mail provider (Postmark, Brevo, or cPanel) |
Developing a robust multi-server architecture requires extensive environment testing. If you have a spare VPS or a small-time package (even with very limited bandwidth) you'd like to donate for research and development, we would greatly value the contribution.
Are you an established hosting provider? Let's collaborate. We are building a curated list of "Certified Great" file hosting providers for our community and upcoming documentation. Partner with us to help set the industry standard for performance and reliability.
Linux hosting only. This project is intended for Linux-based shared hosting, VPS, and dedicated servers.
Your hosting account must support:
| Requirement | Minimum |
|---|---|
| PHP Version | 8.2 or higher |
| Database | MySQL 5.7+ or MariaDB 10.3+ |
| PHP Extensions | PDO, PDO MySQL, OpenSSL (Required), cURL, Sockets |
| Apache Module | mod_rewrite (enabled by default on cPanel/DirectAdmin) |
Your database and database user must already exist before you run the installer. Create them first in cPanel, DirectAdmin, or your server control panel and grant the user access to the database.
To support large file uploads, you still need sane PHP and web-server limits, but Fyuhls now uses a multipart direct-to-storage model for object-storage backends instead of rebuilding the full file inside PHP.
Recommended baseline for 2GB+ uploads:
upload_max_filesize = 256Mpost_max_size = 300Mmax_execution_time = 3600memory_limit = 512M
What these values do:
upload_max_filesize: the largest request PHP will accept for browser/session uploads and admin-side form actions.post_max_size: the maximum full POST request size PHP will accept. This should stay slightly larger thanupload_max_filesize.max_execution_time: gives the app enough time for upload-session orchestration, metadata work, and slower maintenance tasks.memory_limit: keeps enough RAM available for request handling, metadata extraction, and admin tooling.
These PHP limits are no longer the real ceiling for large object-storage uploads. With multipart uploads, the file bytes go directly from the client to the storage backend, so the final file size can be much larger than a single PHP request as long as your package limits, storage quotas, and backend capacity allow it.
For browser multipart uploads to work correctly, configure bucket CORS so your site origin can:
PUTGETHEAD
And expose:
ETag
Without that, direct multipart uploads and resume flows will fail even if the credentials are valid.
If you want a lighter starting point on smaller hosting plans, you can lower the chunk-related PHP limits, but for most real file-hosting installs a 2GB+ baseline is more practical.
1. Using php.ini (VPS/Dedicated):
Find your php.ini file (run php --ini at the server command line to locate it) and update the values above. Restart your web server (Apache/Nginx/PHP-FPM) after saving.
2. Using cPanel:
- Log in to cPanel.
- Search for Select PHP Version.
- Click the Options tab.
- Find the settings in the list and click to update them.
- Find the
.zipfile you downloaded. - Right-click it and choose Extract All.
- You should see folders like
public,src,config,storage,vendor, andmain.
Important: Do NOT upload the files into
public_htmldirectly. The files need to go in a folder abovepublic_htmlfor maximum security.
In your server's home directory (e.g., /home/yourusername/domain.com/), create a new folder called fyuhls or whatever you want.
Upload the entire contents of the extracted folder into /home/yourusername/domain.com/FOLDER MADE ABOVE/. When done, your structure should look like this:
/home/yourusername/domain.com/fyuhls/
public/ <-- this is the only folder your visitors should access
src/
database/
config/
storage/
themes/
vendor/
README.md
composer.json
composer.lock
LICENSE
nginx.conf.example
- Log in to cPanel and go to Domains.
- Find your domain and click Manage.
- Change the Document Root to:
/home/yourusername/domain.com/fyuhls/publicDepending on your hosting setup, you may only need to enter/domain.com/fyuhls/publicand it will update it to the full path for you. Check the final saved path in your file manager. - Click Save.
- Log in to DirectAdmin and go to Domain Setup.
- Click on your domain name.
- Find the Document Root (or Public HTML directory) and change it to:
/home/yourusername/domain.com/fyuhls/publicDepending on your hosting setup, you may only need to enter/domain.com/fyuhls/publicand it will update it to the full path for you. Check the final saved path in your file manager. - Click Save.
- In your control panel (cPanel/DirectAdmin), go to MySQL Databases.
- Create a new database (e.g.,
user_files). - Create a new database user with a strong password.
- Add the User to the Database and grant ALL PRIVILEGES.
- Open your browser and go to:
https://yourdomain.com/install.php - Follow the 4-step walkthrough to connect your database and create your Admin account.
- Pro Tip: In the Absolute Config Path field, enter a path completely outside of your public web directory (e.g.,
/home/yourusername/fyuhls_secure/config.php). This keeps your encryption keys off-grid.
Most day-to-day setup now lives in Admin > Config Hub.
- Open General to set the site name, registration behavior, and core public-site options.
- Open Security to configure login protections, IP controls, captcha, email verification, and built-in two-factor authentication rules.
- Open Email to configure SMTP, test outgoing mail, and edit your templates.
- Open Storage to add local or external file servers and choose your delivery method.
- Open Uploads and Downloads to set limits, chunking, wait times, direct-link behavior, and guest/free-user rules.
- Open SEO to manage titles, metadata templates, sitemap/robots output, and verification codes.
Fyuhls includes a public API with a dedicated frontend reference page and a matching static API reference.
Key API capabilities:
- Personal API tokens with per-scope access.
- Multipart upload session creation and managed upload shortcuts.
- Resume-friendly session inspection and part signing.
- Owner-scoped file metadata.
- Application-controlled download link generation.
Main references:
- Frontend API page:
/api - Static API reference:
main/api.html - Detailed wiki guide:
Public APIpage in the fyuhls wiki
Large-file production deployments should use the current default architecture:
- Client starts an upload session.
- Fyuhls reserves quota and creates multipart state.
- Client uploads parts directly to object storage.
- Client reports parts and completes the upload.
- Fyuhls issues signed download links and optionally redirects eligible public files through a configured CDN.
This keeps PHP out of the bulk file-transfer path for high-volume environments.
Rewards, affiliate, and payout settings are now part of the core script.
- Go to Admin > Config Hub > Monetization.
- Enable the reward models you want to use.
- Set your payout methods, rates, thresholds, and anti-abuse rules.
- If you do not want rewards or affiliate features visible on the site, disable them there and the frontend options will be hidden.
Configure your SMTP settings to enable account verification, password resets, and user notifications.
- Go to Admin > Config Hub > Email.
- Enter your SMTP host, port, and credentials.
- Use the Test Connection button to verify your setup.
- Customize your email templates directly in the editor.
If you use Nginx X-Accel-Redirect but want to pay users only for 100% finished downloads, add this to your Nginx site config:
location /protected_uploads/ {
internal;
post_action /api/callback/nginx-completed;
}To keep your site healthy and process scheduled jobs, cleanup, queue work, multipart session expiry, stale reservation release, checksum/reconciliation work, and maintenance, add this single entry to your server's Crontab (set to run every minute):
* * * * * php /home/yourusername/fyuhls/src/Cron/Run.php
If you need to hand logs to support or an automated agent, use Admin > Support Center or the Support Bundle card in System Status.
The export is:
- sanitized
- secret-redacted
- downloaded as a plain
.jsonfile, not a zip archive
If you want to modify any part of the website, follow these steps so your changes are never overwritten during updates:
- Copy the file from
src/View/home/page.phptothemes/custom/home/page.php. - Edit your new file. The system will prioritize
themes/custom/automatically.
Your PHP installation is missing the pdo_mysql extension. Contact your host to enable it.
- Ensure your SMTP port (usually 465 or 587) is open in your server's firewall.
- Check that your credentials are correct in Admin > Config Hub > Email.
- Verify that your From Email address matches the one authorized by your SMTP provider.
- Verify that the bucket CORS policy allows your Fyuhls origin.
- Make sure
PUT,GET, andHEADare allowed. - Make sure
ETagis exposed. - Confirm your site's CSP allows direct browser connections to the storage endpoint as well as the bucket CORS policy.
- Confirm the endpoint, region, access key, and secret key are correct in Admin > Config Hub > Storage.
- Confirm the token has the correct scope, especially
files.upload. - Use
Idempotency-Keyon create and complete requests. - Persist the upload session ID client-side so the tool can resume instead of starting over.
- Use the public API reference at
/apifor the current request and response format.
- Double-check that the Document Root in Step 2 is pointing to the
public/folder, not the project root. - Ensure PHP 8.2+ is selected in your control panel.
- First confirm the document root points to
fyuhls/public. - Then confirm Apache
mod_rewriteor your host's clean-URL equivalent is enabled.
- Make sure you're typing the database name, username, and password exactly as created in Step 3.
- On cPanel, the full username is often
yourusername_dbusername- include the prefix. - The installer does not create databases or database users for you. Create both first in your hosting panel and assign the user to the database with the required privileges.
The installer detected an existing config. To reinstall, delete config/database.php and run install.php again.
- The installer (
public/install.php) andpublic/post_install_check.phpare blocked after setup, but you should still delete them manually if they remain on disk. - Keep the project root outside the public web root whenever possible so only
public/is web-accessible. - Never share your encryption_key found in your off-grid config. If lost, all encrypted data is permanently unrecoverable.
- Keep your PHP version up to date for security patches.
Need more help? Check the admin page guides, the fyuhls wiki, or the built-in Bug Report area with the sanitized error log export.
