2.1.1 - Documentation improvements (#15)

* pom.xml
 * Bumped pom to 2.1.0

* pom.xml, publish-maven-package.yml
 * Added profiles

* NginxFileServer.groovy
 * Fixed bug in FileServerConfig which breaks creation of subdirectories

* Mainly working on documentation in README.md

* Basic JSM Setup.groovy, JsmH2Deployment.groovy
 * Improved documentation and comments

* Bumped pom to 2.1.1

Author: farthinder

.gitignore

@@ -1,7 +1,7 @@
 /target/
 /.idea/vcs.xml
-/Environments/Terraform/.terraform/
-/Environments/Terraform/.terraform.lock.hcl
-/Environments/Terraform/.terraform.tfstate.lock.info
-/Environments/Terraform/terraform.tfstate
-/Environments/Terraform/terraform.tfstate.backup
+/Environments/AWS/.terraform/
+/Environments/AWS/.terraform.lock.hcl
+/Environments/AWS/.terraform.tfstate.lock.info
+/Environments/AWS/terraform.tfstate
+/Environments/AWS/terraform.tfstate.backup

Environments/Terraform/iam.tf Environments/AWS/iam.tfEnvironments/Terraform/iam.tf renamed to Environments/AWS/iam.tf

@@ -25,9 +25,9 @@ variable "aws_credentials" {
 variable "dockerServerCert" {
   type = map(string)
   default = {
-    "tlscacert" = "../../resources/dockerCert/ca.pem"
-    "tlscert" = "../../resources/dockerCert/server-cert.pem"
-    "tlskey" = "../../resources/dockerCert/server-key.pem"
+    "tlscacert" = "~/.docker/ca.pem"
+    "tlscert"   = "~/.docker/server-cert.pem"
+    "tlskey"    = "~/.docker/server-key.pem"
   }
 
 }

Environments/Terraform/main.tf Environments/AWS/main.tfEnvironments/Terraform/main.tf renamed to Environments/AWS/main.tf

@@ -1,25 +1,64 @@
+# DevStack
 
+DevStack is intended for the DevOps engineer who finds her/him self constantly jumping between different DevOps enterprise tools to deliver new solutions.
 
-## Setup of test Environment
+DevStack gives you simple to reuse groovy classes for spinning up new test environments in a local or remote docker engine and automates the basic setup of the individual tool.
 
-//TODO add info about license files
+## What does it really do?
 
-1. Setup certs in resources/dockerCert
+DevStack creates local or remote docker containers, sets up docker level networking, spins up the container with sensible settings and configures the basic settings needed inside the tool to get it up and running.
+
+Example: [JsmAndBitbucketH2Deployment.groovy](src%2Fmain%2Fgroovy%2Fcom%2Feficode%2Fdevstack%2Fdeployment%2Fimpl%2FJsmAndBitbucketH2Deployment.groovy)
+
+This class will help you spin up JIRA and Bitbucket containers in the same docker network, configure sensible JAVA environment variables, setup DBs for both applications, install JIRA apps and create an Application Link between them.
+
+## Pros/Cons
+
+### Pro
+* Facilitate testing of complex setups
+  * Got a complex flow involving Jira, Bitbucket, Jenkins, Harbor and now you are afraid of upgrading?
+    * Integrate DevStack in your Spock test, configure it to spin up a mirror of your environment and the flow. Tweak the version used and run your test.
+* Takes over after Docker has done its thing.
+  * Docker is great for starting an application like JIRA but then it´s up to you (or DevStack) to setup, DB, Apps, Admin accounts, licenses.
+* Move away from Snowflake test environments, test your changes in fresh environments every time.
+* DevStack can use local or remote Docker engines, making running the tests locally on your machine easy while still offloading the heavy lifting to a cloud Docker Engine. 
+
+### Cons
+* DevStack is not intended for production use ever, it should only be used for short-lived test environments with nothing to loose.
+* Not intended for existing environments, presumes DevStack was used to setup up the environment. 
+
+# Setup Docker Engine in AWS
+
+DevStack defaults to trying to connect to a local Docker engine, but a terraform project is supplied for setting up a remote EC2 with docker engine. The docker engine will be configured to only accept HTTPS from your IP.  
+
+### Requirements:
+ * An AWS account with no vital data
+   * With corresponding Access and Secret key: [Check guide](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_credentials_access-keys.html#Using_CreateAccessKey)
+ * CA, Server and Client certs 
+   * This script can be used for generating the Certs: [createCerts](https://gist.github.com/farthinder/9df3019e2e01cdd167dd02abf7d5f903)
+ * SSH Keys
+
+1. Setup Docker Engine certs in ~/.docker/
     * ca.pem: A ca cert that signed the other certs
-    * cert.pem & key.pem: Public and private keys to be used by docker client
-    * server-cert.pem & server-key.pem: Public and private keys to be used by docker server. Should be setup for domain name: docker.domain.se
+    * server-cert.pem & server-key.pem: Public and private keys to be used by docker server. By convention DevStack uses: docker.domain.se, but anything is fine aslong as you can put it in your hosts file.
+    * ~/.docker/ is the default place but can be changed in [variables.tf](Environments%2FAWS%2Fvariables.tf)
+
+2. Setup Docker Client certs in ~/.docker/
+   * ca.pem: A ca cert that signed the other certs (same as in step 1)
+   * cert.pem & key.pem: Public and private keys to be used by docker client
+   * The ~/.docker/ location is arbitrary and ultimately determined by you when you instantiate DevStack classes.  
 
-2. Set up an AWS account with high (admin) privileges in an ISOLATED test account *WITH NO VITAL SETUPS*
+3. Set up an AWS account with high (admin) privileges in an ISOLATED test account *WITH NO VITAL DATA*
     * Get Access Key and Secret Key for the account
-    * Update *aws_credentials* in Environments/Terraform/variables.tf
+    * Update *aws_credentials* in Environments/AWS/variables.tf
 
-3. Make sure you have a valid public SSH key in ~/.ssh/id_rsa.pub
-    * Or update *ssh-public-key-local-path* in Environments/Terraform/variables.tf
+4. Make sure you have a valid public SSH key in ~/.ssh/id_rsa.pub
+    * Or update *ssh-public-key-local-path* in Environments/AWS/variables.tf
 
-4. Update *trusted-external-ips* in Environments/Terraform/variables.tf
+5. Update *trusted-external-ips* in Environments/AWS/variables.tf
     * This should normally be set to your external ip, check for example: https://whatismyipaddress.com
 
-5. Go to Environments/Terraform and run terraform apply
+6. Go to Environments/Terraform and run terraform apply
     * Note the "Hosts-record" output, this needs to be added to your /etc/hosts
 
 

…vironments/Terraform/ubuntu_user_data.sh Environments/AWS/ubuntu_user_data.shEnvironments/Terraform/ubuntu_user_data.sh renamed to Environments/AWS/ubuntu_user_data.sh Environments/Terraform/ubuntu_user_data.sh renamed to Environments/AWS/ubuntu_user_data.sh

@@ -2,6 +2,17 @@ import com.eficode.devstack.deployment.impl.JsmH2Deployment
 
 String jiraBaseUrl = "http://localhost:8080"
 JsmH2Deployment jsmDep = new JsmH2Deployment(jiraBaseUrl)
-File projectRoot = new File(".")
+File projectRoot = new File("../").canonicalFile
+
+//Set JSM license that should be used
 jsmDep.setJiraLicense(new File(projectRoot.path + "/resources/jira/licenses/jsm.license"))
+
+//Optional settings
+//jsmDep.jsmContainer.containerImageTag = "5.5.1" //Set docker image (and JSM) version
+//jsmDep.jsmContainer.containerName = "Testing" //Set custom container name
+//jsmDep.jsmContainer.jvmMaxRam = 4000 //Set max ram used by JSM
+//jsmDep.appsToInstall = ["https://marketplace.atlassian.com/download/apps/6820/version/1005740":new File(projectRoot.path + "/resources/jira/licenses/scriptrunnerForJira.license").text]
+
+jsmDep.stopAndRemoveDeployment()
+
 jsmDep.setupDeployment()

Environments/Terraform/variables.tf Environments/AWS/variables.tfEnvironments/Terraform/variables.tf renamed to Environments/AWS/variables.tf

@@ -6,7 +6,7 @@
 
     <groupId>com.eficode</groupId>
     <artifactId>devstack</artifactId>
-    <version>2.1.0-SNAPSHOT-groovy-${revision}</version>
+    <version>2.1.1-SNAPSHOT-groovy-${revision}</version>
     <packaging>jar</packaging>
 
     <name>DevStack - Parent pom</name>
@@ -176,7 +176,9 @@
 
                                     <exclude>com.google.code.gson:gson</exclude>
                                     <exclude>org.apache.httpcomponents</exclude>
-                                    <exclude>commons-*</exclude>
+
+                                    <!--exclude>commons-*</exclude--> <!--Seems to break JenkinsAndHarborDeployment.groovy:103, needs org/apache/commons/io/FileUtils-->
+
                                     <exclude>com.kohlschutter.junixsocket:junixsocket-core</exclude>
 
                                 </excludes>

README.md

@@ -31,6 +31,21 @@ class HarborDeployment implements Deployment {
         this.containers.find { it instanceof HarborManagerContainer } as HarborManagerContainer
     }
 
+
+    /**
+     * Returns the IP of the container listening on the private port 8080, ie the main frontend container IP
+     * @return
+     */
+    String getFrontendContainerIp() {
+
+        ContainerSummary harborNginxC = harborContainers.find {it.ports.privatePort.contains(8080)}
+
+        String harborNginxIp = harborNginxC?.networkSettings?.networks?.values()?.ipAddress?.first()
+
+        return harborNginxIp
+
+    }
+
     @Override
     boolean setupDeployment() {
 

examples/Basic JSM Setup.groovy

@@ -7,6 +7,18 @@ import com.eficode.devstack.deployment.Deployment
 import org.slf4j.Logger
 import org.slf4j.LoggerFactory
 
+/**
+ * Sets up a JSM deployment,
+ * creates a local H2 database,
+ * configures JSM license and admin account (admin/admin)
+ * installs optional marketplace apps and their licenses.
+ *
+ *
+ * Before running setupDeployment() make sure to setJiraLicense() and optionally populate setAppsToInstall (ex: [https:marketplace....:AAbbv1223cc...])
+ *
+ * Container name will be derived from the supplied jiraBaseUrl, but can be overridden before creation with: jsmH2Deployment.jsmContainer.containerName = "Something"
+ */
+
 class JsmH2Deployment implements Deployment{
 
     String friendlyName = "JIRA H2 Deployment"
@@ -18,6 +30,12 @@ class JsmH2Deployment implements Deployment{
 
     String jiraBaseUrl
 
+    /**
+     * Sets up a JSM Deployment
+     * @param jiraBaseUrl The full base url where JIRA should be reached (ex: http://jira.domain.se:8080)
+     * @param dockerHost An optional docker host, when not using local Docker Engine (ex: https://docker.domain.se:2376)
+     * @param dockerCertPath folder containing ca.pem, and the client cert: cert.pem, key.pem (ex: ~/.docker/")
+     */
     JsmH2Deployment(String jiraBaseUrl, String dockerHost = "", String dockerCertPath = "") {
         this.jiraBaseUrl = jiraBaseUrl
         this.jiraRest = new JiraInstanceManagerRest(jiraBaseUrl)