What’s actually slowing this PC down?
Pick the symptom - the matching free tool is one click away.
To install Flarum 2.x on a VPS, provision a server with PHP 8.3 or newer, the required PHP extensions, a supported database, SSH access and Composer. Install Flarum into an empty directory with composer create-project flarum/flarum:^2.0.0 ., point your web server at that installation’s public directory, enable URL rewriting, and give the Flarum runtime user read/write access to the install root, storage and assets. Most blank pages, 404s and failed uploads come from one of those requirements being missed.
Need a server to try this on? Antihost offers Linux VPS plans with NVMe storage, full root access and a 14-day free trial.
This runbook is for the current Flarum 2.x line. Flarum 1.x has different PHP, database and Composer requirements, so do not combine its command with a 2.x server stack.
As an Amazon Associate I earn from qualifying purchases.
Recommended Free Tools
What a Flarum VPS installation needs
Flarum is a PHP application managed by Composer. The VPS must provide a web server, PHP-FPM or an equivalent PHP handler, a database, command-line access and a filesystem layout that keeps public files separate from application code. A managed VPS is suitable only if you can still use SSH, run Composer and configure the document root.
Flarum 2.x requirements
- Web server: Apache with
mod_rewrite, or Nginx. Caddy can also be used with the documented PHP FastCGI configuration. - PHP: 8.3 or newer.
- PHP extensions:
curl,dom,fileinfo,gd,json,mbstring,openssl,pdo_mysql,tokenizer,zipandsession. - Database: MySQL 5.7 or newer, MySQL 8.0.30 or newer, MariaDB 10.3 or newer, SQLite 3.35.0 or newer, or PostgreSQL 10.0 or newer.
- Command line: SSH access and Composer. Composer is required to install Flarum and to manage extensions from the shell.
- Domain: a DNS record pointing at the VPS. You can test with an IP address, but a real forum should use the final domain before creating accounts and configuring HTTPS.
For a new production server, the Flarum documentation recommends current long-term-support database releases: MySQL 8.4 LTS, MariaDB 11.8 LTS, or PostgreSQL 15, 16 or 17. Those recommendations can change as database projects publish new releases, so check the supported versions again when you provision the server.
Choose the database deliberately
MySQL and MariaDB are common choices on PHP VPS plans because hosting control panels often provision them easily. PostgreSQL and SQLite are also supported by Flarum 2.x, but your backup, monitoring and upgrade procedures must match the database you choose. SQLite is convenient for a small installation because it is a file rather than a separate database service; it still needs reliable disk backups and correct filesystem permissions.
Apache, Nginx or Caddy?
Use the server you already operate confidently, provided it can set the site’s document root to Flarum’s public directory and pass PHP requests to the correct PHP runtime.
| Server | Rewrite method | PHP integration | Important Flarum setting |
|---|---|---|---|
| Apache | mod_rewrite and Flarum’s .htaccess |
Use the PHP handler or PHP-FPM configured on the VPS | Allow the directory’s .htaccess overrides; point the document root at .../public |
| Nginx | Include Flarum’s supplied .nginx.conf |
Pass PHP files to PHP-FPM | Set the root to /path/to/your/forum/public and include /path/to/flarum/.nginx.conf |
| Caddy | Use the documented Caddy routing rules | PHP FastCGI | Set the site root to Flarum’s public directory and configure PHP FastCGI as documented |
A web root aimed at the project directory instead of public can expose files that should not be public and commonly causes broken routes. Treat the document-root setting as a security requirement, not merely a convenience.
Prepare the VPS over SSH
1. Log in and identify the runtime users
Connect as a normal administrative account (using your provider’s SSH details), then determine which Unix user runs your web server and PHP-FPM pool. The command-line user that runs Composer and the web-server user may be different. Record both; ownership mistakes later usually come from assuming they are the same.
2. Verify PHP and extensions
Check the active PHP binary and Composer before creating the site:
php -v
php -m
composer --versionConfirm that the reported PHP major and minor version is at least 8.3 and that every extension in the requirements list appears in php -m. Check the PHP-FPM version used by the web server as well; a shell may use one PHP installation while the site uses another. If an extension is missing, install the package supplied by your VPS operating system, restart PHP-FPM, and repeat the checks.
Free tools Windows power users keep installed
One-click scans. No signup required.
3. Verify database connectivity
Create an empty database and a dedicated database account through your VPS provider or database administration tools. Keep the database name, username, password, host and port available for the browser installer. Test that the account can connect to the selected database before starting the Flarum installer. Grant only the permissions needed for the forum database; do not reuse a server-wide administrative account.
4. Select an empty installation directory
Choose the final path before running Composer, such as /var/www/forum or another directory used by your deployment conventions. The directory must be empty. Do not run the Flarum project command inside a directory containing an older forum, a partial Composer project or unrelated files. If you are replacing an existing installation, take a verified backup and use a separate release directory instead of deleting the live files blindly.
Install Flarum with Composer
1. Change into the empty directory
cd /path/to/your/forumUse the same path you will later reference in your web-server configuration. A mismatch between the Composer path and the configured document root is a common reason for a directory listing, a 404 or a blank response.
2. Create the Flarum 2.x project
composer create-project flarum/flarum:^2.0.0 .The final dot tells Composer to place the project in the current directory. Composer downloads Flarum’s dependencies and creates the application structure. Flarum explicitly uses Composer to manage both its dependencies and its extensions, so let the command finish and investigate any dependency error rather than copying only part of the directory.
Do these 3 things before closing this tab:
1Scan for outdated or missing drivers - takes under a minute2Repair Windows errors before they cause bigger problems3Fix the driver behind crashes, sound loss and screen glitches3. Keep Composer’s files out of the public web root
After installation, the project root contains configuration, storage and dependency files, while public contains the files intended for direct web access. Do not point Apache, Nginx or Caddy at the project root. Your site’s root must be:
/path/to/your/forum/publicConfigure the web server
Apache
Set the virtual host’s document root to the Flarum public directory. Enable mod_rewrite and allow the .htaccess file shipped with Flarum to override the relevant directory settings. Ensure the virtual host passes PHP files to the PHP version that meets the 8.3 requirement. Reload Apache after validating its configuration.
If direct navigation to the home page works but a forum discussion or tag URL returns a 404, Apache is usually not reading .htaccess, mod_rewrite is disabled, or the virtual host points at the wrong directory. Fix the virtual host and rewrite settings before changing Flarum files.
Nginx
Configure the server block’s root as /path/to/your/forum/public, pass PHP requests to the PHP-FPM socket or address for the supported PHP version, and include Flarum’s supplied configuration file:
/path/to/flarum/.nginx.confUse the actual project path in both settings. Nginx does not read Apache .htaccess files, so copying an Apache recipe into an Nginx server will not provide the required front-controller routing. Reload Nginx and PHP-FPM after testing their configurations.
Caddy
Use the documented Caddy site block with the Flarum public root and PHP FastCGI. Caddy must route normal requests to Flarum’s front controller while still serving static assets from public. Do not expose the project root by setting the site root one directory too high.
HTTPS and the final domain
Point the domain’s DNS record to the VPS, configure HTTPS in your chosen web server, and use the final HTTPS URL when completing the installer. If you initially install at a temporary hostname, changing the URL later requires carefully updating the application configuration and any proxy or cache settings. It is simpler to settle the canonical domain first.
Finish the installation in the browser
- Open the domain in a browser. The request must reach the
publicdirectory and PHP must be running. - Enter the database driver, host, port, database name, username and password you created earlier.
- Set the forum name, administrator username, administrator password and administrator email address.
- Submit the form and wait for Flarum to create
config.phpand initialize its tables. - Sign in to the administrator dashboard and confirm that the home page, tags, discussions, user registration and logout all work.
If the installer reports that it cannot write configuration, the runtime user lacks write access to the installation root. If database validation fails, recheck the host, port, credentials, selected driver and whether the database account is allowed to connect from the VPS.
Outdated Drivers Are Slowing You Down
One free scan finds every outdated or missing driver and matches the right update for your exact hardware.Free scan · exact hardware matchPC Slower Than It Used to Be?
A free scan shows the junk files, broken settings and background clutter dragging Windows down - then fixes them in one click.Free scan · Windows 10 & 11Rank #4
Set permissions without opening the whole server
Flarum’s runtime user must have read and write access to three areas:
- The installation root: Flarum writes
config.phpthere during installation. storage: logs and cached data are written here.assets: uploaded logos, avatars and other generated assets are stored here.
The exact owner and group must match the user that executes PHP through the web server. They also need to be compatible with the account you use for Composer. For example, if Composer creates files as one account and PHP-FPM runs as another, later extension installs or cache writes can fail even though the first page loaded successfully.
Correct ownership and the narrowest workable permissions are preferable to broad recursive permissions. The Flarum documentation shows this as one possible Linux measure when warnings remain:
Quick wins for a faster PC:
Clear out junk files and repair common Windows errorsFree Scan →Scan for outdated or missing drivers - takes under a minuteDriver Scan →chmod 775 -R /path/to/directoryUse that only as a troubleshooting step after confirming ownership, and apply it to the correct project path. Do not make the entire VPS or unrelated directories world-writable. After changing ownership or modes, reload the page and inspect the Flarum log for the first permission error.
Independent reader supportYour contribution helps us test, update, and keep practical guides available for everyone.Install the extension manager carefully
Flarum extensions can be managed with Composer. If you need dashboard-based extension installation, the documentation provides:
composer require flarum/extension-manager:"*"The extension manager can install arbitrary Composer packages. Enable it only when necessary and give administrator access only to people you trust to add and update server-side code. Keep a database backup and a file backup before major extension changes, and test updates on a staging copy when your forum is important.
Best Value
Troubleshoot the failures people hit most often
Every discussion URL returns 404
- Confirm the document root ends in
/public. - On Apache, confirm
mod_rewriteis enabled and.htaccessoverrides are permitted. - On Nginx, confirm the supplied
.nginx.confis included in the correct server block. - On Caddy, confirm the documented front-controller and PHP FastCGI rules are active.
- Reload the web server after changing configuration and test a direct discussion URL again.
The installer cannot create or update files
Check ownership and write access for the project root, storage and assets. Test the identity of the PHP-FPM process rather than relying only on the SSH user. A successful Composer run does not prove that the web-server user can write files.
PHP reports a missing extension
Compare php -m from SSH with the PHP information used by PHP-FPM. Install the missing extension for the PHP version serving the site, restart PHP-FPM, and verify again. Pay special attention to pdo_mysql when using MySQL or MariaDB, and to gd, fileinfo and zip, which are easy to overlook on minimal VPS images.
Composer stops with a platform or dependency error
Check that the command is running with PHP 8.3 or newer and that the required extensions are available to that CLI binary. Make sure the target directory is empty and that the Composer installation is current enough to resolve the Flarum 2.x package. Do not bypass platform checks to force an installation on an unsupported PHP stack; fixing the VPS runtime is safer than creating an unmaintainable deployment.
Uploads or avatars fail after installation
Verify that the PHP runtime user can write to assets and that the web server permits requests to files under public. If only newly uploaded files fail, inspect ownership of the assets subdirectories created after installation; mixed owners often indicate that Composer, a deployment script and PHP are using different accounts.
Flarum 1.x is a separate deployment target
Do not use the Flarum 1.x command on a Flarum 2.x server, or assume that a 1.x PHP requirement is sufficient for 2.x. The official 1.x requirements list PHP 7.3 or newer, MySQL 5.6 or newer (or MySQL 8.0.23 or newer), and MariaDB 10.0.5 or newer. Its project command is:
composer create-project flarum/flarum:^1.8.0 .Choose 1.x only when an existing extension or application specifically requires that major version and you are intentionally following its documentation. For a new forum, use the 2.x requirements and command described above.
Production checklist before opening registration
- PHP-FPM and the command-line PHP both meet the PHP 8.3 requirement.
- All listed PHP extensions are enabled for the web runtime.
- The database engine and version are supported, with a dedicated account and tested backups.
- The web root is exactly the Flarum
publicdirectory. - URL rewriting works for the home page, tags, discussions and user pages.
- The runtime user can write the install root,
storageandassets, without making unrelated paths writable. - HTTPS, DNS and the canonical forum URL are configured.
- Composer dependencies and extensions are changed from a controlled administrative account.
- Logs, database backups and a rollback plan have been tested.
- Registration, email delivery, uploads, administrator login and logout have been exercised with a test account.
A VPS that meets these checks is a Flarum-ready VPS: it gives Composer and PHP the versions they need, keeps the project root private, routes every normal URL through Flarum, and permits writes only where Flarum needs them.
Quick Recap
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.
