AEM開発者ブログ by YAMATO

アドビ社のデリバリーパートナー大和株式会社のAEM開発者ブログです。

CI/CD初心者がCONGAを使ってみたよ

CI/CD DevOps CONGA

こんにちは、大和株式会社の青葉です。

普段のAEMプロジェクト以外にも、Adobe Digital Learning Services（ADLS）が提供している定期コース（AEM Sitesユーザーコース、AEM Sites開発コース）のトレーナーを担当しております。

コロナの影響もあり、自室に籠る時間が長くなったためか、学習も捗るなぁと感じます。宇宙ステーション生活はしばらく続きますが、環境の有効活用で乗り越えます！

最近は CI/CD 分野にも興味を持ち始めたので、手当たり次第に冒険中です。どうぞよろしくお願いいたします。

CONGAとは？

今回みなさんにご紹介するのは、コンフィギュレーション ジェネレータ ツール「CONGA」（コンガ）です！

f:id:yamato_tech:20200403180131p:plain

名前をよく見ると：
CONfiguration GenerAtor　の大文字部分をとった結果がCONGAになります。

CONGAは、wcm.io DevOpsが提供している、AEMにおける CI/CD 関連で登場するツールの１つです。

まずはじめに、CONGAには何ができるのか？ポイントをまとめてみました：

CONGAにできること

  • AEMに特化した設定ファイルおよびパッケージを作成できる
  • AEMにコンテンツパッケージをデプロイできる
  • 指定の環境に、指定の設定を適用させることができる（ローカル or 特定の環境）
  • Ansibleと組み合わせ利用が可能
  • Mavenコマンドで操作できる

CONGAの動作確認ができる簡単なチュートリアル手順とCONGAのストラクチャ（ディレクトリ構成）を後ほどご紹介しますが、CI/CD初心者がいじってみた結果、個人的に少し残念に感じたところもあるのでシェアさせてください：

少し残念なところ

  • CONGAを学ぶためのドキュメント類が少ない（esp. 設定パラメータの詳細ドキュメントがほぼなく、Gitにあるサンプルを見て模索するスタイルを強いられた　笑）
  • そのためか、AEM関連の開発者間であまり浸透していないのかも？という印象がある（調べていてもwcm.ioの公式サイト、Github、adaptToプレゼン以外にあまりヒットしなかった... Adobe Experience Leagueのスレッドもなし）
  • どこまで詳細に設定できるのか、どこまで実際に役に立つのかが不明

以下、CONGAの使い方とストラクチャについてご説明します。
その前にチュートリアルから試してみたい方は、読み進める順番を変えていただいても問題ございません　^^

CONGAの使い方

準備

公式Githubからリポジトリをクローンします：

https://github.com/wcm-io-training/training-conga-exercise-aem

ざっくりとした使い方を説明すると：

  1. YAMLファイルに設定パラメータと値を記述
  2. packages-upload.shに、どの環境にどの設定を適用させるのかを記述
  3. Mavenコマンドでビルドし、パッケージを作成（OSGiコンフィグをパッケージに含めている）
  4. packages-upload.shを実行してAEM環境に適用させる

後半に簡易なチュートリアルも準備しておりますので、是非実際にさわってみましょう ^^

CONGAのストラクチャ（ディレクトリ構成）

CONGAは特定のGUIを使って操作するのではなく、YAMLファイルに設定する内容を記述し、それをMavenコマンドでビルドします。

先ほどご紹介したリポジトリをクローンしてフォルダ構造をのぞいてみると、definitionフォルダとenvironmentフォルダがあります。この２つが、CONGAにとっての２つの大きな領域になります。違いを以下にまとめると：

definitionフォルダ

主に開発者が関与する領域で、当フォルダ下を開発者がいじります。
ローカル環境のAEMインスタンスに設定を適用させます。

environmentフォルダ

主に運用担当者が関与する領域で、当フォルダ下を運用担当者がいじります。
実運用しているAEMインスタンスに設定を適用させます。

ところで、どちらの領域にも共通点があります。
definitionフォルダとenvironmentフォルダを開いてみると、どちらにも以下の２つがあることがわかります：

  • src/mainフォルダ
    • definition/src/main
    • environment/src/main
  • target/configurationフォルダ
    • definition/target/configuration
    • environment/target/configuration
├─definition
│  ├─src
│  │  └─main
│  └─target
│       └─configuration
│
├─environment
│  ├─src
│  │  └─main
│  └─target
│       └─configuration

ここで、共通点として存在するこの２つのフォルダはいったい何なのか、まずはざっくり確認しておきましょう：

src/mainフォルダ

設定内容を記述するYAMLファイルを格納するフォルダです。

target/configurationフォルダ

設定を適用するためのパッケージやwebserver用設定ファイル（dispatcher.anyなど）を格納するフォルダです。

詳細についてはチュートリアル編で具体的に解説します。
だいたいのストラクチャがわかったところで、実際にCONGAを使ってみましょう。

【チュートリアル編】CONGAを使ってみよう

環境準備

実習１：AEMインスタンスにプロジェクトをデプロイする

(1) ローカルAEM Authorインスタンス（ポート番号：4502）を起動します。
(2) 以下をそれぞれ開いて中身を確認してみましょう：

1. development.yaml ファイル

場所：training-conga-exercise-aem\definition\src\main\dev-environments
ローカル環境用の設定を記述するファイルです。

2. packages-upload.sh ファイル

場所：training-conga-exercise-aem\definition
このファイルを実行することにより、作成した設定をAEMインスタンスに適用（デプロイ）します。厳密にはCONGA AEM Maven pluginを使用し、作成されたパッケージをAEMインスタンスにデプロイしているとのこと。

(3) training-conga-exercise-aem下で、mvn clean installコマンドを実行します。

この時点で以下の場所にパッケージが作成されますが、まだAEMインスタンスに適用（インストール）されてはいません ：training-conga-exercise-aem\definition\target\configuration\development\aem-author\packages

(4) training-conga-exercise-aem\definition下にてpackages-upload.shを実行します。

※シェルスクリプトを実行する必要があるため、Windowsの場合はCygwin/Msys2/Git Bash等の端末でコマンドを実行してください。

sh packages-upload.sh

このコマンドが実行されることにより、手順３で作成されたパッケージをAEMインスタンスにインストールされます。

(5) BUILD SUCCESSになったら、Authorインスタンスで以下を開くことができれば、パッケージが無事インストールされたことがわかります。新しく追加されたwcm-io-samplesコンテンツはサンプルプロジェクトです。

http://localhost:4502/editor.html/content/wcm-io-samples/en.html

また、パッケージマネジャー画面にてインストールされたパッケージを見ると、 training-conga-exercise-aem\definition\target\configuration\development\aem-author\packages下にあるパッケージ全てと一致していることがわかります。

実習２：CRXDEを有効にする

CRXDEを有効にする方法はこちらに紹介されていますが、ここではCONGAを使ってCRXDEを有効に設定します。

(1) AEMインストール（初回起動）前の状態にします。crx-quickstartフォルダを削除し、jarファイルとlicense.propertiesファイルのみあることを確認。

(2) Authorインスタンスをnosamplecontent実行モードで起動します。

java -jar aem-author-4502.jar -gui -r nosamplecontent

(3) Authorインスタンスが起動できたら、まずはログインしてCRXDEを開いて、コンテンツツリーが表示されないことを確認します。CONGAでCRXDEを有効化する設定を作り、これから適用します。

(4) development.yaml（training-conga-exercise-aem\definition\src\main\dev-environments）の19行目に以下を追加：

  quickstart:
    port: 4502
    runmodes:
    - author
    - nosamplecontent
    enableDavEx: true
    rootPath: crx/server

※インデントを少しでも間違えると次手順のビルド時にてエラーが出るので注意。

(5) training-conga-exercise-aem下に戻り、mvn clean installコマンドを実行します。

この時点で以下の場所にパッケージが作成（既にある場合は更新）されますが、まだAEMインスタンスに適用（インストール）されてはいません ：training-conga-exercise-aem\definition\target\configuration\development\aem-author\packages

(6) training-conga-exercise-aem\definition下にてpackages-upload.shを実行します。

※シェルスクリプトを実行する必要があるため、Windowsの場合はCygwin/Msys2/Git Bash等の端末でコマンドを実行してください。

sh packages-upload.sh

このコマンドが実行されることにより、手順５で作成されたパッケージをAEMインスタンスにインストールされます。

(7) CRXDEを再度開き、以下を確認します：
- コンテンツツリーが見れること
- OSGiコンフィグファイルがあることを確認する（/apps/aem-cms-system-config/config.author/org.apache.sling.jcr.davex.config）

これにてCRXDEが有効化されました！

解説

実習２ではdevelopment.yamlを編集し、新たに設定をAEMインスタンスに適用しました。
ここでdefinitionフォルダの構造を見てみると以下のようになっています：

├─definition
│  ├─src
│  │  └─main
│  │      ├─dev-environments
│  │      │   └─development.yaml
│  │      ├─roles
│  │      └─templates
│  │
│  ├─target
│  │   └─configuration
│  │      └─development
│  │         └─aem-author
│  │            └─packages
│  │
│  ├─packages-upload.sh

※解説を簡潔にするため、一部省略している箇所もあります。

CONGAのストラクチャで触れた通り、definition/src/mainフォルダは設定内容を記述するYAMLファイルを格納するフォルダです。ここではさらにdev-environmentsというフォルダがあり、その中にdevelopment.yamlがあります。

development.yamlファイル

development.yamlを開くと、内容は大きく分けてnodesとconfigの２つがあります。

# AEM configuration for local development environment

nodes:

- node: aem-author
  roles:
  - role: wcm-io-samples-cms
    variant: aem-author

- node: aem-publish
  roles:
  - role: wcm-io-samples-cms
    variant: aem-publish

config:
  contentPackage.group: wcm-io-samples
  app.sampleContent: true

  quickstart:
    port: 4502
    runmodes:
    - author
    - nosamplecontent
    enableDavEx: true
    rootPath: crx/server

  # Log levels
  log:
    projectSpecificLogLevel: info

nodes

nodes下に、設定を適用させる対象（node）を記述します。
ここで記述したnode名に一致したフォルダをtarget/configuration/development下にあることを確認しましょう。

config

config下に、設定内容をYAML形式で記述します。
設定可能なパラメータや取り得る値などが記載されたドキュメントがほぼなく、公式GithubにあるYAMLファイル（https://github.com/wcm-io-devops/conga-aem-definitions/blob/develop/conga-aem-definitions/src/main/roles/aem-cms.yaml）を参考にしました。

packages-upload.shファイル

どの環境にどの設定を適用させるのかを定義します。
重要な箇所をピックアップすると、以下の２行になります：

CONGA_ENVIRONMENT="development"
CONGA_NODE="aem-author"

順番に見ていきましょう。

CONGA_ENVIRONMENTには、YAMLファイル名を記述します。実習２で編集したdevelopment.yamlに該当します。

CONGA_NODEには、適用させたいnode名を記述します。ただし、以下を満たす必要があります：
- CONGA_ENVIRONMENTに記述したYAMLファイル名に含まれているnode名であること
- target/configuration下に、node名と一致する名前がついたフォルダがあること

実習２ではAuthorインスタンスに設定を適用させたのでCONGA_NODEの値はaem-authorになっていますね。

さいごに

いかがでしょう、実際にCONGAをいじってみることで気づいたことや理解できることは多いかと思います。

せっかく便利で良いツールがあっても情報が少ないと浸透しにくくなってしまいますし、何か新しいことを学習する時に、はじめての人にもわかりやすい・入り込みやすい状態が準備されていることは大事だと私は思います。トレーナー立場の意見ではありますが...

今回のCONGAチュートリアルを通じて、少しでも学べることがあればうれしいです。 他にも研究したいものがたくさんありますので、今後もシェアできればと思います。 引き続きどうぞよろしくお願いいたします。

参考

CONGA
https://devops.wcm.io/conga/

CONGAチュートリアル
https://training.wcm.io/conga/

Github
https://github.com/wcm-io-devops/conga

CONGA definitionファイルサンプル
AEMインスタンス用：
https://github.com/wcm-io-devops/conga-aem-definitions/blob/develop/conga-aem-definitions/src/main/roles/aem-cms.yaml

Dispatcher用：
https://github.com/wcm-io-devops/conga-aem-definitions/blob/develop/conga-aem-definitions/src/main/roles/aem-dispatcher.yaml

他 AEM DevOps系はここをさらに掘り探すといいかもです：
https://github.com/wcm-io-devops/