diff --git a/docs/.vuepress/config/locales/en/sidebar.js b/docs/.vuepress/config/locales/en/sidebar.js index 27f2d0ba9..d3053dd8f 100644 --- a/docs/.vuepress/config/locales/en/sidebar.js +++ b/docs/.vuepress/config/locales/en/sidebar.js @@ -91,6 +91,7 @@ module.exports = { title: 'Setting Up', collapsable: false, children: [ + 'composer', 'install', 'update', 'troubleshoot' @@ -108,6 +109,13 @@ module.exports = { 'mail', 'console' ] + }, + { + title: 'Advanced', + collapsable: false, + children: [ + 'extenders' + ] } ], } diff --git a/docs/composer.md b/docs/composer.md new file mode 100644 index 000000000..5b79a1c14 --- /dev/null +++ b/docs/composer.md @@ -0,0 +1,163 @@ + +# Composer + +Flarum uses a program called composer[Composer](https://getcomposer.org) to manage its dependencies and extensions. +You'll need to use composer if you want to: + +- Install or update Flarum +- Install, update, or remove Flarum extensions + +This guide is provided as a brief explanation of Composer. We highly recommend consulting the [official documentation](https://getcomposer.org/doc/00-intro.md) for more information. + +::: tip Composer v2 +Historically, Composer has caused issues on shared hosting due to huge memory use. In 2020, [Composer v2 was released](https://blog.packagist.com/composer-2-0-is-now-available/) with massive performance and memory usage improvements that eliminate these problems. Make sure your server is using Composer v2! +::: + +## What is Composer? + +> Composer is a tool for dependency management in PHP. It allows you to declare the libraries your project depends on and it will manage (install/update) them for you. — [Composer Introduction]([https://getcomposer.org/doc/00-intro.md](https://getcomposer.org/doc/00-intro.md)) + +Each Flarum installation consists primarily of Flarum core and a set of [extensions](extensions.md).Each of these has its own dependencies and releases. + +Back in the day, forum frameworks would manage extensions by having users upload zip files with the extension code. That seems simple enough, but issues quickly become evident: + +- Uploading random zip files from the internet tends to be a bad idea. Requiring that extensions be downloaded from a central source like [Packagist](https://packagist.org/) makes it somewhat more tedious to spam malicious code, and ensures that source code is available on GitHub for free/public extensions. +- Let's say Extension A requires v4 of some library, and Extension B requires v5 of that same library. With a zip-based solution, either one of the two dependencies could override the other, causing all sorts of inconsistent problems. Or both would attempt to run at once, which would cause PHP to crash (you can't declare the same class twice). +- Zip files can cause a lot of headache if trying to automate deployments, run automated tests, or scale to multiple server nodes. +- There is no good way to ensure conflicting extension versions can't be installed, or that system PHP version and extension requirements are met. +- Sure, we can upgrade extensions by replacing the zip file. But what about upgrading Flarum core? And how can we ensure that extensions can declare which versions of core they're compatible with? + +Composer takes care of all these issues, and more! + +## Flarum and Composer + +When you go to [install Flarum](install.md#installing), you're actually doing 2 things: + +1. Downloading a boilerplate "skeleton" for Flarum. This includes an `index.php` file that handles web requests, a `flarum` file that provides a CLI, and a bunch of web server config and folder setup. This is taken from the [`flarum/flarum` github repository](https://github.com/flarum/flarum), and doesn't actually contain any of the code necessary for Flarum to run. +2. Installing `composer` packages necessary for Flarum, namely Flarum core, and several bundled extensions. These are called by the `index.php` and `flarum` files from step 1, and are the implementation of Flarum. These are specified in a `composer.json` file included in the skeleton. + +When you want to update Flarum or add/update/remove extensions, you'll do so by running `composer` commands. Each command is different, but all commands follow the same general process: + +1. Update the `composer.json` file to add/remove/update the package. +2. Do a bunch of math to get the latest compatible versions of everything if possible, or figure out why the requested arrangement is impossible. +3. If everything works, download new versions of everything that needs to be updated. If not, revert the `composer.json` changes + +When running `composer.json` commands, make sure to pay attention to the output. If there's an error, it'll probably tell you if it's because of extension incompatibilities, an unsupported PHP version, missing PHP extensions, or something else. + +### The `composer.json` File + +As mentioned above, the entire composer configuration for your Flarum site is contained inside the `composer.json` file. You can consult the [composer documentation](https://getcomposer.org/doc/04-schema.md) for a specific schema, but for now, let's go over an annotated `composer.json` from `flarum/flarum`: + +```jsonc +{ + // This following section is mostly just metadata about the package. + // For forum admins, this doesn't really matter. + "name": "flarum/flarum", + "description": "Delightfully simple forum software.", + "type": "project", + "keywords": [ + "forum", + "discussion" + ], + "homepage": "https://flarum.org/", + "license": "MIT", + "authors": [ + { + "name": "Flarum", + "email": "info@flarum.org", + "homepage": "https://flarum.org/team" + } + ], + "support": { + "issues": "https://github.com/flarum/core/issues", + "source": "https://github.com/flarum/flarum", + "docs": "https://flarum.org/docs/" + }, + // End of metadata + + // This next section is the one we care about the most. + // It's a list of packages we want, and the versions for each. + // We'll discuss this shortly. + "require": { + "flarum/core": "^0.1.0", + "flarum/approval": "^0.1.0", + "flarum/bbcode": "^0.1.0", + "flarum/emoji": "^0.1.0", + "flarum/lang-english": "^0.1.0", + "flarum/flags": "^0.1.0", + "flarum/likes": "^0.1.0", + "flarum/lock": "^0.1.0", + "flarum/markdown": "^0.1.0", + "flarum/mentions": "^0.1.0", + "flarum/nicknames": "^0.1.0", + "flarum/pusher": "^0.1.0", + "flarum/statistics": "^0.1.0", + "flarum/sticky": "^0.1.0", + "flarum/subscriptions": "^0.1.0", + "flarum/suspend": "^0.1.0", + "flarum/tags": "^0.1.0" + }, + + // Various composer config. The ones here are sensible defaults. + // See https://getcomposer.org/doc/06-config.md for a list of options. + "config": { + "preferred-install": "dist", + "sort-packages": true + }, + + // Since Flarum is still in beta, this tells composer that it's ok + // to install beta packages. Once a stable version is tagged, this + // line can be removed. + "minimum-stability": "beta", + + // If composer can find a stable (not dev, alpha, or beta) version + // of a package, it should use that. Generally speaking, production + // sites shouldn't run beta software unless you know what you're doing. + "prefer-stable": true +} +``` + +Let's focus on that `require` section. Each entry is the name of a composer package, and a version string. +To read more about version strings, see the relevant [composer documentation](https://semver.org/). + +For Flarum projects, there's several types of entries you'll see in the `require` section of your root install's `flarum/core`: + +- You MUST have a `flarum/core` entry. This should have an explicit version string corresponding to the major release you want to install. For Flarum beta versions, this would be `^0.1.0`. +- You should have an entry for each extension you've installed. Some bundled extensions are included by default (e.g. `flarum/tags`, `flarum/suspend`, etc), [others you'll add via composer commands](extensions.md). Unless you have a reason to do otherwise (e.g. you're testing a beta version of a package), we recommend using an asterisk as the version string for extensions (`*`). This means "install the latest version compatible with my flarum/core". +- Some extensions / features might require PHP packages that aren't Flarum extensions. For example, you need the guzzle library to use the [Mailgun mail driver](mail.md). In these cases, the instructions for the extension/feature in question should explain which version string to use. + +## How to install Composer? + +As with any other software, Composer must first be [installed]([https://getcomposer.org/download/) on the server where Flarum is running. There are several options depending on the type of web hosting you have. + +### Dedicated Web Server + +In this case you can install composer as recommended in the Composer [guide]([https://getcomposer.org/doc/00-intro.md#system-requirements) + +### Managed / Shared hosting + +If Composer is not preinstalled (you can check this by running `composer --version`), you can use a [manual installation](https://getcomposer.org/composer-stable.phar). Just upload the composer.phar to your folder and run `/path/to/your/php7 composer.phar COMMAND` for any command documented as `composer COMMAND`. + +::: danger +Some articles on the internet will mention that you can use tools like a PHP shell. If you are not sure what you are doing or what they are talking about - be careful! An unprotected web shell is **extremely** dangerous. +::: + +## How do I use Composer? + +You'll need to use Composer over the **C**ommand-**l**ine **i**nterface (CLI). Be sure you can access your server over **S**ecure **Sh**ell (SSH). + +Once you have Composer installed, you should be able to run Composer commands in your SSH terminal via `composer COMMAND`. + +::: Optimizations +After most commands, you'll want to run `composer dump-autoload -a`. Essentially, this caches PHP files so they run faster. +::: + +## I don't have SSH access + +Most decent hosts should provide SSH access for shared hosting. If your host doesn't (and you can't switch to a good host that does offer it), hope might not yet be lost. You have several options: + +- Use alternatives like [Pockethold](https://github.com/UvUno/pockethold) to install Flarum. Note that you'll still need composer (and SSH) to install extensions. +- Install composer on your computer, and run the `install` command locally. Then upload the files via FTP to your host. To make modifications (updating Flarum, installing/updating/removing extensions), download the current versions of the files, run whatever composer commands you need locally, and then replace the `composer.json` and `composer.lock` files, and the `vendor` directory of your install with your local copy. Make sure to create backups before doing this! +- Some web hosts might provide a GUI for managing composer. The command line version is generally preferably, but if a GUI is the only possibility, consult your host's documentation for information on how to use it. + +Note that these workarounds are not officially supported! The only officially supported way to install and manage Flarum is through Composer. diff --git a/docs/extenders.md b/docs/extenders.md new file mode 100644 index 000000000..90f1af931 --- /dev/null +++ b/docs/extenders.md @@ -0,0 +1,23 @@ +# Local Extenders + +If there are customizations you want to make to your site without distributing an entire extension, you can do so by using **local extenders**. Each Flarum installation comes with an `extend.php` file where you can add extender instances, just like in a full extension. + +See our [extension documentation](extend/start.md) for more information about extenders (and even an [example of a local extender](extend/start.md#hello-world)). + +If you need to create new files (when adding a custom class to be imported for extenders), you'll need to adjust your composer.json a bit. +Add the following: + +```json +"autoload": { + "psr-4": { + "App\\": "app/" + } +}, +``` + +Now you can create new PHP files in an `app` subdirectory using the `App\...` namespace. + +::: tip Local Extenders vs Extensions +Local extenders can be good for small tweaks, but if you need large customizations, an extension might be a better choice: +a separate codebase, cleaner handling of many files, developer tooling, and the ability to easily open source are big benefits. +::: diff --git a/docs/extensions.md b/docs/extensions.md index ac26a2dc3..03b033b7a 100644 --- a/docs/extensions.md +++ b/docs/extensions.md @@ -16,7 +16,19 @@ Flarum has a wide ecosystem of extensions, most of which are open source and fre Just like Flarum, extensions are installed through [Composer](https://getcomposer.org), using SSH. To install a typical extension: 1. `cd` to your Flarum directory. This directory should contain `composer.json`, `flarum` files and a `storage` directory (among others). You can check directory contents via `ls -la`. -2. Run `composer require COMPOSER_PACKAGE_NAME`. This should be provided by the extension's documentation. +2. Run `composer require COMPOSER_PACKAGE_NAME:*`. This should be provided by the extension's documentation. + +## Updating Extensions + +Follow the instructions provided by extension developers. If you're using `*` as the version string for extensions ([as is recommended](composer.md)), running the commands listed in the [Flarum upgrade guide](update.md) should update all your extensions. + +## Uninstalling Extensions + +Similarly to installation, to remove an extension: + +0. If you want to remove all database tables created by the extension, click the "Uninstall" button in the admin dashboard. See [below](#managing-extensions) for more information. +1. `cd` to your Flarum directory. +2. Run `composer remove COMPOSER_PACKAGE_NAME:*`. This should be provided by the extension's documentation. ## Managing Extensions diff --git a/docs/faq.md b/docs/faq.md index fb06251c7..37dff33ea 100644 --- a/docs/faq.md +++ b/docs/faq.md @@ -42,9 +42,4 @@ Yes, but not for a while. Our focus right now is on getting Flarum stable and fe The real answer is that we generally keep an eye on our community for stand-out members who would make good staff. Honestly, for most of our current staff, what they did before becoming staff wasn't much different from what they do now. -Find a passion and contribute however you feel is best. Then let it take its course. You don't have to have a badge to be respected here. - - +Find a passion and contribute however you feel is best. Then let it take its course. You don't have to have a badge to be respected here. \ No newline at end of file diff --git a/docs/install.md b/docs/install.md index c47b9e320..263b51cb1 100644 --- a/docs/install.md +++ b/docs/install.md @@ -20,14 +20,14 @@ Before you install Flarum, it's important to check that your server meets the re * **SSH (command-line) access** to run Composer ::: tip Shared Hosting -At this stage, it's not possible to install Flarum by downloading a ZIP file and uploading the files to your web server. This is because Flarum uses a dependency-management system called [Composer](https://getcomposer.org) which needs to run on the command line. +It's not possible to install Flarum by downloading a ZIP file and uploading the files to your web server. This is because Flarum uses a dependency-management system called [Composer](https://getcomposer.org) which needs to run on the command line. -This doesn't necessarily mean you need a VPS. Some shared hosts give you SSH access, through which you should be able to install Composer and Flarum just fine. For other hosts without SSH, you can try workarounds such as [Pockethold](https://github.com/andreherberth/pockethold). +This doesn't necessarily mean you need a VPS. Most decent hosts support SSH access, through which you should be able to install Composer and Flarum just fine. ::: ## Installing -Flarum uses [Composer](https://getcomposer.org) to manage its dependencies and extensions. Before installing Flarum, you will need to [install Composer](https://getcomposer.org) on your machine. Afterwards, run this command in an empty location that you want Flarum to be installed in: +Flarum uses [Composer](https://getcomposer.org) to manage its dependencies and extensions. If you're not familiar with it, read [our guide](composer.md) for information on what it is and how to set it up. Afterwards, run this command in an empty location that you want Flarum to be installed in: ```bash composer create-project flarum/flarum . --stability=beta diff --git a/docs/troubleshoot.md b/docs/troubleshoot.md index 766977a8c..ccabcaad5 100644 --- a/docs/troubleshoot.md +++ b/docs/troubleshoot.md @@ -6,6 +6,11 @@ Next, you should take a few minutes to search the [Support forum](https://discus ## Step 0: Turn on debug mode +::: danger Skip on Production +These debugging tools are very useful, but can expose information that shouldn't be public. +These are fine if you're on a staging or development environment, but if you don't know what you're doing, skip this step when on a production environment. +::: + Before you proceed, you should enable Flarum's debugging tools. Simply open up **config.php** with a text editor, change the `debug` value to `true`, and save the file. This will cause Flarum to display detailed error messages, giving you an insight into what's going wrong. If you've been seeing blank pages and the above change doesn't help, try setting `display_errors` to `On` in your **php.ini** configuration file. @@ -18,7 +23,8 @@ A lot of issues can be fixed with the following: * Clear the backend cache with [`php flarum cache:clear`](console.md). * Make sure your database is updated with [`php flarum migrate`](console.md). * Ensure that the [email configuration](mail.md) in your admin dashboard is correct: invalid email config will cause errors when registering, resetting a password, changing emails, and sending notifications. -* Check that your `config.php` is correct. For instance, make sure that the right `url` is being used. +* Check that your `config.php` is correct. For instance, make sure that the right `url` is being used (`https` vs `http` and case sensitivity matter here!). +* One potential culprit could be a custom header, custom footer, or custom LESS. If your issue is in the frontend, try temporarily removing those via the Appearance page of the admin dashboard. You'll also want to take a look at the output of [`php flarum info`](console.md) to ensure that nothing major is out of place. @@ -38,7 +44,7 @@ If it looks like you're going to need help solving the problem, it's time to get * Displayed in the browser console (Chrome: More tools -> Developer Tools -> Console) * Recorded in the server's error log (e.g. `/var/log/nginx/error.log`) * Recorded in PHP-FPM's error log (e.g. `/var/log/php7.x-fpm.log`) -* Recorded by Flarum (`storage/logs/flarum.log`) +* Recorded by Flarum (`storage/logs`) Copy any messages to a text file and jot down a few notes about *when* the error occurred, *what* you were doing at the time, and so on. Be sure to include any insights you may have gleaned about the conditions under which the issue does and doesn't occur. Add as much information as possible about your server environment: OS version, web server version, PHP version and handler, et cetera. diff --git a/docs/update.md b/docs/update.md index c20021979..c94065e3d 100644 --- a/docs/update.md +++ b/docs/update.md @@ -1,3 +1,96 @@ # Updating -While Flarum is in beta, instructions on how to update will be posted in each [release announcement](https://discuss.flarum.org/t/blog?sort=newest). \ No newline at end of file +To update Flarum, you'll need to use [Composer](https://getcomposer.org). If you're not familiar with it (although you should be, because you need it to install Flarum), read [our guide](composer.md) for information on what it is and how to set it up. + +If updating across major versions (e.g. <=0.1.0 to 1.x.x, 1.x.x to 2.x.x, ...), make sure to read the appropiate "major version update guide" before running the general upgrade steps. + +## General Steps + +**Step 1:** Make sure all your extensions have versions compatible with the Flarum version you're trying to install. This is only needed across major versions (e.g. you probably don't need to check this if upgrading from v1.0.0 to v1.1.0, assuming your extensions follow recommended versioning). You can check this by looking at the extension's [Discuss thread](https://discuss.flarum.org/t/extensions), searching for it on [Packagist](http://packagist.org/), or checking databases like [Extiverse](https://extiverse.com). You'll need to remove (not just disable) any uncompatible extensions before updating. Please be patient with extension developers! + +**Step 2:** Take a look at your `composer.json` file. Unless you have a reason to require specific versions of extensions or libraries, you should set the version string of everything except `flarum/core` (and `flarum/NAME` bundled extensions) to `*`. Make sure `flarum/core` is NOT set to `*`. If you're targeting a specific version of Flarum, set `flarum/core` to that (e.g. `"flarum/core": "v0.1.0-beta.16`). If you just want the most recent version, use `"flarum/core": "^0.1.0"`. + +**Step 4:** If your local install uses [local extenders](extenders.md), make sure they are up to date with changes in Flarum. + +**Step 4:** We recommend disabling third-party extensions in the admin dashboard before updating. This isn't strictly required, but will make debugging easier if you run into issues. + +**Step 5:** Make sure your PHP version is supported by the version of Flarum you are trying to upgrade to, and that you are using Composer 2 (`composer --version)`. + +**Step 6:** Finally, to update, run: + +``` +composer update --prefer-dist --no-plugins --no-dev -a --with-all-dependencies +php flarum migrate +php flarum cache:clear +``` + +**Step 7:** If applicable, restart your PHP process and opcache. + +## Major Version Update Guides + +### Updating from Beta (<=0.1.0) to Stable v1 (^1.0.0) + +Coming soon! + +## Troubleshooting Issues + +There are 2 main places where you might run into errors when updating Flarum: while running the update command itself, or when accessing the forum after updating. + +### Errors While Updating + +Here we'll go through several common types of issues while trying to update Flarum. + +--- + +If the output is short and contains: + +``` +Nothing to modify in lock file +``` + +Or does not list `flarum/core as an updated package, and you are not on the latest flarum version: + +- Revisit step 2 above, make sure that all third party extensions have an asterisk for their version string. +- Make sure your `flarum/core` version requirement isn't locked to a specific minor version (e.g. `v0.1.0-beta.16 is locked, ^0.1.0 isn't). If you're trying to update across major versions of Flarum, follow the related major version update guide above. + +--- + +For other errors, try running `composer why-not flarum/core VERSION_YOU_WANT_TO_UPGRADE_TO` + +If the output looks something like this: + +``` +flarum/flarum - requires flarum/core (v0.1.0-beta.15) +fof/moderator-notes 0.4.4 requires flarum/core (>=0.1.0-beta.15 <0.1.0-beta.16) +jordanjay29/flarum-ext-summaries 0.3.2 requires flarum/core (>=0.1.0-beta.14 <0.1.0-beta.16) +flarum/core v0.1.0-beta.16 requires dflydev/fig-cookies (^3.0.0) +flarum/flarum - does not require dflydev/fig-cookies (but v2.0.3 is installed) +flarum/core v0.1.0-beta.16 requires franzl/whoops-middleware (^2.0.0) +flarum/flarum - does not require franzl/whoops-middleware (but 0.4.1 is installed) +flarum/core v0.1.0-beta.16 requires illuminate/bus (^8.0) +flarum/flarum - does not require illuminate/bus (but v6.20.19 is installed) +flarum/core v0.1.0-beta.16 requires illuminate/cache (^8.0) +flarum/flarum - does not require illuminate/cache (but v6.20.19 is installed) +flarum/core v0.1.0-beta.16 requires illuminate/config (^8.0) +flarum/flarum - does not require illuminate/config (but v6.20.19 is installed) +flarum/core v0.1.0-beta.16 requires illuminate/container (^8.0) +flarum/flarum - does not require illuminate/container (but v6.20.19 is installed) +flarum/core v0.1.0-beta.16 requires illuminate/contracts (^8.0) +flarum/flarum - does not require illuminate/contracts (but v6.20.19 is installed) +flarum/core v0.1.0-beta.16 requires illuminate/database (^8.0) +flarum/flarum - does not require illuminate/database (but v6.20.19 is installed) +flarum/core v0.1.0-beta.16 requires illuminate/events (^8.0) +flarum/flarum - does not require illuminate/events (but v6.20.19 is installed) +... (this'll go on for a bit) +``` + +It is very likely that some of your extensions have not yet been updated. + +- Revisit step 1 again, make sure all your extensions have versions compatible with the core version you want to upgrade to. Remove any that don't. +- Make sure you're running `composer update` with all the flags specified in the update step. + +If none of this fixes your issue, feel free to reach out on our [Support forum](https://discuss.flarum.org/t/support). Make sure to include the output of `php flarum info` and `composer why-not flarum/core VERSION_YOU_WANT_TO_UPGRADE_TO`. + +### Errors After Updating + +If you are unable to access your forum after updating, follow our [troubleshooting instructions](troubleshoot.md). \ No newline at end of file