- About
- Setup
- Prerequisites
- Configuration
- Health checks
- Task environmentUp
- Task environmentDown
- Task environmentDev
- Task environmentAwait
- Task environmentReload
- Task environmentHosts
- License
Provides seamless Gradle integration with Docker & Compose/Swarm. Hides many OS-specific glitches from unexperienced Docker users.
Controls virtualized environment consisting of any Docker-compatible software (e.g Apache Web Server (HTTPD), SQL/noSQL databases). Such software is deployed as Docker Containers orchestrated by Compose or Swarm. This solution is cross-platform just like Docker.
Provides environment related tasks: environmentUp, environmentDev, environmentHosts etc.
As of plugin is published at official Gradle Plugin Portal, see instructions from there.
Most of the configuration steps are automated. However, there are three manual steps to make this setup fully operating:
Ensure having shared folders enabled via GUI:
Please note that after each Windows credentials change (e.g forced by company policy), it is required to click button "Reset credentials" to ensure having shared drives working correctly.
When running task environmentUp first time, Windows User Account Control (UAC) may require user confirmation to allow virtualized container to access local configuration files stored on shared drives.
While using Docker Toolbox, beware that, by default, there is only one shared folder in VirtualBox configured which mounts C:/Users to /c/users on Docker Machine / Ubuntu. As a consequence, if project is located outside of C:/Users directory, there is a need to manually add corresponding shared folder and mount it on Docker Machine using VirtualBox GUI.
To configure containers to be deployed using Docker Compose (by default) or Swarm, simply create standard Docker Compose file but with templating (file at path src/environment/docker-compose.yml.peb)
version: "3"
services:
httpd:
image: centos/httpd:latest
command: ["tail", "-f", "--retry", "/usr/local/apache2/logs/error.log"]
ports:
- "80:80"
volumes:
- "{{ rootPath }}/env/src/environment/httpd/conf/httpd.conf:/etc/httpd/conf/httpd.conf"
- "{{ rootPath }}/app/aem/dispatcher/src/conf.d:/etc/httpd/conf.d"
- "{{ rootPath }}/app/aem/dispatcher/src/conf.dispatcher.d:/etc/httpd/conf.dispatcher.d"
- "{{ workPath }}/httpd/modules/mod_dispatcher.so:/etc/httpd/modules/mod_dispatcher.so"
- "{{ workPath }}/httpd/logs:/etc/httpd/logs"
{% if docker.runtime.safeVolumes %}
- "{{ workPath }}/httpd/cache:/var/www/localhost/cache"
- "{{ workPath }}/httpd/htdocs:/var/www/localhost/htdocs"
{% endif %}
{% if docker.runtime.hostInternalIpMissing %}
extra_hosts:
- "host.docker.internal:{{ docker.runtime.hostInternalIp }}"
{% endif %}
Docker has differences in case of how it works on different operating systems. While using templating and variables in that file, Gradle Environment Plugin tries to mitigate these differences, to make your build working smoothly on all OSes and hide glitches from unexperienced Docker users. For example, when using Docker Toolbox, paths should be absolute and having Unix separators despite that host OS is Windows.
Example above comes from that file which is setting up Apache HTTPD for Adobe Experience Manager.
Moreover, plugin comes with rich DSL which allows to:
- run callbacks on each container lifecycle event (resolve, up, reload, dev),
- configure where container resources are stored,
- configure health checks to be able to detect moment in build lifecycle when are container services are stable and be ready to perform next build tasks using these services,
- configure hosts which should be appended to OS-specific hosts file.
environment { // config for AEM environment running on Docker
rootDir.set(prop.string("environment.rootDir")) // project.file(".environment")
hosts { // domains to be appended to hosts file automatically
"http://example.com" { tag("publish") }
"http://locahost:4502" { tag("author") }
}
docker { // Docker specific configuration
containers {
"httpd" { // control container described in 'docker-compose.yml.peb'
resolve {
resolveFiles {
download("http://download.macromedia.com/dispatcher/download/dispatcher-apache2.4-linux-x86_64-4.3.2.tar.gz").use {
copyArchiveFile(it, "**/dispatcher-apache*.so", file("modules/mod_dispatcher.so"))
}
}
ensureDir("cache", "logs")
}
up {
ensureDir("/usr/local/apache2/logs", "/opt/aem/dispatcher/cache/content/example/demo", "/opt/aem/dispatcher/cache/content/example/live")
execShell("Starting HTTPD server", "/usr/local/apache2/bin/httpd -k start")
}
reload {
cleanDir("/opt/aem/dispatcher/cache/content/example/demo", "/opt/aem/dispatcher/cache/content/example/live")
execShell("Restarting HTTPD server", "/usr/local/apache2/bin/httpd -k restart")
}
dev {
watchSourceDir("conf")
}
}
}
}
healthChecks { // checks (e.g GET requests) verifying running Docker containers like HTTPD
http("http://example.com/en-us.html", "Live site", "English US")
http("http://author.example.com/sites.html", "Author module 'Sites'") {
containsText("Sites")
options { basicCredentials = authorInstance.credentials }
}
}
}In case of the dispatcher it takes few seconds to start. Service health checks could be described by following configuration. For example, to wait for all domains to be available and having particular text in response, write:
environment {
healthChecks {
http("http://example.com/en-us.html", "Live site", "English US")
}
}These checks are performed automatically after each file change applied when running task environmentDev or on demand when running task environmentAwait.
Turns on local environment.
Turns off local environment.
Allows to listen for Apache Web Server / Dispatcher configuration files changed and then automatically reload HTTP service.
Workflow:
- Run command
gradlew environmentDev, - Edit files located in src/environment/httpd/conf ,
- Notice that HTTPD service should be restarted automatically after file changes,
- Check results of health checks,
- Optionally, check:
- HTTPD logs located at path .environment/httpd/logs
Performs environment service health checks on demand.
Reloads virtualized environment by reloading all Docker containers (e.g. removing Dispatcher cache files then restarting HTTPD server).
Amends hosts entries in OS-specific file.
Example configuration:
environment {
hosts { // domains to be appended to hosts file automatically
"example.com" { tag("live site") }
"demo.example.com" { tag("demo site") }
"cms" { tag("cms authoring") }
}
}The task will run on Windows & Mac OS interactive process asking for administrative/sudo permissions to be able to edit the hosts file. On other OSes / Unix-based systems, the task will print a path to the generated script to be executed with sudo rights but in a non-interactive way (to be done separately right after this task execution.
Options:
hostUpdater.enabled=false- allows to disable temporarily host amendmend (e.g on CI/CD),hostUpdater.interactive=false- potentially useful when interactive mode does not work for unknown/OS-specific reason,hostUpdater.force=true- by default, updater is lazy - it will not ask for administrative/sudo mode if the hosts file does not need to be updated.
Gradle Environment Plugin is licensed under the Apache License, Version 2.0 (the "License")