Introduction
Everything starts with NuGet. Octopus works with your applications as NuGet packages and distributes them to the appropriate server. PowerShell is equally important as it’s the glue that makes all customization for our deployment process possible. And whatever isn’t built into Octopus can be slapped onto Octopus with PowerShell as well. NancyFX and RavenDB are also crucial for Octopus Deploy’s success as well, but they’re behind the scenes. All of these components are leveraged in Octopus Deploy for everyone’s benefit and so far (to date), each design decision has paid off. Let’s take a look at the high-level overview of deploying your applications.
Keep in mind that you’re not obligated to use Visual Studio, but for the sake of this example, we’re going to assume Visual Studio and TFS. Regardless of the details, the key point to take away from this high-level workflow is that there are four main steps:
- Configuring your IDE
- Generating your NuGet package(s)
- Pushing your NuGet package(s) to the NuGet server
- Configuring your deployment process
The Octo.exe is a utility program which can be used for automating your deployments aka Continuous Deployment. It is not required to use the Octo.exe in order to deploy. Octo.exe has other utility functions that you can leverage but for our topic we’re concentrating on basic deployments in Octopus. We’ll cover the Octo.exe more in detail in another article, but you’ll see throughout Octopus Deploy, many features are optional and in this case the Octo.exe is omitted for our example.
Configuring Visual Studio
Let’s start with Visual Studio (version 2010 or higher) and a CI (continuous integration) server. For our example, I’ll focus on TFS as I’m familiar with it but keep in mind that Octopus is compatible with other solutions such as Team City, Atlassian Bamboo, Cruise Control .NET, etc. How is Octopus able to be compatible with this slew of vendor offerings? Simply put – there is no integration.
When I started investigating Octopus Deploy, I wondered why there was no direct client integration or CI component installation. After working with Octopus and NuGet, I realized that the beauty of using NuGet is that it’s unnecessary to have any direct integration between Octopus, Visual Studio and TFS. Octopus doesn’t care what NuGet server you use nor does it care how you generate your NuGet packages of your solution. You have the responsibility in creating your project in a NuGet package but in return you have the choice of how you do it. Since any project can have any number of projects or configurations, this flexibility is an advantage.
For those using TFS, the fastest way to get started is to use the OctoPack. Within the NuGet package manager, simply search for the OctoPack and install it only to the projects that need to be transported via NuGet to the appropriate server. Note that the OctoPack doesn’t really add any dlls within your solution. The OctoPack dll (Octo.Tasks) is within your packages folder and is called after MSBuild is finished compiling your application.
Now that the OctoPack is installed for your project, we need to create nuspec files for each project that you want to create NuGet packages. Nuspec files allow you to add metadata to your NuGet package and include or exclude files that the NuGet pack command may attach or omit. Creating a nuspec file is a very simple process. Make sure you have the nuget.exe downloaded.
Using the DOS command prompt, go to the directory of your project where the *.csproj or *.vbproj is. Executing the command “<path>\nuget.exe spec <yourprojectname>.csproj”. This will create a .nuspec file that you need to include in your project.
Once the nuspec file is created, you need to add it to your project and edit the default values. You may notice the version number in the nuspec file. Versioning is a whole topic in and of itself, but for now to make things simple – within your project AssemblyInfo.cs file, chanage the AssemblyVersion value from “1.0.0.0” to “1.0.*”.
This will dynamically generate a new number for each build and change the version number for your NuGet packages as well. The great thing about this versioning technique is that it’s simple and will always increment the value over time as the build number is really a date reference and the revision is a relative time on the day of the build. This makes sorting easy and if you use the Octo.exe, you can configure it to use the latest version of your NuGet package which is perfect for continuous deployments. You can read more about versioning in my deep dive post on Versioning in Octopus Deploy (Part I).
Generating your NuGet package(s)
With the OctoPack in place and nuspec file at the ready, we can now get onto generating NuGet packages. How you choose to generate your application packages is (again) up to you. For the sake of our example, I’m assuming you’re using TFS. For TFS, your build template is where you pass parameters to the OctoPack. Look for the MSBuild Arguments field within the Process tab. This field may be in different locations (within the Process tab) for different templates as templates vary between versions of TFS. The example below is a build template from my TFS Online account.
The OctoPack takes three minimum parameters:
/p:RunOctoPack=true
/p:OctoPackPublishPackageToHttp=<http:/p:OctoPackPublishApiKey=<your API Key>
That’s it. There are more parameter options available for the OctoPack, but these three parameters are the bare minimum and instruct the OctoPack to run the NuGet pack command which will build NuGet packages and then upload said packages to the destination NuGet server.
Note: The OctoPack is open source! Over time, many changes and features have been added from contributors. If you really need to see what’s going on, see the source code for yourself!
You should check to see your NuGet package on the NuGet server by browsing the appropriate URL. Each NuGet server may have a different URL path or scheme to your specific feed, but most if not all have some way of viewing available packages.
As you can see, the OctoPack is very easy to use but if you’re more inclined to use .proj files & XAML or PowerShell scripts, that’s fine too. I can cover that topic another time, but as far as Octopus Deploy is concerned, it has no involvement on how your project is compiled and packaged up. Simply getting the NuGet package to the server is a key step; Octopus need not know about it unless you want to do continuous deployment and that requires the Octo.exe. This lack of integration with Visual Studio and/or TFS seems like a burden, but in reality it’s a big advantage as it opens up creative options rather than enforcing a rigid and stifling process. Not everyone uses TFS, nor does every project fit the same mold so while the process seems cumbersome (and it can be), it’s also very adaptable to numerous situations.
Note: The current road map (as of this writing) for Octopus suggests more integration with CI solutions such as Bamboo, Jenkins, TFS and TeamCity. I haven’t used TeamCity so I can’t speak to the current plugin that’s available and I don’t have much information on the other solutions so how “integrated” these plugin offerings will be difficult to determine before their release.
Pushing your NuGet package(s) to the NuGet server
Once your solution is able to compile, build nuget packages of your project and upload (also referred to as “pushing” a package in NuGet lingo) to a NuGet server, Octopus Deploy steps in to deal with the remainder. That remainder being moving your application and all it’s glorious bits to whatever servers you want in your environments.
The NuGet server, like Visual Studio, isn’t really integrated into Octopus. There’s no client or component to install on the NuGet server. You simply register a NuGet server with a URL feed. If authentication is required, you can enter a username/password.
Octopus has it’s own internal NuGet server if you choose to store your packages directly on the server itself. Again, like we’ve seen with other aspects within Octopus Deploy, it’s not mandatory to use the internal NuGet server. You can use any NuGet server that the Octopus server has access to whether internally within your own organization (on-premise) or a service on the web such as MyGet.org. Some commercial NuGet servers such as ProGet, offer NTLM/Active Directory based authentication with NuGet feeds and you can use those as well with the username and password.
While this loose coupling with Octopus Deploy and the NuGet server appears like a strange choice, it’s light-handed approach is a huge benefit as you can leverage this weak bond in creative ways that aren’t apparent at first glance. For example, backing up, secondary sites such as MyGet.org or an Azure VM. This may require more PowerShell scripting but the configuration is not difficult to setup and automate.
Configuring your deployment process
Now to the main course of our meal: the Deployment Process. The heart of the deployment process is the Process tab within your project.
You can add any number of steps to your Deployment Process. In the new 2.4 version, there are downloadable step templates available at http://library.octopusdeploy.com. We’ll circle back to step templates in another article.
As part of the Deployment process customization, you can choose any of the built-in templates. All offer some degree of flexibility. The Deploy NuGet package step type offers options regarding installation path, IIS Server configuration options, AppPool configurations, etc.
Now, you may have noticed that within each project in Octopus, there’s one Deployment Process tab. Hmmm.. only one? What the..? Why? What happened to options n’ stuff? Why just one? Answer: you only need one.
You might say “But I have certain things that can only happen in specific environments!” Don’t sweat it. Each step of your project has a specific condition of what environments to run under. This applies to all steps within Octopus Deploy’s deployment process. Hence, some steps may only apply for Dev and Staging. Some other steps may be exclusive for Production. It’s all up to you.
Now that your NuGet package has been made, stored within the NuGet server and your deployment process is ready to go, it’s time to manually create a release and do a deployment. For this article, I’m not going to cover variables. That I’ll touch up in another article as that subject (like numerous others) is quite a handful to explain within this discussion.
Note: The following steps I give are for manually creating a new release and deployment. You can automate all of these steps with the Octo.exe.
Within every page of your project, in the upper right-hand corner is a green button labeled “Create Release”. Note that all releases themselves are versioned so you can do multiple deployments of the same release. This helps keep some logical organization for all your deployments. Additionally, keep in mind that for every release (not deployment), Octopus takes a snapshot of all the variables and steps, settings and values. Just because you update some information does not mean that the changes will take effect. Snapshots are great for being able to run a previous release with all the variable values and settings the same as it was initially saved. For every change you make and save to your deployment process, you need to create a new release to get the latest changes.
Clicking the “Create Release” will take you to a screen to select specific versions of the NuGet packages that have been requested for download within your process tab. Here, you can easily navigate which NuGet package you want from the server as you can select the latest package, the previous deployed package or search for a specific package.
Clicking the magnifying glass will query the NuGet server that the deployment process step is configured to use and display a list of NuGet packages that have been uploaded.
Once you’ve saved the release, you’re ready to deploy. Clicking the “Deploy Release” button after you’ve saved it will bring you to another screen asking what environment you want to deploy to. Whatever environments you’ve configured your project, those should be visible within the drop-down menu for you to select.
Note: All deployments (by default) are in parallel across servers. You can tell Octopus how many servers to deploy to at a time by setting a Rolling Deployment number. You can think of the number supplied for Rolling Deployments as a batch size number of servers to deploy to. Now each deployment process within the server is serial (in version 2.6, steps can be run in parallel). There are plans in the works on the road map to have processes on servers in parallel as well.
As your deployment is running you can view the “Task Log” tab and watch the deployment in real-time. This information is preserved with the release so you don’t have to save anything. Should you delete the release, you’ll obviously lose the task log associated.
This all-in-one Task Log view of the entire deployment is a wonderful feature within Octopus Deploy. You don’t have to configure anything. This is all, by default and whatever PowerShell scripts you choose to manually add to your deployment process will also be recorded as well. This Task Log view shows everything happening across all servers involved on one page in an easy, logical format.
No doubt by now you can see why I praise Octopus Deploy; it’s flexibility and unique approach make it versatile for a wide variety of projects and configurations. I hope you’ve enjoyed the Octopus Deploy Series so far. I’ll have one article coming later this week to wrap things up with our high-level coverage for Octopus Deploy. Afterwards I’ll begin a new “deep dive” series to really understand how to wield specific features within Octopus Deploy for your projects.
