Grav

関連記事

• PHP
• Nginx
• UWSGI
• Apache HTTP Server

Wikipedia より:

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

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

前提条件

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

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

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

• ウェブサーバ：Apache HTTP Server または nginx など
• アプリケーションサーバ：uWSGI（uwsgi-plugin-php と一緒に）または FPM

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

• nginx → uWSGI（プラス uwsgi-plugin-php）
• nginx → FPM
• Apache（mod_proxy_uwsgi を使用）→ uWSGI（プラス uwsgi-plugin-php）
• Apache（mod_proxy_fcgi を使用）→ FPM

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

インストール

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

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

PHP コードを処理するために使用できる 2 つの主要なアプリケーションサーバーがあります: uWSGI または FPM。FPM は、名前が示すように、PHP に特化しています。Web サーバーと FPM の間で使用されるプロトコルは fastcgi です。このツールは、 PHP のディストリビューションの一部として何年もの間、活発にメンテナンスされています。欠点は、公式ドキュメントが改善の余地があることです。一方、uWSGI は、言語固有のプラグインを介して いくつかの言語で書かれたコードを提供できます。使用されるプロトコルは uwsgi（小文字）です。このツールは 豊富なドキュメントがありますが、ドキュメントの量が多くなると混乱し、扱いにくくなります。メンテナンスは かなり遅れており、特に PHP プラグインについては遅れています。

uWSGI

警告: 2022-01-04 に PHP 8.1 が Arch Linux の Extra リポジトリで利用可能になった時点で、uWSGI の PHP プラグインは壊れていました。(参照：FS#73470) このプラグインのリリース 2.0.20-5 では現在動作していますが、プロジェクトの長期的な実用性について 懸念があることに注意してください。

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

grav.ini

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

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

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

Systemd サービス

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

もし、このようなサービスがいくつか（例えば 2 つ）起動されており、リソースの無駄だと感じる場合は、エンペラーモードを検討してみてください。

FPM

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

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

php-fpm.ini

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

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

root によって所有され、書き込み可能であることを確認してください。-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 grav^AUR 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 grav^AUR 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 grav^AUR 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.