1. Overview

• Example Scenarios

1. Usage

• Prerequisites
• Setup
• Setup Parameters
• Vagrant

1. Host System

• System Requirements
• Cautions

1. Guest System

• Running Applications
• Access Points

1. Contributing

This project is a tool to help developers manage virtual machines contianing AEM instances. It is designed to allow quick setup and creation of vagrant images with a full AEM stack: Author, Publish, & Dispatcher.

This is an example for the use of this project, there are two roles in it's use:

Team Lead Tasks

1. A new project is tasked to a development team.
2. Team lead forks the project and clones it to local system.
3. Lead creates a branch for the new project/client.
4. Lead runs the setup script providing responses or a manually managed parameter file.
5. The setup creates the appropriate Vagrant file, Puppet site manifest, and other necessary files.
6. Lead edits the gitignore files to allow for check-in of the files created by the setup process.
7. Lead commits & pushes the branch out.
8. Run vagrant up and create a new VM for development.

Team Member Tasks

1. Clones forked project and switches to new branch.
2. Run vagrant up and create a new VM for development.

The end result is a standard work environment for the entire team, one that hopefully matches the Development environment.

Supporting Software

1. Vagrant (v1.8.4)
2. Do not use v1.8.5; it has an issue when updating the authorized keys.

Required

1. AEM Quickstart jar file
2. AEM Dispatcher module for your web server
3. AEM License Key for your client

Optional

1. Java JDK that is required for your client. Java or OpenJDK
2. Custom dispatcher.any file

There are two options for preparing the vagrant configuration: Answering questions during setup or creating a parameter file.

There is a setup script which will prompt for necessary configuration needs. This script will prepare the templated files so Vagrant will provision the system correct. Usage from root folder:

> setup/setup.rb

This will create a file ./setup/parameters.json containing the responses. This allows for other teams to quickly reuse an existing configuration.

The setup script will output all answers to the prompted questions to a file for future use. This file can also be manually created and specified as a parameter to the setup script:

> setup/setup.rb setup/parameters.json

Doing so will read the file, and configure the setup accordingly. If any required parameter is missing, that item will be requested via a prompt.

Keep in mind that the setup process will replace all contents of the parameter file with the new information.

This is an example of a file which shows format and parameters:

{
  "client" : "test",
  "jdk_pkg" : "",
  "aem_jar" : "/path/to/aem-quickstart-6.1.jar",
  "aem_license" : "your license here",
  "dispatcher_mod" : "/path/to/dispatcher-apache2.4-4.1.10.so",
  "dispatcher_any" : ""
}

The following are the parameters which are needed in order to setup the Vagrant and puppet configuration files. They are propmpted for in the script and used in the JSON parameter file:

Required. This is the name of the client for which the VM is intended. This is used as way to distinguish this system from others on the host. It affects:

• VM name in VirtualBox
• Host name for accessing dispatcher content (See Access Points).
• Docroot in the HTTP Server configurations.

Format: Any valid string.

Optional. This specifies the package to use when installing the JDK. If not provided, the default JDK for the system will be used. Format: fully qualified path to file.

Required. This specifies the location of the AEM installation jar. This file is not provided as part of this project, and must be provided by the consumer. Format: fully qualified path to file.

Required. This is the license key for running the AEM system. Format: String.

Required. This specifies the location of the AEM dispatcher module. This file is not provided as part of this project, and must be provided by the consumer. Format: fully qualified path to file.

Optional. This is a dispatcher.any file which can be specified for use, instead of the default template Format: fully qualified path to file.

Once the setup has been accomplished, the vagrant system can be started:

> vagrant up

This step will take time to run, as it is configuring and setting up all of the software on the guest.

If there is an update to the setup defintions, then a system reprovision may be required. This is as simple as executing this command while the VM is running:

> vagrant provision

Because of the number of applications running inside the guest, the definition is configured to consume a relatively large amount of system resources. It is recommended that the host sytem have:

• 4 CPUs (or cores)
• 16 GB of RAM
• 100 GB free disk space

The following items are required for the setup process, and are not provided by this project:

• AEM Quickstart Jar
• Dispatcher Module

The following ports are forwarded to the guest VM. If any are unavailable, the guest system may not start corrrectly:

• 4502
• 4503
• 10080
• 18080
• 18009
• 30300
• 30303
• 30304

The following applications are running by default:

• HTTP Server
  • w/ dispatcher module
• AEM Author
• AEM Publish

Most of the systems inside the VM are accessible using two different URLs. This is due to possible cookie issues when using just host/port combination, therefore named virtual hosts are also provided.

• http://localhost:4502/
• http://author.localhost:10080/

Debugging is enabled by default on the Author system, connect using port 30303.

• http://localhost:4503/
• http://publish.localhost:10080/

Debugging is enabled by default on the Author system, connect using port 30304.

• http://localhost:10080
• http://<<client>>.localhost:10080

This project was the driver behind the Puppet AEM module. As new features are added to that module, this project will be updated to incorporate their use for standarization of environments.

Contributions are always welcome, however please ensure that no AEM Quickstar jars or license keys are included in pull requests.