iTechGuides is reader-supported. When you buy through links on our site, we may earn an affiliate commission. As an Amazon Associate I earn from qualifying purchases. Learn more
Need a server to try this on? Antihost offers Linux VPS plans with NVMe storage, full root access and a 14-day free trial.
To install Flarum 2.x on a VPS, use PHP 8.3 or newer with Flarum’s required extensions, a supported database, SSH access, Composer, and either Apache with mod_rewrite or Nginx. Install the application into an empty directory with Composer, set the web server’s document root to Flarum’s public directory, enable URL rewriting, and give the runtime user write access to the installation root, storage, and assets.
This guide follows the Flarum 2.x requirements published in 2026. Flarum 1.x has different PHP, database, and Composer requirements; its deployment is covered separately so the two major versions are not accidentally mixed.
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 →
What you need before installing Flarum
A VPS is suitable for Flarum when you can administer it over SSH and control the web server, PHP runtime, PHP-FPM process (where applicable), filesystem ownership, and database connection. Shared hosting environments that hide Composer or prevent document-root changes can block a normal installation.
Choose the Flarum major version first
This procedure targets Flarum 2.x. The Composer command, PHP baseline, and database constraints differ from Flarum 1.x, so do not run the 1.x command on a PHP 8.3 stack merely because an old tutorial shows it. If you are maintaining an existing 1.x forum, use the 1.x requirements and migration guidance for that deliberate deployment instead of treating it as a new 2.x installation.
#1 Best Overall
Flarum 2.x requirements
| Component | Minimum or supported versions | Provisioning guidance |
|---|---|---|
| Operating web server | Apache with mod_rewrite or Nginx |
Choose a server that lets you set the site root to Flarum’s public directory and configure rewrites. |
| PHP | 8.3 or newer | Use a PHP-FPM setup when your web server passes requests to PHP-FPM. |
| Required PHP extensions | curl, dom, fileinfo, gd, json, mbstring, openssl, pdo_mysql, tokenizer, zip, and session | Install the extensions for the same PHP version that Composer and the web server will use. |
| MySQL | 5.7+ or 8.0.30+ | The documentation recommends MySQL 8.4 LTS for a new deployment. |
| MariaDB | 10.3+ | The documentation recommends MariaDB 11.8 LTS for a new deployment. |
| SQLite | 3.35.0+ | Use a filesystem location that the Flarum runtime user can access. |
| PostgreSQL | 10.0+ | The documentation recommends PostgreSQL 15, 16, or 17 for current deployments. |
| Command-line tools | SSH and Composer | SSH is needed for installation and administration; Composer manages Flarum dependencies and extensions. |
The minimum database versions are compatibility floors, not necessarily the best versions to select when provisioning a new VPS. Database releases change, so recheck the current Flarum documentation and your distribution’s support policy when you create the server.
Verify the VPS software before running Composer
Connect over SSH
- Connect with the account you use for server administration:
ssh your-user@your-server. - Confirm that you can change into the directory where the forum will live and that the directory is empty or newly created for Flarum.
- Identify the user that will run Composer and the user that your web server or PHP-FPM pool runs as. Those identities determine the ownership and permissions you will set later.
Check PHP and its extensions
Run php -v and confirm that the command-line PHP version is 8.3 or newer. Run php -m and check for curl, dom, fileinfo, gd, json, mbstring, openssl, pdo_mysql, tokenizer, zip, and session. A PHP extension can be installed for one PHP version while the web server uses another, so verify both the CLI and the PHP-FPM configuration when they are separate.
Do these 3 things before closing this tab:
1Clear out junk files and repair common Windows errors2Scan for outdated or missing drivers - takes under a minute3Repair Windows errors before they cause bigger problemsIf an extension is missing, install the package matching PHP 8.3 or later, restart PHP-FPM if your distribution requires it, and repeat the check. Composer will stop when a required platform extension is unavailable; fixing the PHP installation is safer than bypassing Composer’s platform checks.
Check Composer
Run composer --version as the same administrative user that will install Flarum. Composer is not an optional add-on: Flarum uses it to resolve the core dependencies and to manage extensions. Make sure the command can write to the chosen installation directory and that outbound package downloads are allowed by the VPS network policy.
Prepare a supported database
Create an empty database and a database account with the privileges needed by the installer. Record the database host, port, database name, username, and password; you will enter these values in Flarum’s browser-based installer. The database server may be on the same VPS or a separate service, but the VPS must be able to reach it and the account must be allowed to connect from the VPS.
Install Flarum 2.x with Composer
Use an empty installation directory
Choose a permanent path, such as /var/www/forum, and ensure it does not contain another application or an earlier Flarum installation. The final webroot will be a subdirectory of this path, not the path itself. Installing into an empty directory prevents Composer from merging unrelated files and makes ownership troubleshooting much easier.
Free tools Windows power users keep installed
One-click scans. No signup required.
Run the official create-project command
- Change into the empty directory:
cd /path/to/your/forum. - Run
composer create-project flarum/flarum:^2.0.0 .. - Wait for Composer to resolve and download Flarum’s dependencies. Do not interrupt the process unless it reports an error; a partially populated directory is not a completed installation.
- Keep the installation path available for the web-server configuration. In the examples below, replace
/path/to/your/forumwith the real absolute path.
The trailing dot in the command tells Composer to place Flarum in the current directory. Running the command from the parent directory without the dot creates a different layout and can make the eventual document root point to the wrong location.
Point the web server at Flarum’s public directory
Flarum’s application files must not be exposed as the document root. Set the site’s root to /path/to/your/forum/public. Normal Flarum routes also require URL rewriting; without it, the home page may load while discussions, tags, or administration URLs return 404 responses.
Apache
Enable Apache’s mod_rewrite module and allow the Flarum directory’s .htaccess rules to be honored. The virtual host’s document root should be:
/path/to/your/forum/public
After changing the Apache configuration, reload or restart Apache using your operating system’s service manager. If Apache serves the directory but ignores the rewrite rules, check that overrides are permitted for this path and that mod_rewrite is enabled in the active Apache configuration rather than only in a disabled site file.
Rank #3
Nginx
Set the Nginx site root to:
/path/to/your/forum/public
Include Flarum’s supplied Nginx rules from:
/path/to/flarum/.nginx.conf
Use the PHP-FPM socket or address that matches the PHP version you verified on the VPS. Test the Nginx configuration before reloading it. A successful configuration test followed by a reload prevents an invalid server block from taking down unrelated sites on the same VPS.
Caddy
The Flarum documentation also provides a Caddy setup. Configure the site root as Flarum’s public directory and pass PHP requests through the documented PHP FastCGI configuration. Caddy does not use Apache’s .htaccess; its site block must provide the equivalent front-controller behavior and the correct PHP-FPM endpoint.
Choose a server configuration
| Server | Rewrite method | PHP integration | When it fits |
|---|---|---|---|
| Apache | mod_rewrite with Flarum’s .htaccess; directory overrides must be allowed |
Use the PHP handler or PHP-FPM arrangement already managed on the VPS | Useful when Apache is already installed and you prefer per-directory rewrite rules. |
| Nginx | Include Flarum’s .nginx.conf |
Pass requests to the matching PHP-FPM socket or address | Useful when Nginx is already your reverse proxy or web server. |
| Caddy | Declare the equivalent routing in the Caddy site block | Use the documented PHP FastCGI configuration | Useful when you already operate Caddy and want its concise site configuration. |
The deciding factors are the server you already administer, how comfortable you are maintaining rewrite rules, the PHP-FPM integration available on the VPS, and whether the server lets you set the root to public. Switching servers during the Flarum install adds another source of errors and is rarely necessary.
Finish the installation in your browser
- Point the forum’s domain or test hostname to the VPS and open it in a browser.
- When Flarum displays the installation form, enter the database connection details you prepared earlier.
- Choose the forum name and administrator credentials. Use a unique administrator password and store it in your password manager.
- Submit the form and wait for Flarum to create
config.phpand initialize the database. - Open the home page, a discussion, a tag, and the administration area. Testing more than the landing page catches rewrite and permission problems immediately.
If the installer reports that it cannot write configuration or cache files, stop and correct filesystem ownership before trying the form repeatedly. The browser process must be able to write the locations described in the next section.
Set ownership and permissions correctly
Flarum’s runtime user must have read and write access to the installation root, storage, and assets. The root is needed for config.php; storage holds logs and cached data; and assets stores items such as logos and avatars.
Rank #4
Match the actual users
Ownership must reflect the users that really run your commands and services. If Composer runs as one account while PHP-FPM runs as another, a directory owned exclusively by the first account can produce browser-side write errors. Decide whether the CLI and web process share a group, then assign ownership and group permissions so both can perform their required tasks without making the entire VPS writable.
Use the least broad permissions that work
The documentation shows chmod 775 -R /path/to/directory as one possible Linux step when warnings remain. Treat that as a troubleshooting measure, not a default security policy: recursive 775 grants broad group write access throughout the tree. Correct ownership, a deliberate group, and narrower permissions on files and directories are preferable. Never make the installation world-writable just to silence an installer warning.
Recommended Free Tools
Verify after every change
- Check that the web-server or PHP-FPM user can read the application files.
- Check write access to the installation root,
storage, andassets. - Reload the page and inspect Flarum’s error output or server logs if the warning persists.
- After installing an extension or uploading an avatar, verify that the expected file appears and that the application remains able to write cache and log data.
Install the dashboard extension manager only when appropriate
If administrators need to install extensions from Flarum’s dashboard, the documentation shows:
composer require flarum/extension-manager:"*"
This extension allows Composer packages to be installed from the administration interface. Grant that capability only to administrators you trust, because it can install arbitrary Composer packages. On a forum with several moderators, separate routine moderation privileges from the small group allowed to manage extensions and server-side code.
Independent reader supportYour contribution helps us test, update, and keep practical guides available for everyone.Troubleshoot common Flarum VPS failures
Home page works but discussion URLs return 404
- Confirm that the document root is
/path/to/your/forum/public, not the installation root. - On Apache, verify that
mod_rewriteis enabled and that.htaccessoverrides are permitted for the site directory. - On Nginx, verify that the site includes
/path/to/flarum/.nginx.confand that the configuration was tested and reloaded. - On Caddy, verify that the site block contains the documented front-controller and PHP FastCGI behavior.
- Clear any external proxy cache only after the server configuration is correct; a cache cannot repair a missing rewrite rule.
The installer says PHP is missing an extension
Compare php -v and php -m with the required list. If the CLI shows an extension but the browser installer does not, PHP-FPM is probably using a different PHP installation or configuration. Install the extension for the PHP-FPM version, restart PHP-FPM, and test the installer again.
Composer refuses to create the project
- Confirm that the directory is empty and writable by the account running Composer.
- Confirm that PHP is 8.3 or newer and that every required extension is available to the CLI.
- Run
composer --versionand review the complete error output rather than suppressing platform checks. - Check network access to package repositories and available disk space on the VPS.
Flarum cannot write configuration, logs, cache, logos, or avatars
Recheck ownership and group membership for the actual PHP-FPM or web-server user. Test the installation root, storage, and assets individually. Correct ownership first; use the documented recursive 775 command only as a temporary diagnostic when narrower permissions have not resolved the warning.
The Tool Desk
Outbyte PC Repair FREERepair Windows errors before they cause bigger problemsFix Now →Outbyte Driver Updater FREEFix the driver behind crashes, sound loss and screen glitchesFind Drivers →Database connection fails
Verify the database host, port, name, username, and password entered in the installer. Confirm that the selected database version is supported and that the VPS can reach the database service. For a remote database, check its network allowlist and the account’s permitted source host.
Admin extension installation is unexpectedly powerful
If the extension manager is installed, review who has administrator access. Its Composer capability can add arbitrary packages, so a compromised administrator account could change server-side application code. Remove the extension when dashboard-based package installation is not required, or restrict administrator accounts and monitor package changes.
Do not mix Flarum 1.x instructions with a 2.x installation
Flarum 1.x is a separate major-version target with older platform constraints. Use it only when you intentionally need that release line, such as maintaining an existing application that has not been upgraded.
| Flarum release line | PHP requirement | Database requirements listed by its documentation | Composer command |
|---|---|---|---|
| 2.x | PHP 8.3+ | MySQL 5.7+ or 8.0.30+, MariaDB 10.3+, SQLite 3.35.0+, or PostgreSQL 10.0+ | composer create-project flarum/flarum:^2.0.0 . |
| 1.x | PHP 7.3+ | MySQL 5.6+ or 8.0.23+, or MariaDB 10.0.5+ | composer create-project flarum/flarum:^1.8.0 . |
These rows are not interchangeable. A server that satisfies Flarum 1.x’s PHP baseline does not automatically satisfy Flarum 2.x, and changing the Composer constraint alone does not perform a supported upgrade. Select the major version before provisioning PHP and the database.
Quick Recap
Flarum VPS deployment checklist
- VPS access works over SSH.
- PHP is 8.3 or newer for Flarum 2.x.
- curl, dom, fileinfo, gd, json, mbstring, openssl, pdo_mysql, tokenizer, zip, and session are enabled for the PHP used by Composer and the web server.
- A supported MySQL, MariaDB, SQLite, or PostgreSQL database is reachable with an empty database prepared.
- Composer runs successfully from the installation account.
- The project was created in an empty directory with
composer create-project flarum/flarum:^2.0.0 .. - The document root is the project’s
publicdirectory. - URL rewriting is configured for the selected web server.
- The runtime user can write the installation root,
storage, andassets. - The browser installer completes and test pages beyond the home page load correctly.
- Dashboard extension installation is limited to administrators who are trusted to add Composer packages.
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.
