{"id":21726961,"url":"https://github.com/wttech/gradle-environment-plugin","last_synced_at":"2025-04-12T23:33:54.128Z","repository":{"id":43113193,"uuid":"237183501","full_name":"wttech/gradle-environment-plugin","owner":"wttech","description":"Provides seamless Gradle integration with Docker \u0026 Compose/Swarm for creating local development environments in a fully automated manner.","archived":false,"fork":false,"pushed_at":"2023-10-10T10:53:55.000Z","size":714,"stargazers_count":4,"open_issues_count":2,"forks_count":0,"subscribers_count":9,"default_branch":"main","last_synced_at":"2025-04-12T23:33:46.032Z","etag":null,"topics":["docker","docker-compose","docker-container","docker-gradle","docker-image","gradle","gradle-plugin","gradle-plugin-kotlin","health-checks","swarm"],"latest_commit_sha":null,"homepage":"https://tech.cognifide.com","language":"Kotlin","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/wttech.png","metadata":{"files":{"readme":"README.MD","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null}},"created_at":"2020-01-30T09:51:48.000Z","updated_at":"2022-04-25T23:02:17.000Z","dependencies_parsed_at":"2023-01-19T01:45:38.093Z","dependency_job_id":null,"html_url":"https://github.com/wttech/gradle-environment-plugin","commit_stats":null,"previous_names":[],"tags_count":88,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/wttech%2Fgradle-environment-plugin","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/wttech%2Fgradle-environment-plugin/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/wttech%2Fgradle-environment-plugin/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/wttech%2Fgradle-environment-plugin/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/wttech","download_url":"https://codeload.github.com/wttech/gradle-environment-plugin/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248647259,"owners_count":21139081,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["docker","docker-compose","docker-container","docker-gradle","docker-image","gradle","gradle-plugin","gradle-plugin-kotlin","health-checks","swarm"],"created_at":"2024-11-26T03:42:27.560Z","updated_at":"2025-04-12T23:33:54.110Z","avatar_url":"https://github.com/wttech.png","language":"Kotlin","readme":"[![WTT logo](docs/wtt-logo.png)](https://www.wundermanthompson.com)\n\n[![Apache License, Version 2.0, January 2004](docs/apache-license-badge.svg)](http://www.apache.org/licenses/)\n\n# Gradle Environment Plugin\n\n  * [About](#about)\n  * [Setup](#setup)\n  * [Prerequisites](#prerequisites)\n     * [Notice for Docker on Windows](#notice-for-docker-on-windows)\n     * [Notice for Docker Toolbox](#notice-for-docker-toolbox)\n  * [Configuration](#configuration)\n     * [Docker compose file](#docker-compose-file)\n     * [DSL options](#dsl-options)\n  * [Health checks](#health-checks)\n  * [Task environmentUp](#task-environmentup)\n  * [Task environmentDown](#task-environmentdown)\n  * [Task environmentDev](#task-environmentdev)\n  * [Task environmentAwait](#task-environmentawait)\n  * [Task environmentReload](#task-environmentreload)\n  * [Task environmentHosts](#task-environmenthosts)\n  * [License](#license)\n\n## About\n\nProvides seamless Gradle integration with Docker \u0026 Compose/Swarm. Hides many OS-specific glitches from unexperienced Docker users.\n\nControls virtualized environment consisting of any Docker-compatible software (e.g Apache Web Server (HTTPD), SQL/noSQL databases).\nSuch software is deployed as [Docker Containers](https://www.docker.com/resources/what-container) orchestrated by [Compose](https://docs.docker.com/compose/) or [Swarm](https://docs.docker.com/engine/swarm/). This solution is cross-platform just like Docker.\n\nProvides environment related tasks: `environmentUp`, `environmentDev`, `environmentHosts` etc.\n    \n## Setup\n\nAs of plugin is published at official Gradle Plugin Portal, see instructions from [there](https://plugins.gradle.org/plugin/com.cognifide.environment).\n\n## Prerequisites\n\nMost of the configuration steps are automated. However, there are three manual steps to make this setup fully operating:\n\n* [Install Docker](https://docs.docker.com/install/)\n    * [Mac](https://docs.docker.com/docker-for-mac/)\n    * [Ubuntu](https://docs.docker.com/install/linux/docker-ce/ubuntu/)\n    * Windows\n        * [Desktop](https://docs.docker.com/docker-for-windows/install/) (highly recommended, using Hyper-V)\n        * [Toolbox](https://docs.docker.com/toolbox/toolbox_install_windows/) (legacy, using VirtualBox)\n\n\n### Notice for Docker on Windows\n\nEnsure having shared folders enabled via GUI:\n\n![Docker Desktop Shared Drive](docs/docker-desktop-share.png)\n\nPlease 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.\nWhen 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.\n\n### Notice for Docker Toolbox\n\nWhile 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. \nAs 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.\n\n## Configuration\n\n### Docker compose file\n\nTo 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*)\n\n```pebble\nversion: \"3\"\nservices:\n  httpd:\n    image: centos/httpd:latest\n    command: [\"tail\", \"-f\", \"--retry\", \"/usr/local/apache2/logs/error.log\"]\n    ports:\n      - \"80:80\"\n    volumes:\n      - \"{{ rootPath }}/env/src/environment/httpd/conf/httpd.conf:/etc/httpd/conf/httpd.conf\"\n      - \"{{ rootPath }}/app/aem/dispatcher/src/conf.d:/etc/httpd/conf.d\"\n      - \"{{ rootPath }}/app/aem/dispatcher/src/conf.dispatcher.d:/etc/httpd/conf.dispatcher.d\"\n      - \"{{ workPath }}/httpd/modules/mod_dispatcher.so:/etc/httpd/modules/mod_dispatcher.so\"\n      - \"{{ workPath }}/httpd/logs:/etc/httpd/logs\"\n      {% if docker.runtime.safeVolumes %}\n      - \"{{ workPath }}/httpd/cache:/var/www/localhost/cache\"\n      - \"{{ workPath }}/httpd/htdocs:/var/www/localhost/htdocs\"\n      {% endif %}\n    {% if docker.runtime.hostInternalIpMissing %}\n    extra_hosts:\n      - \"host.docker.internal:{{ docker.runtime.hostInternalIp }}\"\n    {% endif %}\n```\n\nDocker has differences in case of how it works on different operating systems. While using templating and [variables](src/main/kotlin/com/cognifide/gradle/environment/docker/Docker.kt#L46) 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.\n\nExample above comes from [that file](https://github.com/Cognifide/gradle-aem-multi/blob/master/env/src/environment/docker-compose.yml.peb) which is setting up Apache HTTPD for [Adobe Experience Manager](https://www.adobe.com/pl/marketing/experience-manager.html).\n\n### DSL options\n\nMoreover, plugin comes with rich DSL which allows to:\n\n* run callbacks on each container lifecycle event (resolve, up, reload, dev),\n* configure where container resources are stored,\n* 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,\n* configure hosts which should be appended to OS-specific hosts file.\n\n```kotlin\nenvironment { // config for AEM environment running on Docker\n    rootDir.set(prop.string(\"environment.rootDir\")) // project.file(\".environment\")\n    hosts { // domains to be appended to hosts file automatically\n        \"http://example.com\" { tag(\"publish\") }\n        \"http://locahost:4502\" { tag(\"author\") }\n    }\n    docker { // Docker specific configuration\n        containers {\n            \"httpd\" { // control container described in 'docker-compose.yml.peb'\n                resolve {\n                    resolveFiles {\n                        download(\"http://download.macromedia.com/dispatcher/download/dispatcher-apache2.4-linux-x86_64-4.3.2.tar.gz\").use {\n                            copyArchiveFile(it, \"**/dispatcher-apache*.so\", file(\"modules/mod_dispatcher.so\"))\n                        }\n                    }\n                    ensureDir(\"cache\", \"logs\")\n                }\n                up {\n                    ensureDir(\"/usr/local/apache2/logs\", \"/opt/aem/dispatcher/cache/content/example/demo\", \"/opt/aem/dispatcher/cache/content/example/live\")\n                    execShell(\"Starting HTTPD server\", \"/usr/local/apache2/bin/httpd -k start\")\n                }\n                reload {\n                    cleanDir(\"/opt/aem/dispatcher/cache/content/example/demo\", \"/opt/aem/dispatcher/cache/content/example/live\")\n                    execShell(\"Restarting HTTPD server\", \"/usr/local/apache2/bin/httpd -k restart\")\n                }\n                dev {\n                    watchSourceDir(\"conf\")\n                }\n            }\n        }                        \n    }\n    healthChecks { // checks (e.g GET requests) verifying running Docker containers like HTTPD\n          http(\"http://example.com/en-us.html\", \"Live site\", \"English US\")\n          http(\"http://author.example.com/sites.html\", \"Author module 'Sites'\") {\n              containsText(\"Sites\")\n              options { basicCredentials = authorInstance.credentials }\n          }\n    }\n}\n```\n\n## Health checks\n\nIn case of the dispatcher it takes few seconds to start. Service health checks could be described by following configuration.\nFor example, to wait for all domains to be available and having particular text in response, write:\n\n```kotlin\nenvironment {\n    healthChecks {\n        http(\"http://example.com/en-us.html\", \"Live site\", \"English US\")\n    }\n}\n```\n\nThese checks are performed automatically after each file change applied when running task `environmentDev` or on demand when running task `environmentAwait`.\n\n## Task `environmentUp`\n\nTurns on local environment.\n\n![Environment up task](docs/environment-up-task.gif)\n\n## Task `environmentDown`\n\nTurns off local environment.\n\n![Environment down task](docs/environment-down-task.gif)\n\n## Task `environmentDev`\n\nAllows to listen for Apache Web Server / Dispatcher configuration files changed and then automatically reload HTTP service.\n\nWorkflow:\n\n1. Run command `gradlew environmentDev`,\n2. Edit files located in *src/environment/httpd/conf* ,\n3. Notice that HTTPD service should be restarted automatically after file changes,\n4. Check results of [health checks](#health-checks),\n4. Optionally, check:\n   * HTTPD logs located at path *.environment/httpd/logs*\n   \n![Environment dev task](docs/environment-dev-task.gif)\n\n## Task `environmentAwait`\n\nPerforms [environment service health checks](#environment-service-health-checks) on demand.\n\n## Task `environmentReload`\n\nReloads virtualized environment by reloading all Docker containers (e.g. removing Dispatcher cache files then restarting HTTPD server).\n\n## Task `environmentHosts`\n\nAmends hosts entries in OS-specific file.\n\nExample configuration:\n\n```kotlin\nenvironment {\n    hosts { // domains to be appended to hosts file automatically\n        \"example.com\" { tag(\"live site\") }\n        \"demo.example.com\" { tag(\"demo site\") }\n        \"cms\" { tag(\"cms authoring\") }\n    }\n}\n```\n\nThe task will run on Windows \u0026 Mac OS interactive process asking for administrative/sudo permissions to be able to edit the hosts file.\nOn 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.\n\nOptions:\n\n- `hostUpdater.enabled=false` - allows to disable temporarily host amendmend (e.g on CI/CD),\n- `hostUpdater.interactive=false` - potentially useful when interactive mode does not work for unknown/OS-specific reason,\n- `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.\n\n## License\n\n**Gradle Environment Plugin** is licensed under the [Apache License, Version 2.0 (the \"License\")](https://www.apache.org/licenses/LICENSE-2.0.txt)\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fwttech%2Fgradle-environment-plugin","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fwttech%2Fgradle-environment-plugin","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fwttech%2Fgradle-environment-plugin/lists"}