「Grav」の版間の差分

提供: ArchWiki
ナビゲーションに移動 検索に移動
(→‎Installation: リンクを修正)
(記事を更新)
23行目: 23行目:
   
 
* A web server: [[Apache HTTP Server]] or [[nginx]] or others
 
* A web server: [[Apache HTTP Server]] or [[nginx]] or others
* An application server: [[uWSGI]] (together with {{pkg|uwsgi-plugin-php}}) or [https://cwiki.apache.org/confluence/display/HTTPD/PHP-FPM php-fpm]
+
* An application server: [[uWSGI]] (together with {{pkg|uwsgi-plugin-php}}) or [https://cwiki.apache.org/confluence/display/HTTPD/PHP-FPM FPM]
   
 
The following combinations will be covered:
 
The following combinations will be covered:
   
 
* nginx → uWSGI (plus uwsgi-plugin-php)
 
* nginx → uWSGI (plus uwsgi-plugin-php)
* nginx → php-fpm,
+
* nginx → FPM,
 
* Apache (using mod_proxy_uwsgi) → uWSGI (plus uwsgi-plugin-php)
 
* Apache (using mod_proxy_uwsgi) → uWSGI (plus uwsgi-plugin-php)
* Apache (using mod_proxy_fcgi) → php-fpm
+
* Apache (using mod_proxy_fcgi) → FPM
   
The installation of Grav complies with Arch Linux' [[ウェブアプリケーションパッケージガイドライン]]. This means among other details that Grav must be run with its own system user (''grav''). So it is not possible anymore to execute the PHP code directly in the Apache process by means of {{pkg|php-apache}}.
+
The installation of Grav complies with Arch Linux' [[web application package guidelines]]. This means among other details that Grav must be run with its own system user (''grav''). So it is not possible anymore to execute the PHP code directly in the Apache process by means of {{pkg|php-apache}}.
   
 
== Installation ==
 
== Installation ==
   
[[インストール]] the {{aur|grav}} package. This automatically takes care of installing the two requires dependencies {{Pkg|php}} and {{pkg|php-gd}}. Also install {{pkg|php-apcu}} and {{aur|php-yaml}} - preferrably as a dependency ({{ic|--asdeps}}). Comment the only line in {{ic|/etc/php/conf.d/yaml.ini}}. Do not modify {{ic|/etc/php/conf.d/apcu.ini}}, i.e. leave the only line commented. Activating these two extensions for Grav will be taken care of in other places (see below).
+
[[Install]] the {{aur|grav}} package. This automatically takes care of installing the two requires dependencies {{Pkg|php}} and {{pkg|php-gd}}. Also install {{pkg|php-apcu}} and {{aur|php-yaml}} - preferrably as a dependency ({{ic|--asdeps}}). Comment the only line in {{ic|/etc/php/conf.d/yaml.ini}}. Do not modify {{ic|/etc/php/conf.d/apcu.ini}}, i.e. leave the only line commented. Activating these two extensions for Grav will be taken care of in other places (see below).
   
 
== Application server ==
 
== Application server ==
   
There are two prevalent application servers that can be used to process PHP code: [[uWSGI]] or [https://cwiki.apache.org/confluence/display/HTTPD/PHP-FPM php-fpm]. ''php-fpm'' as the name suggests is specialized on PHP. The protocol used between the web server and ''php-fpm'' is ''fastcgi''. The tool is has been [https://www.php.net/manual/en/install.fpm.php part of the PHP distribution] since many years and is actively maintained. The downside being that the [https://www.php.net/manual/en/install.fpm.configuration.php official documentation] leaves much room for improvement. ''uWSGI'' on the other hand can serve code written in a [https://uwsgi-docs.readthedocs.io/en/latest/LanguagesAndPlatforms.html handful of languages] by means of language specific plugins. The protocol used is ''uwsgi'' (lowercase). The tool is [https://uwsgi-docs.readthedocs.io/en/latest/index.html extensively documented] - albeit the sheer amount of documentation can become confusing and unwieldy. Maintainance has [https://github.com/unbit/uwsgi/commits/master slowed down] significantly - this applies especially for the [https://github.com/unbit/uwsgi/commits/master/plugins/php PHP plugin].
+
There are two prevalent application servers that can be used to process PHP code: [[uWSGI]] or [https://cwiki.apache.org/confluence/display/HTTPD/PHP-FPM FPM]. ''FPM'' as the name suggests is specialized on PHP. The protocol used between the web server and ''FPM'' is ''fastcgi''. The tool is has been [https://www.php.net/manual/en/install.fpm.php part of the PHP distribution] since many years and is actively maintained. The downside being that the [https://www.php.net/manual/en/install.fpm.configuration.php official documentation] leaves much room for improvement. ''uWSGI'' on the other hand can serve code written in a [https://uwsgi-docs.readthedocs.io/en/latest/LanguagesAndPlatforms.html handful of languages] by means of language specific plugins. The protocol used is ''uwsgi'' (lowercase). The tool is [https://uwsgi-docs.readthedocs.io/en/latest/index.html extensively documented] - albeit the sheer amount of documentation can become confusing and unwieldy. Maintainance has [https://github.com/unbit/uwsgi/commits/master slowed down] significantly - this applies especially for the [https://github.com/unbit/uwsgi/commits/master/plugins/php PHP plugin].
   
 
=== uWSGI ===
 
=== uWSGI ===
   
{{Warning|As of 2022-01-04 when PHP 8.1 became available in Arch Linux' Extra repository the PHP plugin of uWSGI was broken. As of release 2.0.20-5 it is working for now but note there are [https://bugs.archlinux.org/task/73470#comment205447 concerns] about the long-term viability of the project. (See {{Bug|73470}})}}
+
{{Warning|As of 2022-01-04 when PHP 8.1 became available in Arch Linux' Extra repository the PHP plugin of uWSGI was broken. (See {{Bug|73470}}) As of release 2.0.20-5 of this plugin it is working for now but note there are [https://github.com/unbit/uwsgi/issues/2287 concerns] about the long-term viability of the project.}}
   
 
uWSGI has its own [[uWSGI|article]]. A lot of useful information can be found there. Install {{pkg|uwsgi}} and the plugin {{pkg|uwsgi-plugin-php}} - preferrably as dependencies, i.e. with {{ic|--asdeps}}. Setup of your Grav application requires only copying one file and defining one systemd service.
 
uWSGI has its own [[uWSGI|article]]. A lot of useful information can be found there. Install {{pkg|uwsgi}} and the plugin {{pkg|uwsgi-plugin-php}} - preferrably as dependencies, i.e. with {{ic|--asdeps}}. Setup of your Grav application requires only copying one file and defining one systemd service.
   
'''grav.ini'''
+
==== grav.ini ====
   
 
Copy the Grav specific uWSGI setup file to the appropriate location.
 
Copy the Grav specific uWSGI setup file to the appropriate location.
   
{{bc|cp /usr/share/webapps/grav/webserver-configs/uwsgi-grav.ini /etc/uwsgi/grav.ini}}
+
# cp /usr/share/webapps/grav/webserver-configs/uwsgi-grav.ini /etc/uwsgi/grav.ini
   
 
Make sure {{ic|grav.ini}} is owned and only writeable by root, i.e. {{ic|-rw-r--r-- 1 root root ... grav.ini}}. This configuration is functional but feel free to adapt it to your liking. E.g. you might like to change {{ic|1=php-set = date.timezone=}} to your preferred timezone.
 
Make sure {{ic|grav.ini}} is owned and only writeable by root, i.e. {{ic|-rw-r--r-- 1 root root ... grav.ini}}. This configuration is functional but feel free to adapt it to your liking. E.g. you might like to change {{ic|1=php-set = date.timezone=}} to your preferred timezone.
   
  +
==== Systemd service ====
'''Enable and start'''
 
   
 
The package {{pkg|uwsgi}} provides a template unit file ({{ic|uwsgi@.service}}). The instance ID (here ''grav'') is used to pick up the right configuration file. So we [[start/enable]] {{ic|uwsgi@grav.service}}.
 
The package {{pkg|uwsgi}} provides a template unit file ({{ic|uwsgi@.service}}). The instance ID (here ''grav'') is used to pick up the right configuration file. So we [[start/enable]] {{ic|uwsgi@grav.service}}.
   
In case you have more than a few (e.g. 2) services started like this and get the impression this is a waste of resource you might consider using [https://uwsgi-docs.readthedocs.io/en/latest/Emperor.html emporer mode].
+
In case you have more than a few (e.g. 2) services started like this and get the impression this is a waste of resource you might consider using [https://uwsgi-docs.readthedocs.io/en/latest/Emperor.html emperor mode].
   
=== php-fpm ===
+
=== FPM ===
   
In case you opt to use ''php-fpm'' as your application server install {{pkg|php-fpm}} - preferrably as a dependent package ({{ic|--asdeps}}).
+
In case you opt to use ''FPM'' as your application server install {{pkg|php-fpm}} - preferrably as a dependent package ({{ic|--asdeps}}).
   
 
You have to tweak its configuration a little bit.
 
You have to tweak its configuration a little bit.
   
'''php-fpm.ini'''
+
==== php-fpm.ini ====
   
It is a good practice to run ''php-fpm'' with its own version of {{ic|php.ini}}. You thus avoid cluttering the standard INI file ({{ic|/etc/php/php.ini}}) with stuff only needed by '' php-fpm''. There is a copy of a functional INI file in {{ic|/usr/share/webapps/grav/webserver-configs}}. Copy it to {{ic|/etc/php}}.
+
It is a good practice to run ''FPM'' with its own version of {{ic|php.ini}}. You thus avoid cluttering the standard INI file ({{ic|/etc/php/php.ini}}) with stuff only needed by ''FPM''. There is a copy of a functional INI file in {{ic|/usr/share/webapps/grav/webserver-configs}}. Copy it to {{ic|/etc/php}}.
   
{{bc|cp /usr/share/webapps/grav/webserver-configs/php-fpm.ini /etc/php}}
+
# cp /usr/share/webapps/grav/webserver-configs/php-fpm.ini /etc/php
   
 
Make sure it is owned and only writeable by root. Something along {{ic|-rw-r--r-- 1 root root ... php-fpm.ini}}. Feel free to customize the configuration as you see fit.
 
Make sure it is owned and only writeable by root. Something along {{ic|-rw-r--r-- 1 root root ... php-fpm.ini}}. Feel free to customize the configuration as you see fit.
   
  +
==== grav.conf ====
'''php-fpm service'''
 
   
  +
You have to create a so called ''pool file'' for ''FPM''. It is responsible for spawning a dedicated ''FPM'' process for the Grav application. Copy the version provided by the {{aur|grav}} package.
''php-fpm'' is (of course) run as a systemd service. You have to modify the service configuration to be able to run Grav. This is best achieved by means of a [[drop-in file]]. The content of the drop-in file can be found in {{ic|/usr/share/webapps/grav/webserver-configs/php-fpm.service.d/override.conf}}. [[Edit]] {{ic|php-fpm.service}} to create the file and copy over the content. The drop-in file has three purposes.
 
   
  +
# cp /usr/share/webapps/grav/webserver-configs/php-fpm.d/grav.conf /etc/php/php-fpm.d
* It replaces the {{ic|ExecStart}} line by a start command that uses the {{ic|php-fpm.ini}} covered in the previous section.
 
* It disables the {{ic|ProtectSystem}} option since Grav requires to be able to write to {{ic|/etc/webapps/grav}}.
 
* It disables the {{ic|PrivateTmp}} option. Although a sensible option it has to be turned off so that the {{aur|grav}} package can also be used with other application servers.
 
   
  +
Again make sure this pool file is owned and only writeable by root (i.e. {{ic|-rw-r--r-- 1 root root ... grav.conf}}). You may tweak some settings (especially {{ic|pm...}} and {{ic|php_admin_value[date.timezone]}} to your liking.
'''grav.conf pool file'''
 
   
  +
{{Tip|The package {{pkg|php-fpm}} comes with its own pool file {{ic|www.conf}} that is of little use here. A good approach to get rid of it is to rename it to {{ic|www.conf.package}} and create a file {{ic|www.conf}} with only comment lines (lines starting with a semicolon). This way {{ic|www.conf}} becomes a no-op. It is also not overwritten during installation of a new version of {{pkg|php-fpm}}. Instead a file {{ic|www.conf.pacnew}} is created. You can compare this against {{ic|www.conf.package}} to see if anything significant has changed in the pool file that you may have to reproduce in {{ic|grav.conf}}. Do not forget to rename {{ic|www.conf.pacnew}} to {{ic|www.conf.package}} at the end of this procedure.}}
Finally you have to create a so called ''pool file'' for ''php-fpm''. It is responsible for spawning a dedicated ''php-fpm'' process for the Grav application. Copy the version provided by the {{aur|grav}} package.
 
   
  +
==== Systemd service ====
{{bc|cp /usr/share/webapps/grav/webserver-configs/php-fpm.d/grav.conf /etc/php/php-fpm.d}}
 
   
  +
''FPM'' is run as a systemd service. You have to modify the service configuration to be able to run Grav. This is best achieved by means of a [[drop-in file]].
Again make sure this pool file is owned and only writeable by root (i.e. {{ic|-rw-r--r-- 1 root root ... grav.conf}}). You may tweak some settings (especially {{ic|pm...}} and {{ic|php_admin_value[date.timezone]}} to your liking.
 
   
  +
{{hc|1=/etc/systemd/system/php-fpm.service.d/override.conf|2=
{{Tip|The package {{pkg|php-fpm}} comes with its own pool file {{ic|www.conf}} that is of little use here. A good approach to get rid of it is to rename it to {{ic|www.conf.package}} and create a file {{ic|www.conf}} with only comment lines (lines starting with a semicolon). This way {{ic|www.conf}} becomes a no-op. It is also not overwritten during installation of a new version of {{pkg|php-fpm}}. Instead a file {{ic|www.conf.pacnew}} is created. You can compare this against {{ic|www.conf.package}} to see if anything significant has changed in the pool file that you may have to reproduce in {{ic|grav.conf}}. Do not forget to rename {{ic|www.conf.pacnew}} to {{ic|www.conf.package}} at the end of this procedure.}}
 
  +
[Service]
  +
ExecStart=
  +
ExecStart=/usr/bin/php-fpm --nodaemonize --fpm-config /etc/php/php-fpm.conf --php-ini /etc/php/php-fpm.ini
  +
ReadWritePaths=/etc/webapps/grav/config
  +
PrivateTmp=false
  +
}}
   
  +
The drop-in file has three purposes.
'''Enable and start'''
 
  +
  +
* It replaces the {{ic|ExecStart}} line by a start command that uses the {{ic|php-fpm.ini}} covered in the previous section.
  +
* It explicitly enables read/write access on {{ic|/etc/webapps/grav/config}} that would otherwise be inhibited by {{ic|1=ProtectSystem=full}} in {{ic|/usr/lib/systemd/system/php-fpm.service}}.
  +
* It disables the {{ic|PrivateTmp}} option set in {{ic|/usr/lib/systemd/system/php-fpm.service}} as this doesn't work together with {{ic|1=php_admin_value[open_basedir] = …:/var/tmp/$pool:…}} in {{ic|/etc/php/php-fpm.d/grav.conf}}.
   
 
Do not forget to [[start/enable]] {{ic|php-fpm.service}}.
 
Do not forget to [[start/enable]] {{ic|php-fpm.service}}.
117行目: 125行目:
 
* The location where [[Certbot]] (or any other ACME client) will put the domain verification challenges.
 
* The location where [[Certbot]] (or any other ACME client) will put the domain verification challenges.
 
* The path under which your Grav installation will be reachable. (The part right to the server name & port section in the URL.)
 
* The path under which your Grav installation will be reachable. (The part right to the server name & port section in the URL.)
* What application server (uWSGI or php-fpm) you are using, i.e. how and where nginx will pass requests that need to trigger some PHP code.
+
* What application server (uWSGI or FPM) you are using, i.e. how and where nginx will pass requests that need to trigger some PHP code.
   
 
There is no need to install any additional modules since nginx natively supports both protocols FastCGI and uwsgi.
 
There is no need to install any additional modules since nginx natively supports both protocols FastCGI and uwsgi.
125行目: 133行目:
 
=== Apache HTTP Server ===
 
=== Apache HTTP Server ===
   
Unfortunately upstream Grav does not provide a sample configuration file for [[Apache HTTP Server]]. At least there is a [[Apache_HTTP_Server#Using_php-fpm_and_mod_proxy_fcgi|section]] in this wiki about how to integrate Apache with PHP by means of php-fpm and mod_proxy_fcgi. uWSGI's [https://uwsgi-docs.readthedocs.io/en/latest/Apache.html documentation] has some information about how to integrate Apache with PHP by means of uWSGI and mod_proxy_uwsgi. Mind that the {{pkg|apache}} package comes with both modules mod_proxy_fcgi and mod_proxy_uwsgi. They need to be loaded as required.
+
Unfortunately upstream Grav does not provide a sample configuration file for [[Apache HTTP Server]]. At least there is a [[Apache HTTP Server#Using php-fpm and mod_proxy_fcgi|section]] in this wiki about how to integrate Apache with PHP by means of FPM and mod_proxy_fcgi. uWSGI's [https://uwsgi-docs.readthedocs.io/en/latest/Apache.html documentation] has some information about how to integrate Apache with PHP by means of uWSGI and mod_proxy_uwsgi. Mind that the {{pkg|apache}} package comes with both modules mod_proxy_fcgi and mod_proxy_uwsgi. They need to be loaded as required.
   
 
== Plugins ==
 
== Plugins ==
131行目: 139行目:
 
A lot of Grav's power comes from the large [https://getgrav.org/downloads/plugins set of plugins] that can be installed. Just follow the [https://learn.getgrav.org/17/plugins/plugin-install instructions] on Grav's documentation how to install plugins.
 
A lot of Grav's power comes from the large [https://getgrav.org/downloads/plugins set of plugins] that can be installed. Just follow the [https://learn.getgrav.org/17/plugins/plugin-install instructions] on Grav's documentation how to install plugins.
   
{{Note|When installing plugins from the command line make sure to perform these commands as user ''grav''. E.g. {{bc|runuser -u grav -- bin/gpm install admin}} Otherwise you will sooner or later run into permission issues.}}
+
{{Note|When installing plugins from the command line make sure to perform these commands as user ''grav''. E.g. {{bc|# runuser -u grav -- bin/gpm install admin}} Otherwise you will sooner or later run into permission issues.}}
   
 
Currently there are no ''grav-plugin-...'' packages that allow installing plugins via {{ic|pacman}} (or some AUR wrapper). This will probably not change in the foreseeable future.
 
Currently there are no ''grav-plugin-...'' packages that allow installing plugins via {{ic|pacman}} (or some AUR wrapper). This will probably not change in the foreseeable future.
148行目: 156行目:
   
 
# Download the desired skeleton.
 
# Download the desired skeleton.
# Extract the {{ic|user}} directory: {{bc|bsdtar -xf grav-skeleton-blahblah.zip user}}
+
# Extract the {{ic|user}} directory: {{bc|# bsdtar -xf grav-skeleton-blahblah.zip user}}
 
# Replace the directories {{ic|pages}}, {{ic|plugins}} and {{ic|themes}} in {{ic|/var/lib/grav/user}} with the corresponding directories from the extracted {{ic|user}} directory.
 
# Replace the directories {{ic|pages}}, {{ic|plugins}} and {{ic|themes}} in {{ic|/var/lib/grav/user}} with the corresponding directories from the extracted {{ic|user}} directory.
# Fix ownership and permissions {{bc|chown -R grav:http /var/lib/grav/user/{pages,plugins,themes}<br />chmod -R 640 /var/lib/grav/user/{pages,plugins,themes}<br />find /var/lib/grav/user/{pages,plugins,themes} -type d -exec chmod 750 {} \;}}
+
# Fix ownership and permissions {{bc|# chown -R grav:http /var/lib/grav/user/{pages,plugins,themes}<br /># chmod -R 640 /var/lib/grav/user/{pages,plugins,themes}<br /># find /var/lib/grav/user/{pages,plugins,themes} -type d -exec chmod 750 {} \;}}
# Replace the config files {{ic|site.yaml}} {{ic|system.yaml}} in {{ic|/etc/webapps/grav/config}} with the corresponding files from the extracted {{ic|user/config}}.
+
# Replace the configuration files {{ic|site.yaml}} {{ic|system.yaml}} in {{ic|/etc/webapps/grav/config}} with the corresponding files from the extracted {{ic|user/config}}.
# Fix ownership and permissions {{bc|chown grav:grav /etc/webapps/grav/config/{site,system}.yaml<br />chmod 644 /etc/webapps/grav/config/{site,system}.yaml}}
+
# Fix ownership and permissions {{bc|# chown grav:grav /etc/webapps/grav/config/{site,system}.yaml<br /># chmod 644 /etc/webapps/grav/config/{site,system}.yaml}}
   
== Migration v1.6 &rarr; v1.7 ==
+
== Migrating from v1.6 to v1.7 ==
   
 
{{Note|Migrating from earlier versions (< 1.7) of the package has been poorly tested (due to technical reasons). Please help to improve this section.}}
 
{{Note|Migrating from earlier versions (< 1.7) of the package has been poorly tested (due to technical reasons). Please help to improve this section.}}
168行目: 176行目:
 
Do not try to tweak your setup to use system user ''http'' as used to be. For good reasons Arch Linux' [[web application package guidelines]] dictates to use a dedicated system user (here ''grav'') to run the application.
 
Do not try to tweak your setup to use system user ''http'' as used to be. For good reasons Arch Linux' [[web application package guidelines]] dictates to use a dedicated system user (here ''grav'') to run the application.
   
Probably the best migration strategy is to backup the {{ic|/usr/share/webapps/grav/user}} directory, uninstall Grav and all [[Pacman/Tips_and_tricks#Removing_unused_packages_(orphans)|dependent packages]], remove all remnants of the Grav installation (including all Grav specific configurations with your web server and application server), update your system (including PHP) and then install Grav from scratch. When everything is set up and your server successfully presents Grav's default page you can start to restore your previous content.
+
Probably the best migration strategy is to backup the {{ic|/usr/share/webapps/grav/user}} directory, uninstall Grav and all [[pacman/Tips and tricks#Removing unused packages (orphans)|dependent packages]], remove all remnants of the Grav installation (including all Grav specific configurations with your web server and application server), update your system (including PHP) and then install Grav from scratch. When everything is set up and your server successfully presents Grav's default page you can start to restore your previous content.
   
 
== Upgrade ==
 
== Upgrade ==
176行目: 184行目:
 
{{Warning|Do not try to upgrade Grav itself with {{ic|gpm}} as described in Grav's [https://learn.getgrav.org/17/basics/updates update documentation] or via the admin plugin. At best this will simply not work, at worst it will ruin your installation.}}
 
{{Warning|Do not try to upgrade Grav itself with {{ic|gpm}} as described in Grav's [https://learn.getgrav.org/17/basics/updates update documentation] or via the admin plugin. At best this will simply not work, at worst it will ruin your installation.}}
   
To the contrary upgrading plugins and themes must be done with {{ic|gpm update}} or via the admin plugin.
+
Unlike upgrading Grav itself, upgrading plugins and themes must be done with {{ic|gpm update}} or via the admin plugin.
   
 
Also not recommended is to download Grav releases as ZIP archives directly from Grav's GitHub project site and copy around stuff in the filesystem. Only do so when you know exactly what you are doing.
 
Also not recommended is to download Grav releases as ZIP archives directly from Grav's GitHub project site and copy around stuff in the filesystem. Only do so when you know exactly what you are doing.

2023年4月11日 (火) 18:38時点における版

関連記事

Wikipedia より:

Grav は、PHP プログラミング言語と Symfony Web アプリケーションフレームワークをベースして書かれたフリーソフトウェアでセルフホスト型のコンテンツ管理システム(CMS)です。バックエンドとフロントエンドの両方でフラットファイルデータベースを使用します。
Grav は学習曲線が浅く、セットアップが簡単であるように設計されています。Grav の焦点は、複雑さを犠牲にした豊富な組み込み機能よりも、スピードとシンプルさです。

Prerequisites

Grav comes with surprisingly few prerequisites by itself. Of course as a web application written in PHP it needs PHP. The only required PHP module is php-gd. A few others are also required but already part of the bare PHP installation. The following PHP modules are optional but highly recommended for better performance:

  • php-apcu for increased cache performance
  • php-yamlAUR for native YAML processing dramatically increasing performance

Although Grav can serve the content on its own this article describes a setup with a full blown web server in front. So you need:

The following combinations will be covered:

  • nginx → uWSGI (plus uwsgi-plugin-php)
  • nginx → FPM,
  • Apache (using mod_proxy_uwsgi) → uWSGI (plus uwsgi-plugin-php)
  • Apache (using mod_proxy_fcgi) → FPM

The installation of Grav complies with Arch Linux' web application package guidelines. This means among other details that Grav must be run with its own system user (grav). So it is not possible anymore to execute the PHP code directly in the Apache process by means of php-apache.

Installation

Install the gravAUR package. This automatically takes care of installing the two requires dependencies php and php-gd. Also install php-apcu and php-yamlAUR - preferrably as a dependency (--asdeps). Comment the only line in /etc/php/conf.d/yaml.ini. Do not modify /etc/php/conf.d/apcu.ini, i.e. leave the only line commented. Activating these two extensions for Grav will be taken care of in other places (see below).

Application server

There are two prevalent application servers that can be used to process PHP code: uWSGI or FPM. FPM as the name suggests is specialized on PHP. The protocol used between the web server and FPM is fastcgi. The tool is has been part of the PHP distribution since many years and is actively maintained. The downside being that the official documentation leaves much room for improvement. uWSGI on the other hand can serve code written in a handful of languages by means of language specific plugins. The protocol used is uwsgi (lowercase). The tool is extensively documented - albeit the sheer amount of documentation can become confusing and unwieldy. Maintainance has slowed down significantly - this applies especially for the PHP plugin.

uWSGI

警告: As of 2022-01-04 when PHP 8.1 became available in Arch Linux' Extra repository the PHP plugin of uWSGI was broken. (See FS#73470) As of release 2.0.20-5 of this plugin it is working for now but note there are concerns about the long-term viability of the project.

uWSGI has its own article. A lot of useful information can be found there. Install uwsgi and the plugin uwsgi-plugin-php - preferrably as dependencies, i.e. with --asdeps. Setup of your Grav application requires only copying one file and defining one systemd service.

grav.ini

Copy the Grav specific uWSGI setup file to the appropriate location.

# cp /usr/share/webapps/grav/webserver-configs/uwsgi-grav.ini /etc/uwsgi/grav.ini

Make sure grav.ini is owned and only writeable by root, i.e. -rw-r--r-- 1 root root ... grav.ini. This configuration is functional but feel free to adapt it to your liking. E.g. you might like to change php-set = date.timezone= to your preferred timezone.

Systemd service

The package uwsgi provides a template unit file (uwsgi@.service). The instance ID (here grav) is used to pick up the right configuration file. So we start/enable uwsgi@grav.service.

In case you have more than a few (e.g. 2) services started like this and get the impression this is a waste of resource you might consider using emperor mode.

FPM

In case you opt to use FPM as your application server install php-fpm - preferrably as a dependent package (--asdeps).

You have to tweak its configuration a little bit.

php-fpm.ini

It is a good practice to run FPM with its own version of php.ini. You thus avoid cluttering the standard INI file (/etc/php/php.ini) with stuff only needed by FPM. There is a copy of a functional INI file in /usr/share/webapps/grav/webserver-configs. Copy it to /etc/php.

# cp /usr/share/webapps/grav/webserver-configs/php-fpm.ini /etc/php

Make sure it is owned and only writeable by root. Something along -rw-r--r-- 1 root root ... php-fpm.ini. Feel free to customize the configuration as you see fit.

grav.conf

You have to create a so called pool file for FPM. It is responsible for spawning a dedicated FPM process for the Grav application. Copy the version provided by the gravAUR package.

# cp /usr/share/webapps/grav/webserver-configs/php-fpm.d/grav.conf /etc/php/php-fpm.d

Again make sure this pool file is owned and only writeable by root (i.e. -rw-r--r-- 1 root root ... grav.conf). You may tweak some settings (especially pm... and php_admin_value[date.timezone] to your liking.

ヒント: The package php-fpm comes with its own pool file www.conf that is of little use here. A good approach to get rid of it is to rename it to www.conf.package and create a file www.conf with only comment lines (lines starting with a semicolon). This way www.conf becomes a no-op. It is also not overwritten during installation of a new version of php-fpm. Instead a file www.conf.pacnew is created. You can compare this against www.conf.package to see if anything significant has changed in the pool file that you may have to reproduce in grav.conf. Do not forget to rename www.conf.pacnew to www.conf.package at the end of this procedure.

Systemd service

FPM is run as a systemd service. You have to modify the service configuration to be able to run Grav. This is best achieved by means of a drop-in file.

/etc/systemd/system/php-fpm.service.d/override.conf
[Service]
ExecStart=
ExecStart=/usr/bin/php-fpm --nodaemonize --fpm-config /etc/php/php-fpm.conf --php-ini /etc/php/php-fpm.ini
ReadWritePaths=/etc/webapps/grav/config
PrivateTmp=false

The drop-in file has three purposes.

  • It replaces the ExecStart line by a start command that uses the php-fpm.ini covered in the previous section.
  • It explicitly enables read/write access on /etc/webapps/grav/config that would otherwise be inhibited by ProtectSystem=full in /usr/lib/systemd/system/php-fpm.service.
  • It disables the PrivateTmp option set in /usr/lib/systemd/system/php-fpm.service as this doesn't work together with php_admin_value[open_basedir] = …:/var/tmp/$pool:… in /etc/php/php-fpm.d/grav.conf.

Do not forget to start/enable php-fpm.service.

Web server

There is an abundance of web servers you can choose from. Whatever option you finally choose you have to keep in mind that the Grav application needs to be run with its own system user grav. So you probably need to forward your requests to one of the above mentioned application servers.

警告: Some of the web server specific sample files provided in /usr/share/webapps/grav/webserver-configs (except nginx.conf) might be outdated.

nginx

Configuration of nginx is way beyond the scope of this article. See the relevant article for further information. The package gravAUR comes with a sample configuration file /usr/share/webapps/grav/webserver-configs/nginx.conf. This file is not functional as is. Use it as a starting point for your own configuration. Most likely you will have to copy it into /etc/nginx/sites-available with an appropriate name and create the corresponding symbolic link in /etc/nginx/sites-enabled.

The sample file assumes you are using SSL/TLS and some ACME client (e.g. Certbot) to get your certificates. OCSP stapling is not configured.

Things you might have to adapt (not exhaustive):

  • Your server name (server_name clauses 2x), i.e. the server part of the URL your Grav installation will be reachable with.
  • The name of the certificate and key you use for SSL / TLS.
  • If and where you want an access log written to.
  • The location where Certbot (or any other ACME client) will put the domain verification challenges.
  • The path under which your Grav installation will be reachable. (The part right to the server name & port section in the URL.)
  • What application server (uWSGI or FPM) you are using, i.e. how and where nginx will pass requests that need to trigger some PHP code.

There is no need to install any additional modules since nginx natively supports both protocols FastCGI and uwsgi.

Grav's documentation also covers setting up Grav with nginx. But be aware that the instructions are Ubuntu / Debian centric and do not mention uWSGI.

Apache HTTP Server

Unfortunately upstream Grav does not provide a sample configuration file for Apache HTTP Server. At least there is a section in this wiki about how to integrate Apache with PHP by means of FPM and mod_proxy_fcgi. uWSGI's documentation has some information about how to integrate Apache with PHP by means of uWSGI and mod_proxy_uwsgi. Mind that the apache package comes with both modules mod_proxy_fcgi and mod_proxy_uwsgi. They need to be loaded as required.

Plugins

A lot of Grav's power comes from the large set of plugins that can be installed. Just follow the instructions on Grav's documentation how to install plugins.

ノート: When installing plugins from the command line make sure to perform these commands as user grav. E.g.
# runuser -u grav -- bin/gpm install admin
Otherwise you will sooner or later run into permission issues.

Currently there are no grav-plugin-... packages that allow installing plugins via pacman (or some AUR wrapper). This will probably not change in the foreseeable future.

Content

See the extensive documentation on Grav's website on how to create content with this CMS.

Skeletons

Chances are the big empty board named Grav appears too intimidating to you. In this case you may want to use one of the many skeletons as a starting point. Skeletons are prefabricated bundles of Grav itself, some plugins, a theme and some sample content that give you some bits and pieces to play around with. Skeletons are supposed to be installed instead of a bare Grav installation. Unfortunately this makes it impossible to use a skeleton together with the gravAUR package.

With a bit of fiddling you can import the content of an arbitrary skeleton into your existing Grav installation.

警告: The following procedure will overwrite your current content. If you want to step back make backups of the directories /var/lib/grav/user and /etc/webapps/grav/config.
  1. Download the desired skeleton.
  2. Extract the user directory:
    # bsdtar -xf grav-skeleton-blahblah.zip user
  3. Replace the directories pages, plugins and themes in /var/lib/grav/user with the corresponding directories from the extracted user directory.
  4. Fix ownership and permissions
    # chown -R grav:http /var/lib/grav/user/{pages,plugins,themes}
    # chmod -R 640 /var/lib/grav/user/{pages,plugins,themes}
    # find /var/lib/grav/user/{pages,plugins,themes} -type d -exec chmod 750 {} \;
  5. Replace the configuration files site.yaml system.yaml in /etc/webapps/grav/config with the corresponding files from the extracted user/config.
  6. Fix ownership and permissions
    # chown grav:grav /etc/webapps/grav/config/{site,system}.yaml
    # chmod 644 /etc/webapps/grav/config/{site,system}.yaml

Migrating from v1.6 to v1.7

ノート: Migrating from earlier versions (< 1.7) of the package has been poorly tested (due to technical reasons). Please help to improve this section.

Migrating from earlier package versions (< 1.7) will most likely require manual intervention. Errors may happen. So backup your data before trying an upgrade from earlier version! This comprises at least the /usr/share/webapps/grav/user directory.

The upgrade will probably fail right away with lots of error messages complaining about files already existing under /usr/share/webapps/grav/vendor. Just delete this directory.

Since the last package of version 1.6 (v1.6.28, 2020-11-18) php has been upgraded from version 7 to 8. This may render some of your plugins non-functional.

Grav v1.7 has become stricter in many ways. See Grav's migration guide about details.

Do not try to tweak your setup to use system user http as used to be. For good reasons Arch Linux' web application package guidelines dictates to use a dedicated system user (here grav) to run the application.

Probably the best migration strategy is to backup the /usr/share/webapps/grav/user directory, uninstall Grav and all dependent packages, remove all remnants of the Grav installation (including all Grav specific configurations with your web server and application server), update your system (including PHP) and then install Grav from scratch. When everything is set up and your server successfully presents Grav's default page you can start to restore your previous content.

Upgrade

Upgrading Grav itself must exclusively be done by pacman (or some AUR wrapper)!

警告: Do not try to upgrade Grav itself with gpm as described in Grav's update documentation or via the admin plugin. At best this will simply not work, at worst it will ruin your installation.

Unlike upgrading Grav itself, upgrading plugins and themes must be done with gpm update or via the admin plugin.

Also not recommended is to download Grav releases as ZIP archives directly from Grav's GitHub project site and copy around stuff in the filesystem. Only do so when you know exactly what you are doing.