diff --git a/docs/composer.md b/docs/composer.md index ad8470667..627f81821 100644 --- a/docs/composer.md +++ b/docs/composer.md @@ -4,14 +4,15 @@ Flarum uses a program called [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 +- Install or update Flarum through the command line +- Install, update, or remove Flarum extensions through the command line 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 +:::tip Shared Hosting -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! +On shared hosting it is recommended to use the Extension Manager extension instead of Composer. It is a graphical interface for Composer that allows you to install, update and remove extensions without the need for SSH access. +You can directly install Flarum using an archive file, without the need for Composer. With the extension manager pre-installed, check the [installation guide](install.md#installing-by-unpacking-an-archive) for more information. ::: @@ -152,13 +153,3 @@ Once you have Composer installed, you should be able to run Composer commands in 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/extensions.md b/docs/extensions.md index a96b1224a..e0244dd58 100644 --- a/docs/extensions.md +++ b/docs/extensions.md @@ -7,12 +7,39 @@ This approach makes Flarum extremely customizable: You can disable any features For more information on Flarum's philosophy on what features we include in core, or if you're looking to make your own extension, please see our [extension documentation](extend/README.md). This article will focus on managing extensions from a forum admin's perspective. +## Extension Manager + +The extension manager is an extension that comes bundled with Flarum when installed via an archive. It provides a graphical interface for installing and updating both extensions and Flarum itself. + +If you do not have the extension manager installed and you wish to install it, you can do so by running the following command in your Flarum directory: + +```bash +composer require flarum/extension-manager:* +``` + +:::warning + +The extension manager allows an admin user to install any composer package. Only install the extension manager if you trust all of your forum admins with such permissions. + +::: + +![extension manager admin page](https://github.com/flarum/docs/assets/20267363/d0e1f7a5-e194-4acd-af63-7b8ddd95c26b) + + ## Finding Extensions Flarum has a wide ecosystem of extensions, most of which are open source and free. To find new and awesome extensions, visit the [Extensions](https://discuss.flarum.org/t/extensions) tag on Flarum's community forums. The unofficial [Extiverse extension database](https://extiverse.com/) is also a great resource. ## Installing Extensions +### Through the interface + +Using the extension manager extension, you can install extensions directly from the admin dashboard. Once you have browsed the list of available extensions from the links above, and found one you want to install, you can install it by entering the extension's composer package name into the extension manager's installation input. + +![Installing an extension](/en/img/install-extension.png) + +### Through the command line + 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`. @@ -20,10 +47,26 @@ Just like Flarum, extensions are installed through [Composer](https://getcompose ## Updating Extensions +### Through the interface + +Using the extension manager extension, you can update extensions directly from the admin dashboard. You can run a check for updates by clicking the "Check for updates" button in the extension manager. If there are updates available, you can update all extensions by clicking the "Global update" button. Or, you can update individual extensions by clicking the "Update" button next to the extension you want to update. + +![Updating an extension](/en/img/update-extension.png) + +### Through the command line + 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 +### Through the interface + +Using the extension manager extension, you can uninstall extensions directly from the admin dashboard. You can uninstall an extension by clicking the "Uninstall" button next to the extension you want to uninstall inside the extension's page. + +![Uninstalling an extension](/en/img/uninstall-extension.png) + +### Through the command line + Similarly to installation, to remove an extension: 0. If you want to remove all database tables created by the extension, click the "Purge" button in the admin dashboard. See [below](#managing-extensions) for more information. @@ -32,8 +75,45 @@ Similarly to installation, to remove an extension: ## Managing Extensions -The extensions page of the admin dashboard provides a convenient way to manage extensions when they are installed. You can: +Each individual extension page of the admin dashboard provides a convenient way to manage the extension. You can: -- Enable or disable an extension -- Access extension settings (although some extensions will use a tab in the main sidebar for settings) +- Enable or disable the extension. +- See the settings provided by the extension, and change them. - Revert an extension's migrations to remove any database modifications it made (this can be done with the Purge button). This will remove ALL data associated with the extension, and is irreversible. It should only be done when you're removing an extension, and don't plan to install it again. It is also entirely optional. +- See the extension's README, if it has one. +- See the extension's version. +- Uninstall the extension if the extension manager is installed. + +## Configuring additional extension repository sources + +The extension manager uses `composer` under the hood, and as such, it looks for extension packages in the same places as `composer`. By default, this is [Packagist](https://packagist.org/). However, you can configure additional sources for the extension manager to look for extensions in. This is useful if you want to install an extension that is not available on Packagist. + +In the admin page of the extension manager, clicking the **Add Repository** button will open a modal where you can enter the name and URL of the repository you want to add. The name is just a label for the repository, and can be anything you want. The URL should be the URL of the repository which depends on the type of repository you want to add. + +### Adding a repository from a VCS + +If you want to add a repository from a VCS (e.g. GitHub, GitLab, BitBucket, etc), the URL should be the URL of the repository's VCS. For example, if you had a private GitHub repository at `https://github.com/acme/flarum-extension`, you would enter that URL into the URL field. If it is a private source, you will need to enter an authentication method through the **New authentication method** button. The token can be generated from your VCS provider's website, and the host should be the domain of the VCS provider (e.g. `github.com`). + +### Adding a composer repository + +Extiverse provides access to premium extensions. It is a good example of a composer repository. You would specify the URL as `https://extiverse.com/composer/` and the name as `extiverse`. You would also need to enter an authentication method through the **New authentication method** button. The token can be generated from your Extiverse account's subscriptions page. + +* Type: `HTTP Bearer` +* Host: `extiverse.com` + +![Configure repositories](/en/img/config-repositories.png) + +:::info + +The configured repositories and auth methods will be active for both the command line and the admin dashboard. If yu configure them from the command line however, you must not include the flag `--global`. + +::: + +## Installing Non-stable extensions + +If for whatever reason you want to install a non-stable extension (e.g. a beta, alpha or RC version) you must first update the **Minimum stability** setting to the wanted stability. + +* If you set it to Alpha, you will be able to install alpha, beta, RC (Release Candidate) and stable versions. +* If you set it to Beta, you will be able to install beta, RC and stable versions. +* If you set it to RC, you will be able to install RC and stable versions. +* If you set it to Stable, you will only be able to install stable versions. diff --git a/docs/install.md b/docs/install.md index 36f5a6d39..75f6e6001 100644 --- a/docs/install.md +++ b/docs/install.md @@ -13,18 +13,43 @@ Before you install Flarum, it's important to check that your server meets the re * **Apache** (with mod\_rewrite enabled) or **Nginx** * **PHP 7.3+** with the following extensions: curl, dom, fileinfo, gd, json, mbstring, openssl, pdo\_mysql, tokenizer, zip * **MySQL 5.6+/8.0.23+** or **MariaDB 10.0.5+** -* **SSH (command-line) access** to run Composer - -:::tip Shared Hosting - -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. Most decent hosts support SSH access, through which you should be able to install Composer and Flarum just fine. - -::: +* **SSH (command-line) access** to run potentially necessary software maintenance commands, and Composer if you intend on using the command-line to install and manage Flarum extensions. ## Installing +### Installing by unpacking an archive + +If you don't have SSH access to your server or you prefer not to use the command line, you can install Flarum by unpacking an archive. Below is a list of the available archives, make sure you choose the one that matches your PHP version and public path or lack thereof preference. + +| Flarum Version | PHP Version | Public Path | Type | Archive | +|----------------|-------------------|-------------|--------|-----------------------------------------------------------------------------------------------------------------------------------------------------------| +| 1.x | 8.3 (recommended) | No | ZIP | [flarum-v1.x-no-public-dir-php8.3.zip](https://github.com/flarum/installation-packages/raw/main/packages/v1.x/flarum-v1.x-no-public-dir-php8.3.zip) | +| 1.x | 8.3 (recommended) | Yes | TAR.GZ | [flarum-v1.x-php8.3.tar.gz](https://github.com/flarum/installation-packages/raw/main/packages/v1.x/flarum-v1.x-php8.3.tar.gz) | +| 1.x | 8.3 (recommended) | No | TAR.GZ | [flarum-v1.x-no-public-dir-php8.3.tar.gz](https://github.com/flarum/installation-packages/raw/main/packages/v1.x/flarum-v1.x-no-public-dir-php8.3.tar.gz) | +| 1.x | 8.3 (recommended) | Yes | ZIP | [flarum-v1.x-php8.3.zip](https://github.com/flarum/installation-packages/raw/main/packages/v1.x/flarum-v1.x-php8.3.zip) | +| 1.x | 8.2 (recommended) | No | TAR.GZ | [flarum-v1.x-no-public-dir-php8.2.tar.gz](https://github.com/flarum/installation-packages/raw/main/packages/v1.x/flarum-v1.x-no-public-dir-php8.2.tar.gz) | +| 1.x | 8.2 (recommended) | Yes | TAR.GZ | [flarum-v1.x-php8.2.tar.gz](https://github.com/flarum/installation-packages/raw/main/packages/v1.x/flarum-v1.x-php8.2.tar.gz) | +| 1.x | 8.2 (recommended) | No | ZIP | [flarum-v1.x-no-public-dir-php8.2.zip](https://github.com/flarum/installation-packages/raw/main/packages/v1.x/flarum-v1.x-no-public-dir-php8.2.zip) | +| 1.x | 8.2 (recommended) | Yes | ZIP | [flarum-v1.x-php8.2.zip](https://github.com/flarum/installation-packages/raw/main/packages/v1.x/flarum-v1.x-php8.2.zip) | +| 1.x | 8.1 | No | TAR.GZ | [flarum-v1.x-no-public-dir-php8.1.tar.gz](https://github.com/flarum/installation-packages/raw/main/packages/v1.x/flarum-v1.x-no-public-dir-php8.1.tar.gz) | +| 1.x | 8.1 | Yes | TAR.GZ | [flarum-v1.x-php8.1.tar.gz](https://github.com/flarum/installation-packages/raw/main/packages/v1.x/flarum-v1.x-php8.1.tar.gz) | +| 1.x | 8.1 | No | ZIP | [flarum-v1.x-no-public-dir-php8.1.zip](https://github.com/flarum/installation-packages/raw/main/packages/v1.x/flarum-v1.x-no-public-dir-php8.1.zip) | +| 1.x | 8.1 | Yes | ZIP | [flarum-v1.x-php8.1.zip](https://github.com/flarum/installation-packages/raw/main/packages/v1.x/flarum-v1.x-php8.1.zip) | +| 1.x | 8.0 (end of life) | No | TAR.GZ | [flarum-v1.x-no-public-dir-php8.0.tar.gz](https://github.com/flarum/installation-packages/raw/main/packages/v1.x/flarum-v1.x-no-public-dir-php8.0.tar.gz) | +| 1.x | 8.0 (end of life) | Yes | TAR.GZ | [flarum-v1.x-php8.0.tar.gz](https://github.com/flarum/installation-packages/raw/main/packages/v1.x/flarum-v1.x-php8.0.tar.gz) | +| 1.x | 8.0 (end of life) | No | ZIP | [flarum-v1.x-no-public-dir-php8.0.zip](https://github.com/flarum/installation-packages/raw/main/packages/v1.x/flarum-v1.x-no-public-dir-php8.0.zip) | +| 1.x | 8.0 (end of life) | Yes | ZIP | [flarum-v1.x-php8.0.zip](https://github.com/flarum/installation-packages/raw/main/packages/v1.x/flarum-v1.x-php8.0.zip) | +| 1.x | 7.4 (end of life) | No | TAR.GZ | [flarum-v1.x-no-public-dir-php7.4.tar.gz](https://github.com/flarum/installation-packages/raw/main/packages/v1.x/flarum-v1.x-no-public-dir-php7.4.tar.gz) | +| 1.x | 7.4 (end of life) | Yes | TAR.GZ | [flarum-v1.x-php7.4.tar.gz](https://github.com/flarum/installation-packages/raw/main/packages/v1.x/flarum-v1.x-php7.4.tar.gz) | +| 1.x | 7.4 (end of life) | No | ZIP | [flarum-v1.x-no-public-dir-php7.4.zip](https://github.com/flarum/installation-packages/raw/main/packages/v1.x/flarum-v1.x-no-public-dir-php7.4.zip) | +| 1.x | 7.4 (end of life) | Yes | ZIP | [flarum-v1.x-php7.4.zip](https://github.com/flarum/installation-packages/raw/main/packages/v1.x/flarum-v1.x-php7.4.zip) | +| 1.x | 7.3 (end of life) | No | TAR.GZ | [flarum-v1.x-no-public-dir-php7.3.tar.gz](https://github.com/flarum/installation-packages/raw/main/packages/v1.x/flarum-v1.x-no-public-dir-php7.3.tar.gz) | +| 1.x | 7.3 (end of life) | Yes | TAR.GZ | [flarum-v1.x-php7.3.tar.gz](https://github.com/flarum/installation-packages/raw/main/packages/v1.x/flarum-v1.x-php7.3.tar.gz) | +| 1.x | 7.3 (end of life) | No | ZIP | [flarum-v1.x-no-public-dir-php7.3.zip](https://github.com/flarum/installation-packages/raw/main/packages/v1.x/flarum-v1.x-no-public-dir-php7.3.zip) | +| 1.x | 7.3 (end of life) | Yes | ZIP | [flarum-v1.x-php7.3.zip](https://github.com/flarum/installation-packages/raw/main/packages/v1.x/flarum-v1.x-php7.3.zip) | + +### Installing using the Command Line Interface + 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 @@ -35,6 +60,18 @@ While this command is running, you can configure your web server. You will need When everything is ready, navigate to your forum in a web browser and follow the instructions to complete the installation. +If you wish to install and update extensions from the admin dashboard, you need to also install the [Extension Manager](extensions.md) extension. + +```bash +composer require flarum/extension-manager:* +``` + +:::warning + +The extension manager allows an admin user to install any composer package. Only install the extension manager if you trust all of your forum admins with such permissions. + +::: + ## URL Rewriting ### Apache @@ -131,6 +168,8 @@ By default Flarum's directory structure includes a `public` directory which cont However, if you wish to host Flarum in a subdirectory (like `yoursite.com/forum`), or if your host doesn't give you control over your webroot (you're stuck with something like `public_html` or `htdocs`), you can set up Flarum without the `public` directory. +If you intend to install Flarum using one of the archives, you can simply use the `no-public-dir` (Public Path = No) [archives](#installing-by-unpacking-an-archive) and skip the rest of this section. If you're installing via Composer, you'll need to follow the instructions below. + Simply move all the files inside the `public` directory (including `.htaccess`) into the directory you want to serve Flarum from. Then edit `.htaccess` and uncomment lines 9-15 in order to protect sensitive resources. For Nginx, uncomment lines 8-11 of `.nginx.conf`. You will also need to edit the `index.php` file and change the following line: diff --git a/docs/internal/package-manager.md b/docs/internal/extension-manager.md similarity index 90% rename from docs/internal/package-manager.md rename to docs/internal/extension-manager.md index dbd407e7a..de9ee751f 100644 --- a/docs/internal/package-manager.md +++ b/docs/internal/extension-manager.md @@ -1,5 +1,7 @@ -# Package Manager -This contains an explanation of how the package manager works and what it has to offer. +# Extension Manager +This contains an explanation of how the extension manager works and what it has to offer. + +slightly outdated: see [the extensions guide for more](/extensions.md). ## Contents * Installing, Updating, and Removing Extensions. @@ -19,9 +21,9 @@ The relevant machine web user needs to have permissions to read and write to: `v ![flarum lan_admin (3)](https://user-images.githubusercontent.com/20267363/135268536-f79d42ab-6e05-4e41-b2ab-d95ec7a8b021.png) ### Path Repository -In development environments (and production in rare scenarios) there should a path repository to a directory containing (mostly dev) packages, the path to this directory must be changed to an absolute path otherwise composer will have trouble running any command. Additionally the path repository by default has higher priority, so requiring an extension that exists in that repository will probably fail, unless a `*@dev` constraint is specified, in which case the package manager should not be used for dev purposes anyway. +In development environments (and production in rare scenarios) there should a path repository to a directory containing (mostly dev) packages, the path to this directory must be changed to an absolute path otherwise composer will have trouble running any command. Additionally the path repository by default has higher priority, so requiring an extension that exists in that repository will probably fail, unless a `*@dev` constraint is specified, in which case the extension manager should not be used for dev purposes anyway. -There is currently now hint of any of this in the package manager UI. +There is currently now hint of any of this in the extension manager UI. ## Common Actions Each one of the features listed above is basically a composer command or two, and there are common actions/common behaviour between them all. @@ -79,12 +81,8 @@ It is common for shared hosts to have a low php version used in SSH, users must ::: -![Package Manager Queue Table Preview](/en/img/package-manager-queue.png) +![Extension Manager Queue Table Preview](/en/img/extension-manager-queue.png) ## TODO - Try on shared hosting. -- Composer command job must not overlap. -- Code TODOs. - Better explanation on the UI about background tasks. -- Take into consideration a scenario where we're updating an extension that isn't a root required dependency, like bundles. -- Run one background task at a time, prevent user from triggering multiple tasks. diff --git a/docs/update.md b/docs/update.md index 76000acec..21b090eb2 100644 --- a/docs/update.md +++ b/docs/update.md @@ -1,5 +1,15 @@ # Updating +## From the Admin Dashboard + +:::info + +If you have the extension manager extension installed you can simply run the update from its interface and skip this page entirely. + +::: + +--- + 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 appropriate "major version update guide" before running the general upgrade steps. diff --git a/sidebars.js b/sidebars.js index ea2371246..330154fbb 100644 --- a/sidebars.js +++ b/sidebars.js @@ -150,7 +150,7 @@ module.exports = { 'internal/README', 'internal/merging-policy', 'internal/bundled-extensions-policy', - 'internal/package-manager', + 'internal/extension-manager', ] }, ] diff --git a/static/en/img/config-repositories.png b/static/en/img/config-repositories.png new file mode 100644 index 000000000..7e42f3183 Binary files /dev/null and b/static/en/img/config-repositories.png differ diff --git a/static/en/img/package-manager-queue.png b/static/en/img/extension-manager-queue.png similarity index 100% rename from static/en/img/package-manager-queue.png rename to static/en/img/extension-manager-queue.png diff --git a/static/en/img/install-extension.png b/static/en/img/install-extension.png new file mode 100644 index 000000000..4d88f5156 Binary files /dev/null and b/static/en/img/install-extension.png differ diff --git a/static/en/img/uninstall-extension.png b/static/en/img/uninstall-extension.png new file mode 100644 index 000000000..4a4e1404d Binary files /dev/null and b/static/en/img/uninstall-extension.png differ diff --git a/static/en/img/update-extension.png b/static/en/img/update-extension.png new file mode 100644 index 000000000..71ef48d02 Binary files /dev/null and b/static/en/img/update-extension.png differ