If you recall, the build process is composed of three stages: input, transformation, and output. Once you have a consistent build going, you should have a pretty good idea on how AnthillPro tackles the first two phases of the build process to generate output and deliver the artifacts to Codestation (the artifact management system). At this point, you can set up a deployment process in AnthillPro that will enable you to move the artifacts (or the output of the build process) to a different location. For example, the deployment process is typically used to move the artifacts so they can be: tested in a different environment; delivered to specialized hardware; subjected to exhaustive testing; etc. Once the deployment process is set up, AnthillPro will keep track of what was deployed; when the deployment took place; where the artifacts ended up; who ran the deployment; as well as the build that generated the artifacts.
Setting up a deployment process is similar to setting up the build process: you will need to configure a workflow and a job. However, since a deployment is a secondary process (called a non-originating workflow in AnthillPro) that runs after a build has completed, you will need to configure what is called a non-originating workflow. In other words, a non-originating workflow is configured for any process you want to subject an existing build to. So a deployment is one type of secondary process responsible for moving the artifacts around.
To achieve a successful deployment, you will need to:
Already have at least one successful build in AnthillPro. It's a good idea to get a consistent build process in place before dealing with deploying artifacts. If you have not successfully built a project in AnthillPro, see Setting Up a Build.
Create a deployment workflow. Creation is similar to that of a build workflow, but is simpler to configure. A deployment workflow (implemented as a non-originating workflow) inherits many of its properties from the project's build workflow.
Create a deployment job. Similar to creating a build job, the deployment job includes steps that move the artifacts to a different location. However, you will not use the Job Wizard to create the deployment job.
Run a deployment. Once configuration is done, you are ready to run the deployment.
Remember that in AnthillPro the originating workflow is used for setting up a build process, and that the non-originating workflow is set up to run a secondary process on a completed build. So when setting up a deployment process, you will need to configure a non-originating workflow.
To create a deployment workflow:
Go to Administration and select the Add Workflow icon of the project you created in the Setting Up a Build section.
Next, check Non-originating workflow and click Select on the New Workflow page. In AnthillPro, it is the non-originating workflow that is used to run a deployment.
Workflow configuration:
Name. Give a name for this workflow. Typically, the name should reflect the type of work to be performed when this workflow runs. For example, "Deploy."
Description (optional). Give a description of this workflow. The description allows you to convey more information about the workflow.
Environment. In AnthillPro, the environment is the location where the deployment takes place. Select the environment you would like this deploy workflow to run in. For example, if your build took place in the Build-Farm and you want to deploy it to the QA environment, select the QA environment from the drop-down. If you recall, AnthillPro ships with 3 default environments:
Build-Farm. Generally, this is the environment that all builds take place within, and is most closely associated with Development. This is the environment you want your builds to run in.
QA. This environment is provided for performing quality assurance testing. Most often, when you are sending a build to testing, you want that workflow to run in this environment. This is the environment you want to use when running a secondary process (i.e., non-originating workflow) that deploys the artifacts to your testing environment.
Production. This environment is typically used to deploy your builds once they are ready for production.
Notification Scheme. Select the Default Notification scheme. By default, AnthillPro will send an e-mail notification to AnthillPro users. For now, don't worry if you aren't getting any e-mails. Notifications are covered in more detail in the Basic Notifications section. If you have not already done so, you may want to configure the notifications for this and other workflows.
Priority. Use the default Normal Priority. Once you have a lot of projects going in AnthillPro, you may need to prioritize which workflows run first.
Click Save.
The job is composed of a series of distinct actions the server must perform (called "steps" in AnthillPro) to successfully run a deployment. For any job you create, the steps (actions) are executed by the server one at a time, in a specific order. When configuring the deployment process, you will need to manually create a job.
Every deployment job must:
Set and clean the working directory. To ensure that a clean deployment is performed every time, this step will allow AnthillPro to run a clean-up at the beginning of the job.
Resolve the artifacts. This step retrieves artifacts generated by the originating workflow and deposit them in a specified directory.
Deploy the content. This step uses a builder to run a deploy script. For example, if you use Ant, you would select it from the Builders menu and then configure the script.
To configure the deployment job:
Go to Administration and select the Add Job icon of the project you created in the Setting Up a Build section.
Check No and click Select. Do not use the Job Wizard.
Set up job:
Name. Give a name for this job. Typically, the name should reflect the type of work to be performed by the job. For example, "Deploy."
Description (optional). Give a description of this job. The description allows you to convey more information about what this job does, etc.
Click Set.
On the Job Configuration page, click the Create Step button.
Next, add a Set Working Directory step. Expand the Miscellaneous folder, select Set Working Directory, and then click Select.
Working Directory Script. Select the Default Project Working Directory script form the drop-down. For most projects, the default script will be sufficient.
Clean Working Directory. Check this box. This will erase files and subdirectories in the Working Directory when this step runs, thus ensuring that a clean deployment will take place.
If you did not use a default working directory script above, you will need to verify that the working directory is not set to something like
C:orC:\because the entire contents of the C drive will be permanently removed when the Clean Working Directory step is run.Show Additional Options. These are advanced settings. For a simple deployment, you can skip these settings.
Click Save.
Add the Resolve My Artifacts step. This step will retrieve the artifacts generated by the build you configured earlier. Click the Insert After icon (under the Actions Menu) of the Set Working Directory step, expand the Artifacts folder, select Resolve My Artifacts, and click Select.
Name. Giving a simple name of "Resolve Artifacts" is sufficient.
Artifact Set. Select the artifact set you configured in the Capture and Deliver Build Artifacts section during basic build job creation.
Directory. Specify what directory you want to artifacts delivered to. This is relative to the working directory. For example, if this workflow's working directory is
C:\myProject\deployWorkflow\, and you specify "artifacts" here, the artifacts will be delivered toC:\myProject\deployWorkflow\artifacts.Transfer Only Changed Files. Check here if you want AnthillPro to transfer only changed files based on checksums. For configuring your first deployment, this optional feature is unnecessary. See also Server Security.
If you are using the Transfer Only Changed Files option for your Resolve Artifact step, you must activate the Digest Algorithm server setting. Once set, AnthillPro will use either a SHA or MD cryptographic hash function to protect the build and deployment artifacts. AnthillPro will then use the generated file checksums for the resolve, and skip the Codestation caching on the agent. Use of this feature can result in faster deployments that use less bandwidth -- especially if the deployment target is a remote server and only a small proportion of the files will change between deployments. Include Patterns. List the artifacts to be resolved. If you want to include all the artifacts, simply leave this field blank, (or use the wild card
**/*). You can refer to the Capture and Deliver Build Artifacts section for additional information on using include patterns.Exclude Patterns. Give the patterns of the artifacts that should be skipped from the include. This field is set in the same way as the Include Artifacts field, only you are telling AnthillPro what NOT to include. If you leave this filed blank, AnthillPro will exclude no files. You can refer to the Capture and Deliver Build Artifacts section for additional information on using exclude patterns.
Show Additional Options. These are advanced settings. For a simple deployment, you can skip these settings.
Click Save.
If you configured more than one artifact set for the build, add the Resolve and step for each set. For example, if your build published different artifacts into the APP, DB, and WEB artifact sets, then you will need three resolve steps -- one for each artifact set.
Add a Deploy Artifacts step. This step will deliver the resolved artifacts to the target destination. To do this, you will have to configure a Builder step that will run your deploy script. Most users simply use the same tool for builds and deployments. To configure this step:
Click the Insert After icon (under the Actions Menu) of the Resolve My Artifacts step, and then expand the Builders folder.
You will need to select one of the following and then click Select:
Follow the instructions given for the builder you are using to run your deploy script.
Note that when configuring the step, give it a name such as "Deploy Artifacts" so that it can be differentiated from other builder steps. Also, if you see a Script Content tab, that means you can write your script directly in the AnthillPro UI.
When you have added the Deploy Artifacts (Builder) step, see Complete Deployment Configuration.
Once the deployment job has been created, it needs to be added to the deployment workflow you created earlier. This ties the deployment process together, and allows AnthillPro to send the artifacts to the desired location.
Go to the workflow you created in the Create a Deployment Workflow section.
Select the Definition tab. The Workflow Definition is used to define the execution of the Job used by this workflow. A Workflow Definition has a single starting point and a single end point.
Use the default Embedded Definition. Click Select.
Click the Start button and select Insert Job After. Configure:
Job. Select the job you created in the Create a Deployment Job section. The job will appear in the drop-down menu under "Project Jobs."
Pre-Condition. Select Always as the pre-condition for this job. That way, the job will always run.
Agent Filter. Select at least one agent from the Fixed Agent Selection list. Highlight the agent name in the list and click the plus sign (it will suffice to select one agent).
Once you are more familiar with AnthillPro, you can use agent filtering to determine which agent(s) a job can run on, including using scripted agent selection. For more on scripted agent selection scripts, see the scripting documentation in the Development Kit Bundle at tools > anthill3-dev-kit.zip. Working Directory. Select Source Config's Work Directory from the menu. This will ensure that the build takes place in the correct location.
Lock for Workflow. Use the default value of No. Locking is an advanced feature.
Click Insert Job.
Now that you have configured the deployment process, the next step is to run the deployment. See Run a Deployment.
Running a manual deployment is a simple push-button process performed on the Dashboard. Once you select a build number (called Build Life in AnthillPro), the build's Main page gives you an option to run a secondary process (i.e., run the deployment workflow you just set up).
To run your deployment:
Go to the Dashboard and select the build workflow of your project.
On the workflow's Main page, Select the Build Life number of one of your builds.
On the Build Life page, click the Run Secondary Process button.
Next, run the secondary process (i.e., deployment workflow):
Workflow. Unless you have configured multiple non-originating workflows for this project, AnthillPro will automatically populate this field.
If you are given a drop-down, select the workflow you created in the Create a Deployment Workflow section and then click Next.
Environment. AnthillPro will automatically populate this field for you if you only check one environment while configuring the deployment workflow.
If you are given an option, select the environment you want this workflow to run in. For example, if you want it to run in a QA environment, select it here.
Delay. You can leave this blank. That way, the deployment will run immediately.
Advanced: To delay a deployment, check the box and then give the date and time you wish this workflow to run. This is a one-time event, not to be confused with a scheduled deployment. Once you configure a delayed deployment, it appears on the Current Activity tab under the Delayed Builds (or Planned Workflow Execution in some versions of AnthillPro) menu. There, you can delete the request for a delayed deployment. Click Run.
Once the deployment has been started, you can check the status on the Build Life page (the page you were returned to). Refresh the page to update status. When the deployment is completed, it will be listed on the Build Life page, along with the build (originating workflow).
It's worth noting here that the same deployment process can be run on any build (Build Life). For example, if you have 3 successful builds, you can run the same deployment process on each Build Life.
Also, there is no limit to how many time a secondary process can be run on a build (Build Life). So, you can run the same deployment as many times as you want for any given build.
AnthillPro will always keep track of which deployment belongs to which Build Life (build), and how many times the deployment was run on each particular build.
Once you have your basic deployment workflow running, you may want to automate the deployment instead of having to click the deploy button every time. There are a number of ways to do this, but following are the two most common scenarios.
Add a "deploy" job to your build. If you want to practice continuous deployment, appending your build job with a "deploy" job -- which contains a single step: Run Another Workflow -- will deploy the content every time a build is successful. It's worth noting that this option can become resource intensive if used on every project. To auto deploy upon build completion:
Ensure that your deployment workflow successfully runs. If it you have not created one yet, go to the beginning of this section and create one. You will also need to ensure that your build workflow is delivering the artifacts to AnthillPro's artifact management system.
Go to Administration and then select the Project that you want to deploy.
Click on the Add Job icon. Do not use the Job Wizard.
Name the job ... something like "Send to [Environment]" and give a description. It's a good idea to give this job a different name than the job used by the actual deploy workflow.
Insert a single step in the job: Run Another Workflow. This step is contained in the Miscellaneous folder. Configure the step:
Name the step.
Description. Give an optional description.
Workflow. Select the deploy workflow you want to run.
Environment. Select the environment you want this workflow to run in. This will typically be the environment that your deploy workflow runs in.
Wait for Workflow. Check the box if you want AnthillPro to wait until the workflow completes before running the deploy workflow. For this scenario, you should be able to skip this option. (If any of them fails, then this step will be failed) Caution: While waiting, this workflow will still hold any Lockable Resource, and this job will count as running on an agent.
Pass Properties. You have the option of passing properties from the build workflow to the deploy workflow. Under this scenario, you can select Do Not Pass. However, if you need to pass all the properties, select Pass All, or if you need to pass only matching properties -- properties that are set on both workflows -- use that option.
Show Additional Options (optional; advanced). Select the Show Additional Options link to configure more options.
Is Active. Select No to temporarily deactivate the step without deleting it; otherwise select Yes.
Pre-Condition Script. From the drop down menu, select the condition which must be met for the step to continue. Before editing an existing script or creating a new one, see Step Pre-Condition Scripts.
Ignore Failures. Select Yes if this step should not effect the determination for step continuation or the status determination of the job.
PostProcessingScript. Select a script for determining when commands should count as fail or succeed. See Post Processing Scripts.
Timeout. Enter the time in minutes after the start of the step when AnthillPro will consider the step as timed out and abort it.
Click Save.
Next, still on the Administration page, go to the originating (build) workflow and click the Definition tab.
Click on the Stop icon (at the bottom) and select Insert Job Before. If you have more than one job in the definition, be sure you add the deploy job to the end. Then set the job configuration:
Pre-Condition. Here, if you select the default option "All Ancestor Jobs Success or Not Needed" then this job will run (i.e., kick off the deployment) when the build job is successful. This option will only kick of a deployment upon build completion. The "not needed" portion comes into play if you have multiple jobs in the build definition but not all of them run all the time.
Agent Filter. Here, if you select the same options as you did for your build job everything should work fine. Since the job is simply calling another workflow, nothing much is going on here that requires a specific agent.
Working Directory. Selecting Parent Job's Working Directory is the simplest option. As with the Agent Filter, nothing much is going on here to be concerned about.
Lock for Workflow. Typically, selecting No will suffice. Unless you start having locking issues or have multiple jobs attempting to run the same working directory at the same time, it is unnecessary to lock for the workflow.
Save the your work.
The next time your project builds, it will automatically kick of the deploy workflow.
Add a scheduled trigger to your deploy workflow. This method is most commonly used when you want to run a deployment on a regular schedule (e.g., deploy the most recent build to a testing environment during down time).
To do this, go to the deploy workflow, select the trigger tab and then choose Scheduled Trigger. A basic interval schedule can be used if you are deploying a nightly build, or if you have a more complex scenario, you can use a cron schdule. See Workflow Triggers and Scheduled Builds for more.
Integrating with other tools. Now that you have a successful build-and-deploy process going, you can add further automation to your processes by using AnthillPro's robust integrations. See Integrating Other Tools.
Setting up dependencies between projects. Use AnthillPro's unique dependency management system that lets you set up relationships and provide visibility into your dependency structures. See Dependency Management.