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" gear link in the top menu bar, then "Create New Application". You'll see a screen similar to this:
This page offers a variety to create a new application including: a standard application with some skeleton deployment plans, an empty application with no configuration at all, cloning an existing application, wizards that set up skeleton applications for various scenarios including deploying from Jenkins, TeamCity, or TFS, and more. In this example, we'll use the Standard Application template at the top of the screen.
Once we select Standard Application, I'll name the application "Accounts" and 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. Using the Standard Application template, 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
To add a Source Control Provider, visit "Admin" > Extensibility > "Source Control Providers", select "Create New Source Control Provider" and choose Subversion from the list. Because this functionality is available in an extension that may not be installed, you may be prompted to download and install the extension automatically. Once you have done this, fill in the necessary connection information (URL: http://inedo-test-project.googlecode.com/svn/trunk) as shown in the image below. For other extensions, you can find per-extension information on the Integration page.
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 Standard Application template for the application provided a skeleton plan that can be utilized for most builds and deployments. 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. These skeleton groups can be edited or deleted as necessary for your own applications.
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" tag, 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 "artifacts" tag 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 users 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 "artifacts" tag, 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 under the "files" tag after the 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.
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!