Getting a Simple Application Into BuildMaster
This set of tutorials is intended to show you how to build and deploy a simple real-world application with BuildMaster. This tutorial will cover the basics of creating an application within the tool, integrating with your source control system, and creating and deploying a build.
If you don't already have BuildMaster, you can download it for free. The installation process should only take a few minutes. For more details, see the Installing BuildMaster subsection of the documentation.
When you access BuildMaster for the first time and log-in, you'll be prompted to "Create a Build" of BitChecker, an example application we've included as a general overview. It is strongly recommended that you run it, read the copy that is included, and take a look at how its deployment plans are setup – or at the very least come back to them after you've completed the rest of this tutorial.
Creating Your Own Application
First, you may be wondering what is meant by the term application. Basically, an "application" within BuildMaster is the totality of technology, code, platforms, etc., that comprise and deliver the business functionality for a particular task. Applications may be large (requiring a floor of programmers and analysts to maintain) or small (a single executable that infrequently changes). For this example, we'll use an ASP.NET website.
Now that the term has been defined, we'll create our own application. Click the "Admin" link in the top menu bar, then "Create New Application". You'll see a screen similar to this:
For this example, I'll name the application "Accounts", and create one deployable named "Website". I can leave the remaining options at their defaults. Once I click "Create Application", I'll be taken to the application overview page which is essentially empty because there have been no deployments yet. With the "Create Initial Workflows and Set-up Release", most of the initial application configuration is handled for you by default – which means we can begin creating a deployment plan right away with these default environments. At this point however, I know I'm going to need source control integration before the plan is created, so I will integrate with the project's SCM tool Subversion.
Creating a Source Control Provider
Before we can add the provider, we need to install its containing extension since almost all external tool connectivity and integration comes from BuildMaster's extensibility engine. The project in this example is stored in Subversion, but any SCM will work as long as you choose the appropriate extension from the Extension Gallery. The most common extensions containing source control providers are TFS, SVN, and Git. To install an extension, head to "Admin" > Extensibility > "Add/Configure BuildMaster Extensions" and choose the extension(s) you need then click "Install Selected Extensions". Make sure to click "Install" on the confirmation page.
Once you've installed the extension, you can add the source control provider. If you visit "Admin" > Applications > "Configure Source Control Integration" you should see the extension's provider in the list once you click "Create New Source Control Provider". Click on it, and fill in the necessary connection information. You can find per-extension information in the Extension Gallery on inedo.com.
For this example, I'll create a provider for Subversion which in my case only requires a URL to the project which you may also use if you'd like for testing purposes (http://inedo-test-project.googlecode.com/svn/trunk):
Configure a Deployment Plan
At a high level, BuildMaster basically works by promoting builds through environments in the order specified by a workflow until they are successfully promoted to the final environment where both the build and release become deployed. When the build is promoted to an environment, its deployment plan steps (known as actions) will be executed in order.
With the source control integration in place, we can begin creating a deployment plan for the first environment (Integration by default). Select the "Accounts" application from the application dropdown to return to the application overview page and select "Deployment Plans" from the menu. The "Create Initial Workflows and Set-up Release" option for the application provided a skeleton plan that can be utilized for most deploys. Note that some steps may not be relevant in your particular case, such as if you're deploying an ASP.NET (such as the Accounts one), HTML or PHP website, it won't need a "Build Website" step.
For our first step we'll click the Add Action button for the first action group:
This will bring up a list of categorized actions that you can pick from. Our first step would be to get the latest source code from Subversion, so I choose the "Get Latest" action under the "Source Control" category, then select the Subversion provider we created earlier. For this action, I'll leave the "Target Directory" (i.e. where the files will be pulled to) as default. If I click the […] button next to the Source Path, I'll get to choose which files I want to get, in this case the "Accounts" subdirectory:
Double-clicking on the Accounts directory will populate the source path, then we can Save the action. If we were to click "Builds" > "Create New Build" right now, a build would be created that is automatically promoted to Integration and only the "Get Latest" action would be executed, which would not be terribly useful for deployment! We still need some more actions in order to deploy this site.
The next one we will add is a "Create Build Artifact" action in the "BuildMaster" category to the Build Website group (technically it's not being built, but that's OK we can always edit the title of the group). This action would essentially create a zip file build artifact and associate it with the build, making it easily accessible for download by those with privileges and also easy to deploy to future environments. We don't need to specify any directories in this case because we're using the default, which is the same place the source code from the previous action will be.
Our next action for this integration environment will be a "Deploy Build Artifact" action in the "BuildMaster" category, which basically takes the zipped artifact we just created and puts it out on the file system somewhere on the specified server. I will add this action to the Deploy Website group with the "Target Directory" of "C:\Websites\Accounts" (because that's where the site is served from). After deleting the unnecessary Stop and Start Application groups, the plan now looks like this:
For our final action, I know that the Accounts application relies on a file under the bin directory named "version.info" (which isn't in source control) with the contents being the current version number of the application in order to display it on the website. In that case, I'll add a "Create File" action after Get Latest action, specifying %RELNO%.%BLDNO% as the text, which BuildMaster will automatically replace with the actual release number and build number when it comes time to execute the build:
That leaves the plan looking like this:
And that's all there is to creating this plan! I now have a working plan for my Integration environment that will pull code from SVN and place it into the home directory of its website.
Creating a Build
With the deployment plan in place, we can run a build by choosing "Builds" > "Create New Build" in the main menu. You'll notice on the create build page that it allows you to select a release you wish to create a build for and shows you the deployables that are included with that release. You may have noticed in the auto-generated skeleton plans the lines "[execute for the Website deployable]", which means that particular action group will only execute if the Website deployable is included in the selected release. This helps when you have multiple components as part of an entire application that aren't always deployed with a new release of that application. For a better distinction between applications and deployables, see our Knowledge Base article on the subject: The Difference Between Deployables and Applications
Since we clearly want that deployable to be deployed (as it's the only one), we'll go ahead and click the "Create New Build" button and watch the deployment happen live:
Once the build completes, we're redirected to the build overview page where we can see many details about this build including:
- The build status
- Any variables associated with the build
- The current promotion status of the build
- Any approvals required or received for the build
- Build Artifacts
- Any notes associated with the build
Navigating to the C:\Websites\Accounts directory shows the files there, and browsing to the already configured IIS website shows that it's up and running:
You may notice that the web.config value displays "Local Machine" (because that's what in the source controlled version of the web.config file), which introduces a whole new subsystem of BuildMaster: Configuration Files – where you can have BuildMaster manage the file and its particular instances across the environments and deploy the correct one automatically when you create or promote a build. You can visit the configuration files tutorial for more information on how to do this.
While this example is just the tip of the iceberg, hopefully this lets you see the power that BuildMaster is capable of. There are an unlimited number of actions you can add at any point in your plans including executing command line utilities, running Powershell, batch, or shell scripts, or any of the easy-to-use built-in actions such as unit testing, manual actions that require human intervention, creating a file diff from previous versions, or advanced file transfers with masking. If you're feeling really adventurous, you can even write your own!