Gravのソースを表示

[[Category:コンテンツ管理システム]]
[[en:Grav]]
{{Related articles start}}
{{Related|PHP}}
{{Related|Nginx}}
{{Related|UWSGI}}
{{Related|Apache HTTP Server}}
{{Related articles end}}
[[Wikipedia:Grav_(CMS)|Wikipedia]] より:

:Grav は、PHP プログラミング言語と Symfony Web アプリケーションフレームワークをベースして書かれたフリーソフトウェアでセルフホスト型のコンテンツ管理システム（CMS）です。バックエンドとフロントエンドの両方でフラットファイルデータベースを使用します。

:Grav は学習曲線が浅く、セットアップが簡単であるように設計されています。Grav の焦点は、複雑さを犠牲にした豊富な組み込み機能よりも、スピードとシンプルさです。

== 前提条件 ==

Grav は驚くほど少ない前提条件で提供されています。もちろん PHP で書かれたウェブアプリケーションなので [[PHP]] が必要です。必要な PHP モジュールは {{pkg|php-gd}} のみです。他にも[https://learn.getgrav.org/17/basics/requirements#php-requirements いくつか]必要ですが、それらはすでに PHP インストール時に含まれています。次の PHP モジュールはオプションですが、パフォーマンス向上のために強くお勧めします。

* キャッシュパフォーマンス向上のための {{pkg|php-apcu}}
* パフォーマンスを劇的に向上させるネイティブ YAML 処理の {{aur|php-yaml}}

Grav は[https://getgrav.org/blog/using-builtin-webserver 独自の機能]でコンテンツを提供できますが、この記事ではフル機能のウェブサーバを前提としたセットアップを説明します。したがって、必要なものは以下の通りです。

* ウェブサーバ：[[Apache HTTP Server]] または [[nginx]] など
* アプリケーションサーバ：[[uWSGI]]（{{pkg|uwsgi-plugin-php}} と一緒に）または [https://cwiki.apache.org/confluence/display/HTTPD/PHP-FPM FPM]

以下の組み合わせをカバーしています:

* nginx &rarr; uWSGI（プラス uwsgi-plugin-php）
* nginx &rarr; FPM
* Apache（mod_proxy_uwsgi を使用）&rarr; uWSGI（プラス uwsgi-plugin-php）
* Apache（mod_proxy_fcgi を使用）&rarr; FPM

Grav のインストールは、Arch Linux の [[ウェブアプリケーションパッケージガイドライン]] に準拠しています。これは、他の詳細とともに、Grav は独自のシステムユーザー (''grav'') で実行する必要があることを意味します。したがって、{{pkg|php-apache}} を使用して Apache プロセスで PHP コードを直接実行することはもうできません。

== インストール ==

{{aur|grav}} パッケージを[[インストール]]します。これにより、2つの必要な依存関係である {{Pkg|php}} と {{pkg|php-gd}} が自動的にインストールされます。また、{{pkg|php-apcu}} と {{aur|php-yaml}} を、できれば依存関係として ({{ic|--asdeps}}) をインストールします。{{ic|/etc/php/conf.d/yaml.ini}} の唯一の行をコメントアウトします。{{ic|/etc/php/conf.d/apcu.ini}} を変更しないでください。つまり、唯一の行をコメントしたままにしておきます。これら2つの拡張機能を Grav で有効化する作業は、他の場所で行われます（以下参照）。

== アプリケーションサーバー ==

PHP コードを処理するために使用できる 2 つの主要なアプリケーションサーバーがあります: [[uWSGI]] または [https://cwiki.apache.org/confluence/display/HTTPD/PHP-FPM FPM]。''FPM'' は、名前が示すように、PHP に特化しています。Web サーバーと ''FPM'' の間で使用されるプロトコルは ''fastcgi'' です。このツールは、 [https://www.php.net/manual/en/install.fpm.php PHP のディストリビューションの一部]として何年もの間、活発にメンテナンスされています。欠点は、[https://www.php.net/manual/en/install.fpm.configuration.php 公式ドキュメント]が改善の余地があることです。一方、''uWSGI'' は、言語固有のプラグインを介して [https://uwsgi-docs.readthedocs.io/en/latest/LanguagesAndPlatforms.html いくつかの言語]で書かれたコードを提供できます。使用されるプロトコルは ''uwsgi''（小文字）です。このツールは [https://uwsgi-docs.readthedocs.io/en/latest/index.html 豊富なドキュメント]がありますが、ドキュメントの量が多くなると混乱し、扱いにくくなります。メンテナンスは [https://github.com/unbit/uwsgi/commits/master かなり遅れ]ており、特に [https://github.com/unbit/uwsgi/commits/master/plugins/php PHP プラグイン]については遅れています。

=== uWSGI ===

{{Warning|2022-01-04 に PHP 8.1 が Arch Linux の Extra リポジトリで利用可能になった時点で、uWSGI の PHP プラグインは壊れていました。(参照：{{Bug|73470}}) このプラグインのリリース 2.0.20-5 では現在動作していますが、プロジェクトの長期的な実用性について [https://github.com/unbit/uwsgi/issues/2287 懸念]があることに注意してください。}}

uWSGI には独自の [[uWSGI|記事]]があります。そこには多くの有用な情報が掲載されています。{{pkg|uwsgi}} とプラグイン {{pkg|uwsgi-plugin-php}} をインストールします。できれば依存関係として、つまり {{ic|--asdeps}} で。Grav アプリケーションのセットアップには、ファイルを 1 つコピーして、systemd サービスを1つ定義するだけです。

==== grav.ini ====

Grav 固有の uWSGI 設定ファイルを適切な場所にコピーします。

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

{{ic|grav.ini}} が root によって所有され、書き込み可能であることを確認してください。すなわち {{ic|-rw-r--r-- 1 root root ... grav.ini}} となります。この設定は機能的ですが、お好みに合わせて変更してください。たとえば、{{ic|1=php-set = date.timezone=}} をお好みのタイムゾーンに変更することができます。

==== Systemd サービス ====

{{pkg|uwsgi}} パッケージは、テンプレートユニットファイル（{{ic|uwsgi@.service}}）を提供します。インスタンス ID（ここでは ''grav''）が正しい設定ファイルを選択するために使用されます。したがって、{{ic|uwsgi@grav.service}} を[[起動/有効化]] します。

もし、このようなサービスがいくつか（例えば 2 つ）起動されており、リソースの無駄だと感じる場合は、[https://uwsgi-docs.readthedocs.io/en/latest/Emperor.html エンペラーモード]を検討してみてください。

=== FPM ===

''FPM'' をアプリケーションサーバーとして使用する場合は、{{pkg|php-fpm}} をインストールします。できれば依存パッケージとして（{{ic|--asdeps}}）。

設定を少し調整する必要があります。

==== php-fpm.ini ====

''FPM'' は、独自のバージョンの {{ic|php.ini}} を実行するのが良い方法です。これにより、''FPM'' でのみ必要なもので標準の INI ファイル（{{ic|/etc/php/php.ini}}）を散らかさずに済みます。{{ic|/usr/share/webapps/grav/webserver-configs}} に機能的な INI ファイルのコピーがあります。それを {{ic|/etc/php}} にコピーします。

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

root によって所有され、書き込み可能であることを確認してください。{{ic|-rw-r--r-- 1 root root ... php-fpm.ini}} など。必要に応じて設定をカスタマイズしてください。

==== 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 {{aur|grav}} 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. {{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.

{{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.}}

==== 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]].

{{hc|1=/etc/systemd/system/php-fpm.service.d/override.conf|2=
[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 {{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] =  &hellip;:/var/tmp/$pool:&hellip;}} in {{ic|/etc/php/php-fpm.d/grav.conf}}.

Do not forget to [[start/enable]] {{ic|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.

{{Warning|Some of the web server specific sample files provided in {{ic|/usr/share/webapps/grav/webserver-configs}} (except {{ic|nginx.conf}}) might be outdated.}}

=== nginx ===

Configuration of ''nginx'' is way beyond the scope of this article. See the relevant [[nginx|article]] for further information. The package {{aur|grav}} comes with a sample configuration file {{ic|/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 {{ic|/etc/nginx/sites-available}} with an appropriate name and create the corresponding symbolic link in {{ic|/etc/nginx/sites-enabled}}.

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

Things you might have to adapt (not exhaustive):

* Your server name ({{ic|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 &amp; 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 [https://learn.getgrav.org/17/webservers-hosting/servers/nginx 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 [[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 ==

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.}}

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.

== Content ==

See the extensive [https://learn.getgrav.org/17/content 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 [https://getgrav.org/downloads/skeletons 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 {{aur|grav}} package.

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

{{Warning|The following procedure will overwrite your current content. If you want to step back make backups of the directories {{ic|/var/lib/grav/user}} and {{ic|/etc/webapps/grav/config}}.}}

# Download the desired skeleton.
# 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.
# 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 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}}

== 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.}}

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 {{ic|/usr/share/webapps/grav/user}} directory.

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

Since the last package of version 1.6 (v1.6.28, 2020-11-18) {{Pkg|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 [https://learn.getgrav.org/17/advanced/grav-development/grav-17-upgrade-guide 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 {{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 ==

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

{{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.}}

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.