このファイルは .github/workflows/gh-pages.yml によって生成されています - すべてのローカル変更は最終的に失われます！
= ansible-role-apache2
Jonas Pammer opensource@jonaspammer.at;
:toc: left
:toclevels: 2
:toc-placement!: :source-highlighter: rouge

https://galaxy.ansible.com/jonaspammer/apache2[image:https://img.shields.io/badge/available%20on%20ansible%20galaxy-jonaspammer.apache2-brightgreen[バージョン情報]]
// とても関連性の高いステータスバッジ
https://github.com/JonasPammer/ansible-role-apache2/actions/workflows/ci.yml[image:https://github.com/JonasPammer/ansible-role-apache2/actions/workflows/ci.yml/badge.svg[テストCI]]

Apache2をインストールし、モジュールを有効化/無効化し、デフォルトを設定し、仮想ホストを作成するためのAnsibleロールです。

toc::[]

[[meta]]
== 🔎 メタデータ
下記には以下の情報があります：

• ロールの必要Ansibleバージョン
• ロールのサポート対象プラットフォーム
• ロールの依存関係に関する情報

.link:meta/main.yml[]
[source,yaml]

---

---

galaxy_info:
role_name: "apache2"
description:
"Apache2をインストールし、モジュールを有効化/無効化し、
デフォルトを設定し、仮想ホストを作成するためのAnsibleロールです。
geerlingguyのapache2ロールに基づいています。"

author: "jonaspammer"
license: "MIT"

min_ansible_version: "2.11"
platforms:
- name: EL
versions:
- "9"
- name: Fedora
versions:
- "38"
- "39"
- name: Debian
versions:
- bullseye
- bookworm
- name: Ubuntu
versions:
- focal
- jammy

galaxy_tags:
- web
- apache
- webserver
- html
- httpd

dependencies: []

allow_duplicates: true

[[requirements]]
== 📌 要件
このロールまたはAnsible自体がカバーしていない前提条件があれば、ここに記載する必要があります。
Ansibleユーザーはbecomeを使用できる必要があります。

SSL/TLSを使用する場合（<>）、自分自身の証明書とキーのファイルを提供する必要があります。

ApacheをPHPと共に使用する場合は、
https://github.com/geerlingguy/ansible-role-php/[geerlingguy.php]ロールを使用してPHPをインストールし、
mod_php（適切なパッケージを追加することで、例えばUbuntuではlibapache2-mod-php5として）を使用するか、
https://github.com/geerlingguy/ansible-role-apache-php-fpm[`geerlingguy.apache-php-fpm`]を使用して、ApacheをPHPに接続します。
詳細情報はリンク先のREADMEを参照してください。

Solarisベースのシステムをターゲットにする際は、
https://galaxy.ansible.com/community/general[`community.general` コレクション]
（pkg5モジュールを含む）がAnsibleコントローラーにインストールされている必要があります。

Suseベースのシステムをターゲットにする際は、
https://galaxy.ansible.com/community/general[`community.general` コレクション]
（zypperモジュールを含む）がAnsibleコントローラーにインストールされている必要があります。

[[variables]]
== 📜 ロール変数
このロールで設定可能な変数の説明がここに記載されます。
他のロールおよび/またはグローバルスコープから読み込まれる変数（例：hostvars、グループ変数など）もここに記載されるべきです。

[source,yaml]

apache_mods_enabled:

• rewrite
• ssl
  apache_mods_disabled: []

---

（Debian/RHELのみ）
Apacheモジュールを有効化または無効化するためのリスト（これらは適切な場所にシンボリックリンクされます）。
利用可能なすべてのモジュールについては、<<apache__server_root_dir,apacheのルートディレクトリ>>内のmods-available（Debian） / conf.modules.d（RHEL）ディレクトリを参照してください。

[source,yaml]

apache_listen_ip: "*"
apache_listen_port: 80
apache_listen_port_ssl: 443

---

ApacheがリスニングすべきIPアドレスとポートです。
ポート80または443で別のサービス（リバースプロキシなど）がリスニングしている場合にデフォルトを変更する必要がある場合に便利です。

[source,yaml]

apache_remove_default_vhost: false

Debian/Ubuntuでは、Apacheの設定にデフォルトの仮想ホストが含まれています。
これをtrueに設定すると、そのデフォルトが削除されます。

[source,yaml]

apache_state: started

初期のApacheの状態を設定します。
推奨値：startedまたはstopped

[source,yaml]

apache_enabled: true

Apacheサービスの初期状態を設定します。
推奨値：trueまたはfalse

[source,yaml]

apache_restart_state: restarted

設定変更が行われた際にApacheを置く状態を設定します。
（つまり、restart apacheハンドラーが呼び出されたときです）。
推奨値：restartedまたはreloaded

[[apache_default_favicon]]
[source,yaml]

---

apache_default_favicon: favicon.ico

サーバーにコピーされ、Apacheがデフォルトのファビコンとして使用するためのファイルへのパスです。

=== インストール用のロール変数

[source,yaml]

apache_packages: [OS固有のデフォルト、/defaultsディレクトリを参照]

Apache2と最も必要なユーティリティをインストールするためのパッケージ名のリストです。

[source,yaml]

apache_packages_state: present

もし追加のリポジトリ（例：
https://launchpad.net/~ondrej/+archive/ubuntu/apache2[`ondrej/apache2`],
https://fedoraproject.org/wiki/EPEL[`EPEL`]、
http://rpms.remirepo.net/[`remi`]）を有効にしている場合、バージョンを簡単にアップグレードするための方法がほしいかもしれません。
そのためには、これをlatestに設定します。

[source,yaml]

apache_enablerepo: ""

(RHEL/CentOSのみ)
Apacheをインストールする際に使用するリポジトリです。
OSのコアリポジトリにあるApacheの利用可能なバージョンよりも最新のものを希望する場合は、
https://fedoraproject.org/wiki/EPEL[EPEL]のようなリポジトリを使用してください。

=== 仮想ホストを作成するために使用されるロール変数

[TIP]
<>セクションに行って、
生成されたVirtualHostファイルがどのように見えるかを示す例を確認してください。

[NOTE]
このロールは、すべての設定ファイルの構文チェックを実行することで、
動作するApache設定を確保しようとしています（-t）
およびエラーが発生した場合に生成された仮想ホストを戻します。

[source,yaml]

apache_create_vhosts: true
apache_vhosts_filename: "vhosts.conf"
apache_vhosts_template: "vhosts.conf.j2"

---

trueに設定すると、このロールの変数によって管理されるvhostsファイル（下記参照）が生成され、
Apacheの設定フォルダーに配置されます。
falseに設定すると、自分自身のvhostsファイルをApacheの設定フォルダーに置くことができ、このロールによって追加された便利（しかしより基本的な）ファイルを省略できます。

使用するテンプレートをオーバーライドし、
独自のテンプレートへのパスを設定して、仮想ホストのレイアウトをさらにカスタマイズすることもできます。

[source,yaml]

apache_global_vhost_settings: |
DirectoryIndex index.php index.html

---

この変数は、生成された仮想ホストファイルの*_どのディレクティブ_の外で使用されます。

[WARNING]
これにより、Apacheの一般的なコンテキストに適用される設定が変更されます。

デフォルト値に関して理解しておくべき点は、
DirectoryIndexは設定しないのではなく、追加することです。

[source,yaml]

apache_vhosts:

• servername: "local.dev"
  documentroot: "/var/www/html"

---

このリスト内の各エントリーに対して、
{{ apache_listen_ip }}:{{ apache_listen_port }}でリスニングする<VirtualHost>ディレクティブが生成されます。

各エントリーのリストは以下のプロパティを持つことができます。
詳しい情報については、<>セクションやキリンクされた公式ドキュメントを確認してください。

https://httpd.apache.org/docs/2.4/mod/core.html#servername[servername]（必須）：：

https://httpd.apache.org/docs/2.4/mod/core.html#serveralias[serveralias]：：

https://httpd.apache.org/docs/2.4/mod/core.html#serveradmin[serveradmin]：：

https://httpd.apache.org/docs/2.4/mod/core.html#documentroot[documentroot]：：

documentroot__link:https://httpd.apache.org/docs/2.4/mod/core.html#servername[allowoverride]：
DocumentRootの<Directory>内で使用されるAllowOverrideディレクティブです。
デフォルトはapache_vhosts_default_documentroot__allowoverrideの値です。

documentroot__link:https://httpd.apache.org/docs/2.4/mod/core.html#options[options]：
DocumentRootの<Directory>内で使用されるOptionsディレクティブです。
デフォルトはapache_vhosts_default_documentroot__optionsの値です。

https://httpd.apache.org/docs/2.4/mod/mod_log_config.html#logformat[logformat]：：

https://httpd.apache.org/docs/2.4/mod/core.html#loglevel[loglevel]：：

[[apache_vhosts__errorlog]]
https://httpd.apache.org/docs/2.4/mod/core.html#errorlog[errorlog]：
文字列（パスを表し、自動的に引用されません）または複雑なデータ型です：
path：：
パス。
"`"で引用されます。

extra：：
pathの後に追加される文字列。

extra_parameters：：
この変数は、実際のErrorLogステートメントの前にそのまま挿入されます
（インデントは2）。
このパラメータの使用ケースは、条件付きログを有効にするための
SetEnvIf / SetEnvを使用することや、この特定のエラーログに
カスタムLogFormat設定を使用するためです。

[[apache_vhosts__customlogs]]
https://httpd.apache.org/docs/2.4/mod/mod_log_config.html#customlog[customlogs]：：
カスタムログの配列。
各エントリーは文字列（自動的に引用されません）または複雑なデータ型です：
path：：
パス。
"`"で引用されます。

extra：：
pathの後に追加される文字列。
引用されません（例えば、カスタムログの追加オプションパラメータを供給するため）。

extra_parameters：：
この変数は、ループされた<VirtualHost>の最後にそのまま挿入されます（インデントは2）。

[[apache_vhosts_ssl]]
[source,yaml]

---

apache_vhosts_ssl: []

このリスト内の各エントリーに対して、
{{ apache_listen_ip }}:{{ apache_listen_port_ssl }}でリスニングする<VirtualHost>ディレクティブが生成されます。

各エントリーのリストは以下のプロパティを持つことができます。
詳しい情報については、<>セクションやキリンクされた公式ドキュメントを確認してください。

https://httpd.apache.org/docs/2.4/mod/core.html#servername[servername]（必須）：：

https://httpd.apache.org/docs/2.4/mod/core.html#serveralias[serveralias]：：

https://httpd.apache.org/docs/2.4/mod/core.html#serveradmin[serveradmin]：：

https://httpd.apache.org/docs/2.4/mod/core.html#documentroot[documentroot]：：

documentroot__link:https://httpd.apache.org/docs/2.4/mod/core.html#servername[allowoverride]：
DocumentRootの<Directory>内で使用されるAllowOverrideディレクティブです。
デフォルトはapache_vhosts_default_documentroot__allowoverrideの値です。

documentroot__link:https://httpd.apache.org/docs/2.4/mod/core.html#options[options]：
DocumentRootの<Directory>内で使用されるOptionsディレクティブです。
デフォルトはapache_vhosts_default_documentroot__optionsの値です。

no_actual_ssl：
Trueに設定された場合、<VirtualHost>はSSLオプションを持ちません。
これは、extra_parametersで定義したHTTPからHTTPSへのリダイレクトを希望するときだけ使用されます。

https://httpd.apache.org/docs/current/mod/mod_ssl.html#sslcertificatefile[ssl_certificate_file]（必須）::
https://httpd.apache.org/docs/current/mod/mod_ssl.html#sslcertificatekeyfile[ssl_certificate_key_file]（必須）::
https://httpd.apache.org/docs/current/mod/mod_ssl.html#sslcertificatechainfile[ssl_certificate_chain_file]：：
これは非推奨です。

https://httpd.apache.org/docs/2.4/mod/mod_log_config.html#logformat[logformat]：：

https://httpd.apache.org/docs/2.4/mod/core.html#loglevel[loglevel]：：

https://httpd.apache.org/docs/2.4/mod/core.html#errorlog[errorlog]：
<<apache_vhosts__errorlog,apache_vhosts.errorlog>>と等価です。

https://httpd.apache.org/docs/2.4/mod/mod_log_config.html#customlog[customlogs]：
<<apache_vhosts__customlogs,apache_vhosts.customlogs>>と等価です。

extra_parameters：：
この変数は、ループされた<VirtualHost>の最後にそのまま挿入されます（インデントは2）。

[source,yaml]

apache_ignore_missing_ssl_certificate: true

falseに設定された場合、apache_vhosts_sslの指定されたエントリーは、sslcertificatefileが存在する場合にのみ生成されます。

[source,yaml]

apache_ssl_protocol: "All -SSLv2 -SSLv3"
apache_ssl_cipher_suite: "AES256+EECDH:AES256+EDH"

---

これらの変数は、各apache_vhosts_sslに対するデフォルトとして使用されます。
これらの変数は、回避策として（それぞれの接頭辞を除いて）同じ名前が付けられています。
実際のApacheディレクティブに関するドキュメントは、
https://httpd.apache.org/docs/current/mod/mod_ssl.html[Apacheのドキュメント]を参照してください。

[source,yaml]

apache_vhosts_default_documentroot__allowoverride: "All"
apache_vhosts_default_documentroot__options: "-Indexes +FollowSymLinks"

---

[[public_vars]]
== 📜 このロールによって定義された事実/変数

このセクションにリストされている各変数は、
このロールを実行する際に動的に定義され（ansible.builtin.set_factsを使用してのみ上書き可能）、
単に内部で使用されることを意図しています。

[[apache__service]]
.pass:[apache__service]

---

このロール外での使用例：
[source,yaml]

---

roles.xyz用のハンドラーファイル

• name: apache2再起動
  ansible.builtin.service:
  name: "{{ apache__service | default('apache2') }}"
  state: restarted

---

---

[[apache__daemon]]
.pass:[apache__daemon_dir], pass:[apache__daemon]

---

apache2コマンドの実行可能名とディレクトリです。

---

[[apache__server_root_dir]]
.pass:[apache__server_root_dir]

---

Apache2の設定が含まれるディレクトリ（/etc内）。

---

[[debian_is_different_note]]
[NOTE]
Debian 10の/etc/apache2/apache2.confで見られるコメントを考慮するときは、
以下の設定値に関して理解しておくべきことがあります：

---

DebianのApache2の設定は、
上流が推奨する方法とは大きく異なります。
これは、DebianのデフォルトのApache2インストールが、
モジュール、仮想ホスト、追加の設定ディレクティブを可能な限り柔軟に追加および削除できるようにして、
変更の自動化とサーバーの管理をできるだけ簡単にするためです。

---

つまり、Debianでは、
pass:[apache__server_root_dir]は次のようになります：

.tree /etc/apache2の出力（新規Debian 10マシンにApache2をインストールした後）

.
├── apache2.conf  
├── conf-available  
│   ├── charset.conf  
│   ├── localized-error-pages.conf  
│   ├── other-vhosts-access-log.conf  
│   ├── php7.4-fpm.conf  
│   ├── security.conf  
│   └── serve-cgi-bin.conf  
├── conf-enabled  
│   ├── charset.conf -> ../conf-available/charset.conf  
│   └── …  
├── envvars  
├── magic  
├── mods-available  
│   ├── access_compat.load  
│   ├── alias.load  
│   ├── alias.conf  
│   └── …  
├── mods-enabled  
│   ├── access_compat.load -> ../mods-available/access_compat.load  
│   ├── alias.conf -> ../mods-available/alias.conf  
│   ├── alias.load -> ../mods-available/alias.load  
│   └── …  
├── ports.conf  
├── sites-available  
│   ├── 000-default.conf  
│   └── default-ssl.conf  
└── sites-enabled  
    └── 000-default.conf -> ../sites-available/000-default.conf  

ほかのシステムでは、このように見えます：

.tree /etc/apache2の出力（新規CentOS 8マシンにApache2をインストールした後）

.
├── conf  
│   ├── httpd.conf  
│   └── magic  
├── conf.d  
│   ├── autoindex.conf  
│   ├── ssl.conf  
│   ├── userdir.conf  
│   └── welcome.conf  
├── conf.modules.d  
│   ├── 00-base.conf  
│   ├── 00-dav.conf  
│   ├── 00-lua.conf  
│   ├── 00-mpm.conf  
│   ├── 00-optional.conf  
│   ├── 00-proxy.conf  
│   ├── 00-ssl.conf  
│   ├── 00-systemd.conf  
│   ├── 01-cgi.conf  
│   ├── 10-h2.conf  
│   ├── 10-proxy_h2.conf  
│   └── README  
├── logs -> ../../var/log/httpd  
│   └── …  
└── modules -> ../../usr/lib64/httpd/modules  
    ├── mod_access_compat.so  
    ├── mod_actions.so  
    ├── mod_alias.so  
    └── …  

====

[[apache__primary_configuration_file_path]]
.pass:[apache__primary_configuration_file_path]

---

Apache2の主要な設定ファイルで、
すべての他のファイルの参照をIncludeし、一部の他のディレクティブを含んでいます。

取り込まれている内容の調査
[TIP]
DebianのApache2 Includeディレクティブは、pass:[apache__primary_configuration_file_path]に見つかります：

[source,ini]

モジュール設定を含める：

IncludeOptional mods-enabled/.load
IncludeOptional mods-enabled/.conf

リスニングするポートのリストの取り込み

Include ports.conf

ディレクトリの取り込みは、エディターやdpkgのバックアップファイルを無視し、

一般的なステートメントスニペットを含める

IncludeOptional conf-enabled/*.conf

仮想ホストの設定を含める：

IncludeOptional sites-enabled/*.conf

RHELのApache2 Includeディレクティブは、CentOS 8マシンの
pass:[apache__primary_configuration_file_path]に見られます：

[source,ini]

動的共有オブジェクト（DSO）サポート

ビルトインDSOとしてビルドされたモジュールの機能を使用するには、

ここに対応するLoadModule行を配置する必要があります。

モジュールの内容は、使用される前に実際に利用可能になります。

静的にコンパイルされたモジュール（httpd -lでリストされるもの）は、

ここで読み込む必要はありません。

例：

LoadModule foo_module modules/mod_foo.so

Include conf.modules.d/*.conf

補足的な設定：

IncludeOptional conf.d/*.conf

====

[[apache__ports_configuration_file]]
.pass:[apache__ports_configuration_file]

---

Apache2の設定ファイルで、
着信接続のリスニングポートを決定するためのディレクティブを格納します。

一部のシステムでは、これがpass:[apache__primary_configuration_file_path]と同じですが、
他のシステムでは、言及されたpass:[apache__primary_configuration_file_path]によってIncludeされる単独のファイルです。

---

[[apache__server_conf_dir]]
.pass:[apache__server_conf_dir]

---

すべてのhttp://httpd.apache.org/docs/2.4/mod/core.html#include[Include]されたファイルが格納されるディレクトリです。

このディレクトリがIncludeされることはないかもしれませんが、
Includeされるサブディレクトリがある場合があります。
異なるOSにおいてのデフォルトでIncludeされるディレクトリについては、
<>のNOTE/TIPで確認してください。

---

[[apache__default_log_dir]]
.pass:[apache__default_log_dir]

---

デフォルトですべての仮想ホストに使用される/var内のディレクトリです。

以下の出力は、主要なディストリビューションのこのフォルダー内の典型的なデフォルトファイル内容を示しています：

.RedHat

[root@instance-py3-ansible-5 /]# ls -l /var/log/httpd/  
total 8  
-rw-r--r-- 1 root root   0 Jun 11 11:16 access_log  
-rw-r--r-- 1 root root 980 Jun 11 11:16 error_log  
-rw-r--r-- 1 root root   0 Jun 11 11:16 ssl_access_log  
-rw-r--r-- 1 root root 328 Jun 11 11:16 ssl_error_log  
-rw-r--r-- 1 root root   0 Jun 11 11:16 ssl_request_log  

.Debian

root@instance-py3-ansible-5-debian10:/# ls -l /var/log/apache2  
total 4  
-rw-r----- 1 root adm     0 Aug 29 10:17 access.log  
-rw-r----- 1 root adm  2133 Aug 29 10:18 error.log  
-rw-r--r-- 1 root root    0 Aug 29 10:18 local2-error.log  
-rw-r----- 1 root adm     0 Aug 29 10:17 other_vhosts_access.log  

---

[[tags]]
== 🏷️ タグ

タスクは以下の以下の
https://docs.ansible.com/ansible/latest/user_guide/playbooks_tags.html#adding-tags-to-roles[タグ]を使用してタグ付けされます：

| タグ | 用途

2+| このロールには公式に文書化されたタグがまだありません。

すべてのタスクは、指定されたタグがない場合に実行されます。

[[dependencies]]
== 👫 依存関係

他のロールのリストや、他のロールのパラメーターに設定が必要な詳細、
または他のロールで使用される変数がここに配置されます。

[[example_playbooks]]
== 📚 使用例プレイブック

このロールを使用した一般的なシナリオのプレイブック例を含めることは、ユーザーにとって常に便利です。

[NOTE]
このロールは、
https://github.com/JonasPammer/ansible-roles[私の多くの目的特化した互換ロール]の一部です。

マシンは準備されていないといけません。
CIでは、molecule/resources/prepare.ymlにおいて
そのソフト依存関係がrequirements.ymlからソースされます：

.link:molecule/resources/prepare.yml[]
[source,yaml]

---

---

• name: prepare
  hosts: all
  become: true
  gather_facts: false

  roles:

  • role: jonaspammer.bootstrap

---

以下の図は、このロールの「ソフト依存関係」とそのソフト依存関係の再帰的ツリーのコンパイルです。

image:https://raw.githubusercontent.com/JonasPammer/ansible-roles/master/graphs/dependencies_apache2.svg[requirements.ymlの依存関係グラフ]

====

.Standard Installation (no variables)
次のyamlが生成されます：
[source,yaml]

---

roles:

• role: jonaspammer.apache2

---

次のようなVirtualHostが生成されます：
[source]

# Ansibleによって管理されています  
DirectoryIndex index.php index.html  
<VirtualHost *:80>  
    ServerName local.dev  
    DocumentRoot "/var/www/html"  

    <Directory "/var/www/html">  
        AllowOverride All  
        Options -Indexes +FollowSymLinks  
        Require all granted  
    </Directory>  
</VirtualHost>  

参照のために、これはDebian/Ubuntuシステムに付属のデフォルトのvhostです
（apache_remove_default_vhostを真に設定することで削除可能）：
[source]

<VirtualHost *:80>  
        ServerAdmin webmaster@localhost  
        DocumentRoot /var/www/html  

        ErrorLog ${APACHE_LOG_DIR}/error.log  
        CustomLog ${APACHE_LOG_DIR}/access.log combined  
</VirtualHost>  

ロール設定がなければ、Apache2を自分でインストールする際の逸脱点は以下です：

• 特定のモジュールがデフォルトでアクティブになります（<<apache_mods_enabled>>）。
• システムには上記のVirtualHostが示されます。
• 初回インストール時、ファイル名がfavicon.ico（<>から）であれば、
  /var/www/htmlに配置されます。
  このファビコンはデフォルトで、ウィキメディアにあるAnsibleのロゴを表しています。

このロールは/var/www/htmlの内容を削除しないことにご注意ください。
（最初のApache2インストール以降に作成された場合でも）。
====

.Logging
次のyamlが生成されます：
[source,yaml]

---

roles:

• role: jonaspammer.apache2

vars:
apache_vhost_filename: "local2.dev.conf"
apache_vhosts:
- servername: "wwww.local2.dev"
loglevel: info
errorlog: "{{ apache__default_log_dir }}/local2-error.log"
customlog:
path: "${{ apache__default_log_dir }}/local2-access.log"
extra: "combined"

---

次のようなVirtualHostが生成されます：
[source]

# Ansibleによって管理されています。  

TODO  

====

.Usage of extra_parameters
[TIP]
YAMLの行の最後にパイプシンボルがある場合、
その後にインデントされたテキストはマルチラインスカラー値として解釈されます。
詳細な説明は、https://yaml-multiline.info/[yaml-multiline.info]を参照してください。
====

次のyamlが生成されます：
[source,yaml]

---

roles:

• role: jonaspammer.apache2

vars:
apache_vhost_filename: "myvhost.conf"
apache_vhosts:
- servername: "www.local.dev"
serveralias: "local.dev"
documentroot: "/var/www/html"
extra_parameters: |
# 「www」サブドメインへのすべてのリクエストをリダイレクトします。Apache 2.4+
RewriteEngine On
RewriteCond %{HTTP_HOST} !^www. [NC]
RewriteRule ^(.*)$ %{REQUEST_SCHEME}://www.%{HTTP_HOST}%{REQUEST_URI} [R=302,L]

---

次のようなVirtualHostが生成されます：
[source]

# Ansibleによって管理されています。  

TODO  

====

• 次のyamlが生成されます：
  [source,yaml]

---

roles:

• role: jonaspammer.apache2

vars:
apache_vhost_filename: "myvhost.conf"
apache_vhosts:
- servername: "srvcmk.intra.jonaspammer.com"
extra_parameters: |
Redirect / {{ checkmk_site_url }}

---

次のようなVirtualHostが生成されます：
[source]

# Ansibleによって管理されています。  
DirectoryIndex index.php index.html  
<VirtualHost *:80>  
    ServerName srvcmk.intra.jonaspammer.com  

    Redirect / http://srvcmk.intra.jonaspammer.at/master  
</VirtualHost>  

====

.Creating your own virtualhost file / Integrate into a role
このapache2ロールは、Play内で複数回実行できます。目的は、
https://docs.ansible.com/ansible/latest/user_guide/playbooks_reuse_roles.html#using-allow-duplicates-true[これを許可すること]
により、仮想ホストを生成することができます。

[source,yaml,subs="+quotes,macros"]

• tasks:
  pass:[#]...
  • name: Apache2のVirtualHostを生成
    ansible.builtin.#include_role#: "apache2"
    vars:
    #apache_vhost_filename: "myapp.conf"#
    apache_vhosts:
    - servername: "www.myapp.dev"
    serveralias: "myapp.dev"
    DocumentRoot: "/opt/myapp"
    pass:[#]...

---

====

[[tested-distributions]]
== 🧪 テスト済みのディストリビューション

このロールは、Red Hat Enterprise Linux（RHEL）のような異なるディストリビューションで動作する可能性がありますが、
特定のディストリビューションでテストされているわけではありません。

OSファミリー	ディストリビューション	ディストリビューションリリース日	ディストリビューションのサポート終了日	付随するDockerイメージ

| Rocky | Rocky Linux 8 (https://www.howtogeek.com/devops/is-rocky-linux-the-new-centos/[RHEL/CentOS 8の偽装]) | 2021-06 | 2029-05 | https://github.com/geerlingguy/docker-rockylinux8-ansible/actions?query=workflow%3ABuild[image: https://github.com/geerlingguy/docker-rockylinux8-ansible/workflows/Build/badge.svg?branch=master[CI]]

| Rocky | Rocky Linux 9 | 2022-07 | 2032-05 | https://github.com/geerlingguy/docker-rockylinux9-ansible/actions?query=workflow%3ABuild[image: https://github.com/geerlingguy/docker-rockylinux9-ansible/workflows/Build/badge.svg?branch=master[CI]]

| RedHat | Fedora 39 | 2023-11 | 2024-12 | https://github.com/geerlingguy/docker-fedora39-ansible/actions?query=workflow%3ABuild[image: https://github.com/geerlingguy/docker-fedora39-ansible/workflows/Build/badge.svg?branch=master[CI]]

| Debian | Ubuntu 20.04 LTS | 2021-04 | 2025-04 | https://github.com/geerlingguy/docker-ubuntu2004-ansible/actions?query=workflow%3ABuild[image: https://github.com/geerlingguy/docker-ubuntu2004-ansible/workflows/Build/badge.svg?branch=master[CI]]

| Debian | Ubuntu 22.04 LTS | 2022-04 | 2027-04 | https://github.com/geerlingguy/docker-ubuntu2204-ansible/actions?query=workflow%3ABuild[image: https://github.com/geerlingguy/docker-ubuntu2204-ansible/workflows/Build/badge.svg?branch=master[CI]]

| Debian | Debian 11 | 2021-08 | 2024-06 (2026-06 LTS) | https://github.com/geerlingguy/docker-debian11-ansible/actions?query=workflow%3ABuild[image: https://github.com/geerlingguy/docker-debian11-ansible/workflows/Build/badge.svg?branch=master[CI]]

| Debian | Debian 12 | 2023-06 | 2026-06 (2028-06 LTS) | https://github.com/geerlingguy/docker-debian12-ansible/actions?query=workflow%3ABuild[image: https://github.com/geerlingguy/docker-debian12-ansible/workflows/Build/badge.svg?branch=master[CI]]

[[tested-ansible-versions]]
== 🧪 テスト済みのAnsibleバージョン

テスト済みのAnsibleバージョンは、
https://github.com/ansible-collections/community.general#tested-with-ansible[
Ansibleのcommunity.generalコレクションのサポートパターン]と等価になるようにしています。
執筆時点では以下です：

• 2.13 (Ansible 6)
• 2.14 (Ansible 7)
• 2.15 (Ansible 8)
• 2.16 (Ansible 9)

[[development]]
== 📝 開発
https://conventionalcommits.org[image:https://img.shields.io/badge/Conventional%20Commits-1.0.0-yellow.svg[Conventional Commits]]
https://results.pre-commit.ci/latest/github/JonasPammer/ansible-role-apache2/master[image:https://results.pre-commit.ci/badge/github/JonasPammer/ansible-role-apache2/master.svg[pre-commit.ci status]]

[[development-system-dependencies]]
=== 📌 開発マシンの依存関係

• Python 3.10以上
• Docker

[[development-dependencies]]
=== 📌 開発依存関係
開発依存関係は
https://pip.pypa.io/en/stable/user_guide/#requirements-files[pip要件ファイル]にて定義されています。
Linuxのインストール手順の例は以下です：

# オプション：Python仮想環境を作成し、現在のシェルセッションのためにアクティブ化します  
$ python3 -m venv venv  
$ source venv/bin/activate  

$ python3 -m pip install -r requirements-dev.txt  

[[development-guidelines]]
=== ℹ️ Ansibleロール開発ガイドライン

私の https://github.com/JonasPammer/cookiecutter-ansible-role/blob/master/ROLE_DEVELOPMENT_GUIDELINES.adoc[Ansibleロール開発ガイドライン] をご覧ください。

興味がある場合は、
https://github.com/JonasPammer/cookiecutter-ansible-role/blob/master/ROLE_DEVELOPMENT_TIPS.adoc[一般的なAnsibleロール開発（最良）プラクティス] についても記載しています。

[[versioning]]
=== 🔢 バージョン管理

バージョンは https://git-scm.com/book/en/v2/Git-Basics-Tagging[タグ]を使用して定義され、
それは https://galaxy.ansible.com/docs/contributing/version.html[Ansible Galaxyで認識され、使用されます]。

バージョンはvで始まってはいけません。

新しいタグがプッシュされると、
https://github.com/JonasPammer/ansible-role-apache2/actions/workflows/release-to-galaxy.yml[GitHub CIワークフロー]が、
役割を私のAnsible Galaxyアカウントにインポートすることを担当します。

[[testing]]
=== 🧪 テスト

自動テストは各貢献に対して、GitHubワークフローを使用して実行されます。

これらのテストは、
https://molecule.readthedocs.io/en/latest/[Molecule]を実行し、
<<tested-distributions,varying set of linux distributions>> および
<<tested-ansible-versions,various ansible versions>> を使用することに主に焦点を当てています。

Moleculeテストには、すべてのansibleプレイブックをリントするステップも含まれており、
最良のプラクティスと改善できる可能性のある挙動をチェックします。

テストを実行するには、単にコマンドラインでtoxを実行します。
Moleculeによって起動されるDockerコンテナのディストリビューションを定義するために、オプションの環境変数を渡すこともできます：

$ MOLECULE_DISTRO=ubuntu2204 tox  

MOLECULE_DISTROに渡される可能な値のリストについては、
link:.github/workflows/ci.yml[]のマトリクスを確認してください。

==== 🐛 Moleculeコンテナのデバッグ

1. MOLECULE_DESTROY=neverオプションを使用してMoleculeテストを実行します。例えば：

$ *MOLECULE_DESTROY=never MOLECULE_DISTRO=#ubuntu1604# tox -e py3-ansible-#5#*  
...  
  TASK [ansible-role-pip : (省略)] pass:[************************]  
  failed: [instance-py3-ansible-9] => changed=false  
...  
 pass:[___________________________________ summary ____________________________________]  
  pre-commit: commands succeeded  
ERROR:   py3-ansible-9: commands failed  

2. MoleculeでプロビジョニングされたDockerコンテナの名前を特定します：

$ *docker ps*  
#30e9b8d59cdf#   geerlingguy/docker-debian12-ansible:latest   "/lib/systemd/systemd"   8 minutes ago   Up 8 minutes                                                                                                    instance-py3-ansible-9  

3. コンテナのbashシェルに入ってデバッグを行います：

$ *docker exec -it #30e9b8d59cdf# /bin/bash*  

root@instance-py3-ansible-2:/#  

[TIP]
デバッグしようとしている失敗が、verify.ymlのステップの一部であり、
実際のconverge.ymlではない場合は、
Ansibleのモジュール（vars）、ホスト（hostvars）、および
環境変数の出力がプロビジョナーおよびDockerマシンの両方でファイルに保存されていることをご理解ください：

• /var/tmp/vars.yml（hostvarsキーの下のホスト変数が含まれます）
• /var/tmp/environment.yml

  grep、cat、または希望に応じて転送してください。

[TIP]
また、前述したファイルは、特定のワークフロー実行のGitHub CIアーティファクトに添付されています。
これにより、実行間の差異を確認し、
何が原因で不具合や一般的な失敗が発生したかをデバッグするのに役立ちます。

image::https://user-images.githubusercontent.com/32995541/178442403-e15264ca-433a-4bc7-95db-cfadb573db3c.png[]

4. デバッグが終了したら、退出し、コンテナを削除します：

root@instance-py3-ansible-2:/# *exit*  
$ *docker stop #30e9b8d59cdf#*  
$ *docker container rm #30e9b8d59cdf#*  
_or_  
$ *docker container prune*  

==== 🐛 インストールされたパッケージバージョンのローカルデバッグ

tox 3の標準機能ですが、
https://github.com/tox-dev/tox/pull/2794[今]はCI変数の存在を認識したときにのみ起こります。
たとえば：

$ CI=true tox  

[[development-container-extra]]
=== 🧃 TIP: コンテナ化された理想的な開発環境

このプロジェクトは、「1クリックのコンテナ化された開発環境」を提供します。
このコンテナでは、内部でDockerコンテナを実行することも可能で（Docker-In-Docker、dind）、
Moleculeの実行を可能にします。

使用方法：

1. Visual Studio Code開発コンテナのシステム要件を満たしていることを確認します。
   これは、リンクされたページの__インストール__セクションの手順を含みます。
   この手順には、Dockerのインストール、Visual Studio Code自体のインストール、および必要な拡張機能のインストールが含まれます。
2. プロジェクトを自分のマシンにクローンします。
3. リポジトリのフォルダーをVisual Studio Codeで開きます（_ファイル - フォルダーを開く…_）。
4. 開発コンテナ定義が存在することについてのプロンプトが右下隅に表示される場合、
   伴うボタンを押すことでその中に入ることができます。
   さもなければ、 Visual Studioコマンド Remote-Containers: Open Folder in Containerを実行することもできます（表示 - コマンドパレット -> _上記のコマンドを入力_）。

[TIP]
Remote-Containers: Rebuild Without Cache and Reopen in Containerをあちこちで使用することをお勧めします。
開発コンテナ機能は、定義の変更を認識する際にいくつかの問題があるためです。
====

[NOTE]
コンテナがSSH/GPGキーを使用できるように、ホストシステムの設定が必要になる場合があります。
手順は、公式開発コンテナドキュメントの「コンテナとGit資格情報を共有」の下に記載されています。

[[cookiecutter]]
=== 🍪 CookieCutter

このプロジェクトは、
https://github.com/JonasPammer/cookiecutter-ansible-role[もともとテンプレートとして使用したCookieCutter]と
同期を保つ必要があります。
これを実現するために、できるだけ（必要に応じて）手動で調整を行います。

.公式なcruft updateの使用例
image::https://raw.githubusercontent.com/cruft/cruft/master/art/example_update.gif[公式な`cruft update`使用例]
==== 🕗 変更履歴
新しいタグがプッシュされると、リポジトリのメンテナーが
GitHubリリースを作成し、適切なタイトルと説明を持つ人間による変更ログを提供します。

[[pre-commit]]
=== ℹ️ 一般的なリントおよびスタイリング慣行

一般的なリントおよびスタイリング慣行は、
https://stackoverflow.blog/2020/07/20/linters-arent-in-your-way-theyre-on-your-side/[*自動的に*基準に従います]
さまざまなhttps://pre-commit.com/[`pre-commit`]フックによって、少なくともある程度まで行われます。

pre-commitの自動実行は、各貢献で行われ、
https://pre-commit.ci[`pre-commit.ci`]によって管理されます。
プルリクエストは、同じツールによって自動的に修正されます。
下手をすると、ファイルを自動的に変更するフックによってもです。

[NOTE]
混同しないでください：
いくつかのpre-commitフックは、文法やコードの欠陥を警告することができるかもしれませんが、
そのため、pre-commitのフックはテストスイートの一部です。
テストに関する情報は<>を参照してください。
====

[TIP]
[[note_pre-commit-ci]]
ただし、出発点として、pre-commitをローカル開発ワークフローに統合することをお勧めします。
これは、クローンしたプロジェクトのディレクトリに移動し、pre-commit installを実行することで行えます。
そうすることで、Gitは毎回コミットするたびにpre-commitチェックを実行し、
フックが警告を発する場合、コミットを中止します。

例えば、pre-commit run --all-filesを実行することで
いつでもpre-commitのフックを実行できます。
====

[[contributing]]
== 💪 貢献
image:https://img.shields.io/badge/PRs-welcome-brightgreen.svg?style=flat-square[PRs歓迎]
https://open.vscode.dev/JonasPammer/ansible-role-apache2[image:https://img.shields.io/static/v1?logo=visualstudiocode&label=&message=Open%20in%20Visual%20Studio%20Code&labelColor=2c2c32&color=007acc&logoColor=007acc[Visual Studio Codeで開く]]

:toc:
:toclevels: 3

以下のセクションは一般的な内容であり、新しい貢献者を助けるために使用されます。
このプロジェクトの実際の「開発ドキュメント」は、<>にあります。

=== 🤝 前書き
まず初めに、このプロジェクトに貢献することを考える方に感謝します。

これらのガイドラインに従うことで、
オープンソースプロジェクトを管理し開発する開発者の時間を尊重していることを伝えるのに役立ちます。
その返礼として、彼らはあなたの問題に対処し、
変更を評価し、プルリクエストを最終的に完了させる際に、その尊重を返してくれるでしょう。

[[cookiecutter--contributing]]
=== 🍪 CookieCutter
このプロジェクトの多くのファイルは
https://github.com/JonasPammer/cookiecutter-ansible-role[もともとテンプレートとして使用したCookieCutter]に由来しています。

考慮すべき編集がある場合は、それがテンプレートに対して実際に適用可能であるかを確認してください。
もしそうであれば、その適切な変更をそこに施してください。
あなたの変更がテンプレートに部分的に適用でき、またこのプロジェクトに部分的に適用できる場合、
複数のPRを作成することになります。

=== 💬 一般的なコミットの慣行

カジュアルな貢献者は、
https://github.com/JonasPammer/JonasPammer/blob/master/demystifying/conventional_commits.adoc[__spec__]
https://www.conventionalcommits.org/en/v1.0.0/[__定義__]に従う心配をする必要はありません。
プルリクエストはすべて、プロジェクトの1つのコミットに統合されます。
コア貢献者、すなわちこのプロジェクトのブランチにプッシュする権限を持つ者だけがそれに従う必要があります。
（自動バージョン判定および変更ログ生成が機能するためです）。

=== 🚀 始め方

貢献は、イシューとプルリクエスト（PR）を通じてこのリポジトリに対して行われます。
それらに共通するいくつかの一般的なガイドラインは以下です：

• 自分自身で作成する前に、既存のイシューやPRを検索してください。
• もし初めての貢献であれば、
  https://auth0.com/blog/a-first-timers-guide-to-an-open-source-project/[
  Auth0のブログにある初めてのガイド]を参照して、情報やヒントを得てください。

==== イシュー

イシューは問題の報告、新しい機能のリクエスト、またはPRを作成する前に潜在的な変更を議論するために使用されるべきです。
新しいイシューを作成するとき、
テンプレートが読み込まれ、調査に必要な情報を収集し提供するのを助けます。

もし、あなたが抱えている問題に対処するイシューがある場合、
新たなイシューを作成するのではなく、既存のイシューに対して自身の再現情報を追加してください。
反応を追加することも、特定の問題が報告者以外にも影響を及ぼしていることを示すのに役立ちます。

==== プルリクエスト

このプロジェクトへのPRは常に歓迎され、あなたの修正や改善を次のリリースに組み込むための迅速な方法となり得ます。
一般的に、PRは以下のようにするべきです：

• 問題の修正または機能追加のみ行うか、広範囲な空白やスタイルの問題に対処するかのどちらかを行うべきであり、両方は行わないでください。
• 修正または変更された機能に対してユニットまたは統合テストを追加してください（テストスイートがすでに存在する場合）。
• 単一の問題に対処してください
• リポジトリにドキュメントを含めてください
• 完全なプルリクエストテンプレートが添付されていること（PR作成時に自動的に読み込まれます）。

コア機能に関する変更や、破壊的変更を伴う場合（例：メジャーリリース）には、
最初に提案について議論するためにイシューをオープンするのが最善です。

一般的には、「フォーク・アンド・プル」Gitワークフローに従います。

1. リポジトリを自分のGitHubアカウントにフォークします。
2. プロジェクトを自分のマシンにクローンします。
3. 簡潔で説明的な名前でローカルにブランチを作成します。
4. ブランチに対して変更をコミットします。
5. このリポジトリ特有のフォーマットやテストガイドラインに従います。
6. 自分のフォークに変更をプッシュします。
7. 私たちのリポジトリにPRを開き、変更を効率よくレビューできるようにするためにPRテンプレートに従います。

[[changelog]]
== 🗒 変更履歴
変更履歴を確認するには、
https://github.com/JonasPammer/ansible-role-apache2/releases[このリポジトリのリリースページ]を参照してください。

このプロジェクトはセマンティックバージョニングに従います。
マイナーバージョンアップデートでの偶然の破壊的変更があった場合は報告してください。

[[license]]
== ⚖️ ライセンス

.link:LICENSE[]

MITライセンス

著作権 (c) 2022, Jonas Pammer

このソフトウェア及び関連する文書ファイル（「ソフトウェア」）のコピーを取得したすべての人に対して、無償で制限なく使用することが許可されます。これには、使用、コピー、改変、結合、出版、配布、サブライセンス、及び/又は販売する権利が含まれ、このソフトウェアを提供された人にそのように行わせることも含まれます。ただし、以下の条件が適用されます：

上記の著作権表示及びこの許可通知は、ソフトウェアのすべてのコピーまたは重要な部分に含まれるものとします。

このソフトウェアは「現状のまま」で提供され、
明示または暗黙のいかなる種類の保証もなく、
商品性、特定の目的への適合性及び非侵害の保証を含むが、これに限定されません。
著者及び著作権者はいかなる請求、損害、またはその他の責任にも責任を負うことはありません。
契約、過失、またはその他の根拠に基づいて、
このソフトウェアの使用またはその他の取り扱いに関連して、発生した場合。

---