Do these 3 things before closing this tab:
1Repair Windows errors before they cause bigger problems2Fix the driver behind crashes, sound loss and screen glitches3Clear out junk files and repair common Windows errorsTo install current Flarum 2.x on a VPS, use PHP 8.3 or newer, a supported database, SSH and Composer. Create the project in an empty directory, serve its public directory, enable URL rewriting, then finish the web installer. The most common failures—404s, unwritable directories and Composer errors—come from an incorrect document root, missing rewrite rules, or mismatched CLI and web-server users.
Need a server to try this on? Antihost offers Linux VPS plans with NVMe storage, full root access and a 14-day free trial.
What Flarum needs on a VPS
Provision the server before downloading Flarum. The current 2.x requirements published by Flarum in 2026 are:
As an Amazon Associate I earn from qualifying purchases.
| Component | Supported requirement | Practical choice |
|---|---|---|
| Operating system | A Linux VPS capable of running the listed software | A currently supported 64-bit Linux distribution with security updates |
| Web server | Apache with mod_rewrite, or Nginx |
Use the server already standardised in your stack; Caddy is also documented with PHP FastCGI |
| PHP | PHP 8.3 or newer | Use the same PHP minor version for the CLI, PHP-FPM and web requests |
| Required PHP extensions | curl, dom, fileinfo, gd, json, mbstring, openssl, pdo_mysql, tokenizer, zip and session |
Verify the loaded modules rather than assuming a distribution package included them |
| Database | MySQL 5.7+ or 8.0.30+, MariaDB 10.3+, SQLite 3.35.0+, or PostgreSQL 10.0+ | For a new production VPS, the documentation recommends MySQL 8.4 LTS, MariaDB 11.8 LTS, or PostgreSQL 15, 16 or 17 |
| Administration | SSH command-line access | A non-root administrator account with sudo |
| Dependency manager | Composer | Install Composer for the account that will run updates and extension commands |
Database support is version-sensitive. Check the Flarum requirements again when provisioning if your distribution offers a newer release than the versions listed above. A VPS hosting plan for Flarum should therefore provide SSH, Composer, PHP-FPM and one of these database engines—not just a generic web control panel.
Choose Apache, Nginx or Caddy
All three can serve Flarum. The decision is mostly operational: which server you already maintain, how you prefer to express rewrite rules, and whether you can point the site root at Flarum’s public directory.
| Server | Rewrite method | PHP connection | When it fits |
|---|---|---|---|
| Apache | mod_rewrite and permitted .htaccess overrides |
Typically PHP-FPM or a distribution PHP module | Best when your VPS already uses Apache and you want per-directory rules |
| Nginx | Include Flarum’s supplied .nginx.conf |
PHP-FPM through a Unix socket or TCP endpoint | Good for a central, explicit server configuration |
| Caddy | A concise site block with the documented root and PHP FastCGI handling | php_fastcgi to PHP-FPM |
Useful when automatic HTTPS and a small configuration are priorities |
Regardless of server, the document root must be the installation’s public directory. Pointing a virtual host at the project root exposes files that should not be directly downloadable and causes routing problems.
Prepare the VPS
1. Connect over SSH
Use the administrator account supplied by your VPS provider:
The Tool Desk
Outbyte PC Repair FREEClear out junk files and repair common Windows errorsFree Scan →Outbyte Driver Updater FREEScan for outdated or missing drivers - takes under a minuteDriver Scan →ssh your-user@your-serverDo not run the entire application as root. Create a separate deployment or web user, grant it only the required administrative privileges, and record which account runs PHP-FPM. The same identity must be able to read the application and write the directories Flarum uses at runtime.
2. Check the command-line tools
Run these checks before creating the project:
php -v
php -m
composer --version
mysql --versionFor PostgreSQL, use psql --version; for SQLite, use sqlite3 --version. Confirm that php -v reports 8.3 or later and that php -m contains every extension in the requirements table. A web page showing a different PHP version does not prove that the CLI version is correct: PHP-FPM and the shell can use different binaries.
3. Verify PHP-FPM and its socket
Find the PHP-FPM service and endpoint used by your distribution. The socket name commonly contains the PHP minor version, but it is not identical on every VPS. Use the actual socket or TCP address in your web-server configuration. After changing PHP packages, restart PHP-FPM and confirm that a test request reaches the intended version.
Create the database and an empty application directory
Flarum’s Composer command must run in an empty directory. Choose a path outside your distribution’s default public directory, such as /var/www/flarum, and make sure it contains no old application files, partial Composer output or an existing composer.json.
What’s actually slowing this PC down?
Pick the symptom - the matching free tool is one click away.
sudo mkdir -p /var/www/flarum
sudo chown your-deploy-user:your-deploy-user /var/www/flarum
cd /var/www/flarumCreate a dedicated database and database user rather than granting Flarum access to an administrative account. The exact SQL syntax depends on the engine and authentication method, but the account needs permission to create and modify the tables in its own database. Record the database name, username, password, host and port; the browser installer will ask for them.
- Use a long, unique database password and keep it out of shell history where possible.
- Restrict database network access to the VPS or private network unless remote administration is genuinely required.
- Use a database encoding and collation supported by your selected engine and distribution defaults.
Install Flarum with Composer
From the empty installation directory, run the official 2.x project command:
composer create-project flarum/flarum:^2.0.0 .The trailing dot is significant: it tells Composer to place Flarum in the current directory. Composer downloads Flarum and its dependencies, creates the vendor tree and prepares the files used by the installer. Flarum uses Composer to manage both dependencies and extensions, so retain Composer access for future maintenance.
Do not substitute the 1.x command on a PHP 8.3 deployment or combine a 1.x dependency set with a 2.x application. If Composer stops with a platform-requirement error, fix the reported PHP version or extension first; do not bypass checks with a blanket ignore flag on a production server.
Quick wins for a faster PC:
Repair Windows errors before they cause bigger problemsFix Now →Fix the driver behind crashes, sound loss and screen glitchesFind Drivers →Clear out junk files and repair common Windows errorsFree Scan →Point the web server at public
Set the virtual host’s document root to:
/var/www/flarum/publicReplace the path with your actual installation directory. The project root contains configuration and dependency files that should not be served as ordinary documents.
Apache
Enable mod_rewrite, allow the Flarum directory’s .htaccess rules to take effect, and configure the virtual host’s DocumentRoot as the public directory. Your PHP handler must pass requests to PHP 8.3 or newer. Reload Apache after enabling the site. If Apache ignores the rewrite rules, check the directory’s AllowOverride setting and inspect the error log for denied overrides.
Nginx
Set root to the public directory and include Flarum’s supplied configuration file, located at:
/var/www/flarum/.nginx.confThe include path must point to the project root’s file, not to public/.nginx.conf. Pass PHP files to the PHP-FPM socket used by your server. A typical arrangement has a server block for the domain, the public root, the Flarum include, and a PHP-FPM location. Validate the syntax with nginx -t before reloading Nginx.
Free tools Windows power users keep installed
One-click scans. No signup required.
Caddy
Use a site block whose root is /var/www/flarum/public and connect PHP requests with Caddy’s PHP FastCGI directive to your PHP-FPM socket or TCP endpoint. Add the file-server behavior required for static assets. Validate the Caddy configuration before restarting the service. The important Flarum-specific details are the public root and PHP FastCGI routing; a site block pointed at the project root is not equivalent.
Set ownership and writable directories
Flarum’s runtime user must have read and write access to three locations:
- The installation root, because Flarum writes
config.phpduring installation and may need to update managed files. storage, for logs and cached data.assets, for uploaded logos, avatars and other generated or uploaded files.
Ownership must match reality: identify the account running PHP-FPM and the account that runs Composer, then choose a controlled group or deployment strategy that lets both perform their required tasks. Avoid making the entire server world-writable. The documentation shows chmod 775 -R /path/to/directory as a possible Linux remedy when warnings remain, but broad recursive permissions should be a fallback, not the design. Correct ownership and the least-permissive working mode are safer.
Recommended Free Tools
sudo chown -R your-deploy-user:your-web-group /var/www/flarum
sudo chmod -R u=rwX,g=rwX,o=rX /var/www/flarumAdapt the user, group and policy to your distribution. If Composer is run as one user and PHP-FPM as another, test both paths explicitly. A permission change that fixes the browser installer but prevents later updates is not a complete fix.
Finish the browser installation
- Open the domain over HTTPS once DNS and the virtual host are ready.
- Enter the database driver, host, port, database name, username and password created earlier.
- Choose the administrator username, password and email address. Use a unique administrator password and store it in a password manager.
- Submit the form and wait for Flarum to write
config.phpand complete the schema setup. - Sign in, open the administration area and confirm that the dashboard loads, assets display and a test discussion can be created.
If the installer reports that it cannot write a file, correct ownership for the actual PHP-FPM user rather than repeatedly refreshing the page. If it reports a missing extension, install that extension for the PHP-FPM version as well as the CLI version, then restart PHP-FPM.
Enable extension installation from the dashboard carefully
If administrators need to install extensions through the dashboard, the documentation provides:
composer require flarum/extension-manager:"*"This capability can install arbitrary Composer packages. Give dashboard administration only to people you trust, and treat extension installation as code deployment: review the extension, its permissions and its maintenance status before enabling it on a production forum.
Fix the problems that appear most often
Every forum route returns 404
- Confirm the virtual host root ends in
/public. - On Apache, confirm
mod_rewriteis enabled and directory overrides are allowed. - On Nginx, confirm the Flarum
.nginx.confinclude is inside the correct server configuration and that the configuration passednginx -t. - On Caddy, confirm the site block uses the Flarum public root and PHP FastCGI.
- Reload the web server after configuration changes and clear any proxy cache before retesting.
A 404 on the home page and a 404 only on pretty URLs point to different layers: the former usually indicates a wrong root or missing files, while the latter usually indicates missing rewrite handling.
The installer says directories are not writable
Check the owner and group of the project, storage and assets. Test as the PHP-FPM user, not only as your SSH user. Also check parent-directory execute permission: a writable child cannot be reached if a parent directory blocks traversal. Correct ownership first; use a narrowly scoped permission adjustment only if required.
Composer reports an incompatible PHP version or extension
Compare php -v and php -m with the PHP-FPM version and loaded modules. Installing an extension for an older PHP minor version does not satisfy PHP 8.3. Restart PHP-FPM after package changes and run Composer again from the Flarum directory. Do not mix the Flarum 1.x command with the 2.x requirements.
Database connection fails
- Check the host and port; a local database may require a Unix socket rather than
127.0.0.1. - Verify the database user has access from the host where PHP runs.
- Test the credentials with the database client’s command-line tool.
- Confirm that the selected database engine and version meet Flarum’s support floor.
CSS, avatars or logos do not load
Verify that assets is writable and that the web server serves static files from public. Inspect browser network errors and the web-server log for incorrect asset URLs, denied permissions or an HTTPS mixed-content configuration. Do not make the whole project writable to solve a static-file problem.
Blank page or a server error after installation
Check the web-server and PHP-FPM logs, then inspect Flarum’s storage logs. Confirm that PHP-FPM can read the vendor directory and write storage. A newly enabled extension can also introduce a PHP fatal error; disable the last change, restore service, and review the compatibility requirements before re-enabling it.
Flarum 1.x is a separate deployment target
Flarum 1.x has older constraints and should be installed only when you intentionally need that major version. Its documented baseline is PHP 7.3 or newer, MySQL 5.6+ or 8.0.23+, or MariaDB 10.0.5+, with this Composer command:
composer create-project flarum/flarum:^1.8.0 .| Flarum 2.x | Flarum 1.x | |
|---|---|---|
| PHP baseline | 8.3+ | 7.3+ |
| MySQL baseline | 5.7+ or 8.0.30+ | 5.6+ or 8.0.23+ |
| MariaDB baseline | 10.3+ | 10.0.5+ |
| Project command | composer create-project flarum/flarum:^2.0.0 . |
composer create-project flarum/flarum:^1.8.0 . |
Do not copy a 1.x installation guide into a 2.x server build. The PHP, database and dependency constraints are not interchangeable.
Quick Recap
Production checklist after the forum opens
- Confirm the domain uses HTTPS and that the canonical URL in Flarum matches it.
- Verify that the web root is the
publicdirectory. - Confirm successful reads and writes in
storageandassets. - Log out and back in, create a test discussion, upload a permitted image and visit several nested routes.
- Configure VPS backups for both the database and the Flarum files, especially
config.phpand uploaded assets. - Keep PHP, the database engine, the operating system and Composer-managed packages patched within their supported release lines.
- Review every extension before installation and limit administrator accounts.
- Monitor disk space, PHP-FPM failures, database errors and Flarum logs.
Product prices and availability are accurate as of the date/time indicated and are subject to change. Any price and availability information displayed on Amazon at the time of purchase will apply.
