DocsPipelines for ApplicationsDeployment tutorials
IIS.net application: Deploy on Windows

IIS .net application: Deploy on Windows

Sections


In this tutorial I will explore deploying a .NET application to a Windows IIS Server using Pipelines.

Before you begin the tutorial you must:

  • Install the Pipelines CLI on the development system. Installing the CLI
  • Ensure git is installed on the development system. Download Git
  • Have a destination server available to deploy software to.
  • Install the Pipelines agent on the destination server. Installing the agent

This tutorial assumes you have experience working with:

This tutorial will use the BlogEngine.NET code available here.

Note: This has been tested with Windows Server 2012.

Preparing the Application

The following instructions are all executed from the same command (cmd) shell prompt.

  1. To get started create a directory for building your application.

    ~~~ $ mkdir WinIISBlog ~~~

  2. Change to the directory just created.

    ~~~ $ cd WinIISBlog ~~~

  3. Download the BlogEngine.NET (Web) code into this new directory. You can get the code here.

    Now you will need to create the deploy instructions for Pipelines. This is done with the distelli-manifest.yml file.

  4. In the WinIISBlog directory create the file distelli-manifest.yml.
  5. Copy and Paste the following into the distelli-manifest.yml file.
<username>/WinIISBlog:
  PkgInclude:
    - '*.zip'
  Env:
    # Define the TCP port you want the IIS application to listen on
    - PORT: enter_value_here
    # Define the Name for the IIS application
    - SITE: enter_sitename_here
    # Define the Directory full path where the IIS application should reside
    - APPDIR: enter_directory_here
  PreInstall:
    - echo "Begin PreInstall"
    - echo "Install any IIS Prerequisites"
    - echo "---"
    - echo "Removing existing IIS Site"
    - echo "---"
    - echo "Create Application Directory"
    - echo "---"
    - echo "Creating IIS Site"
    - echo "---"
    - echo "Done PreInstall"
  PostInstall:
    - echo "Begin PostInstall"
    - echo "Unzip BlogEngine.NET to Application Directory"
    - echo "---"
    - echo "Set Directory Attributes"
    - echo "---"
    - echo "Done PostInstall"
  Start:
    - echo "Begin Start"
    - echo "Start IIS Site"
    - echo "---"
    - echo "Open Firewall"
    - echo "---"
    - echo "Done Start"

The above is a skeleton manifest file. The following will discuss what needs to be added to the various manifest sections to successfully deploy this IIS application.

Username

First step is to change the <username> field to your Pipelines user name. If you need assistance in finding your user name see Finding Your Pipelines Username. For example if your user name is johndoe your manifest first line would look like this:

johndoe/WinIISBlog:

PkgInclude Section

This section defines which files make up your application that need to be deployed to the destination Windows Server. In this scenario we need only the BlogEngine.zip file. This *.zip syntax will keep all .zip files which will work.

  PkgInclude:
    - '*.zip'

Env Section

In this section, you set environment variables that will be used in the balance of the manifest file.

  Env:
    # Define the TCP port you want the IIS application to listen on
    - PORT: enter_value_here
    # Define the Name for the IIS application
    - SITE: enter_sitename_here
    # Define the Directory full path where the IIS application should reside
    - APPDIR: enter_directory_here

Change the values as appropriate for your environment. Here are some notes and suggestions:

Port: "8085"

Enter a TCP Port number to listen to for this application. Don’t use an existing port that is being listened to. This parameter will be used when adding the Site to IIS and setting up firewall rules.

SITE: BlogEngine

Enter a name for the IIS Site. This parameter will be used when adding the Site to IIS.

APPDIR: c:\blog

Enter the full path to the directory where the application will be served from. This directory should not already exist. This is the directory where the BlogEngine application will be unzipped to and run from. Here is the text with suggestions so you can copy/paste:

  Env:
    # Define the TCP port you want the IIS application to listen on
    - PORT: "8085"
    # Define the Name for the IIS application
    - SITE: BlogEngine
    # Define the Directory full path where the IIS application should reside
    - APPDIR: c:\blog

PreInstall - Install any IIS Prerequisites

In my scenario, the Windows 2012 server did not have IIS, ASP, and .NET provisioned, so I chose to install these dependencies on deploy, which I was able to accomplish with the following commands:

dism /enable-feature /online /featurename:IIS-WebServer /all
dism /enable-feature /online /featureName:IIS-ASP /all
dism /enable-feature /online /featureName:IIS-ASPNET /all
dism /enable-feature /online /featureName:IIS-ASPNET45 /all

My manifest PreInstall “Install any IIS Prerequisites” section looks like this:

  PreInstall:
    - echo "Begin PreInstall"
    - echo "Install any IIS Prerequisites"
    - dism /enable-feature /online /featurename:IIS-WebServer /all
    - dism /enable-feature /online /featureName:IIS-ASP /all
    - dism /enable-feature /online /featureName:IIS-ASPNET /all
    - dism /enable-feature /online /featureName:IIS-ASPNET45 /all
    - echo "---"

Note: Your system may require installation of other prerequisites.

PreInstall - Removing Existing IIS Site

The syntax to create a site with IIS is:

%windir%\system32\inetsrv\appcmd add site

The above command will fail and set %ERRORLEVEL% if the site already exists, which will cause the deploy to fail, so providing some code to check for an existing site and remove it first will be helpful.

    - echo "Removing existing IIS Site"
    - for /F "tokens=*" %%a in ('%windir%\system32\inetsrv\appcmd list site %SITE%') do set RESPONSE=%%a
    - if "%RESPONSE%"=="" (
    -   echo "%SITE% doesn't exist"
    - ) else (
    -   echo "%SITE% does exist. Deleting"
    -   (%windir%\system32\inetsrv\appcmd delete site %SITE%)
    - )
    - echo "---"

This code will check IIS to see if %SITE% exists. (Remember %SITE% is the environment variable you set in the Env: section above.) If it does exist, it will be deleted.

PreInstall - Create Application Directory

In this section you will need to create the application directory. Of note, if you try to do a “mkdir” for a directory that already exists, mkdir will set %ERRORLEVEL% which will cause the Pipelines deploy to fail. You can use “IF not exist” syntax to check for the directory before creating. Realize that if the directory is not empty, you may encounter unknown issues.

Approach One

    - echo "Create Application Directory"
    - IF not exist %APPDIR% (mkdir %APPDIR%)
    - echo "---"

Another approach may be to “quietly” remove any existing directory and all its contents before recreating. Note, “rmdir” does not set %ERRORLEVEL% if the directory doesn’t exist so it’s safe.

Approach Two

    - echo "Create Application Directory"
    - rmdir /S/Q %APPDIR%
    - mkdir %APPDIR%
    - echo "---"

Realize the above depicts two different approaches and they shouldn’t be used together. I prefer the latter as it ensures the directory is empty.

PreInstall - Creating IIS Site

Ultimately , after ensuring the site doesn’t exist and the application directory is empty, the IIS site will need to be created with the following syntax:

    - echo "Creating site %SITE%"
    - (%windir%\system32\inetsrv\appcmd add site /name:%SITE% /physicalPath:%APPDIR% /bindings:http://*:%PORT%)
    - echo "---"

This ends the PreInstall section of the manifest.

PostInstall - Unzip BlogEnbing.NET to Application Directory

Between the PreInstall and PostInstall phases, the Pipelines deploy does the “Install” phase where the application release bundle is downloaded to the destination Windows Server. This means that the BlogEngine.zip file is available, on the disk, in the PostInstall section. This file can be found in the %DISTELLI_INSTALLHOME% directory. For more information on System Environment variables see Environment Variables Reference Guide. You can use powershell to unzip the contents of the BlogEngine.zip file with one of the following syntax:

For Powershell ver 2

PowerShell (New-Object -COM Shell.Application).NameSpace('"%APPDIR%"').CopyHere((New-Object -COM Shell.Application).NameSpace('"%DISTELLI_INSTALLHOME%\ZIPFILE.zip"').Items(), 16);

For Powershell ver 3

powershell add-type -assemblyname "system.io.compression.filesystem" ; [System.io.compression.zipfile]::ExtractToDirectory('"%DISTELLI_INSTALLHOME%\ZIPFILE.zip"','"%APPDIR%"')

For this section the manifest syntax is:

  PostInstall:
    - echo "Begin PostInstall"
    - echo "Unzip BlogEngine.NET to Application Directory"
    # Using Powershell version 2
    #- PowerShell (New-Object -COM Shell.Application).NameSpace('"%APPDIR%"').CopyHere((New-Object -COM Shell.Application).NameSpace('"%DIStELLI_INSTALLHOME%\BlogEngine.NET 3.1 (web).zip"').Items(), 1564);
    # Using Powershell version 3+
    - powershell add-type -assemblyname "system.io.compression.filesystem" ; [System.io.compression.zipfile]::ExtractToDirectory('"%DIStELLI_INSTALLHOME%\BlogEngine.NET 3.1 (web).zip"','"%APPDIR%"')
    - echo "---"

Unremark the syntax that is appropriate for your version of Powershell on your destination Windows Server.

PostInstall - Set Directory Attributes

According to the install instructions for BlogEngine.NET, found here; the App_Data directory must have permissions set for the IIS User to read and write data. This can be accomplished in the PostInstall section after the files are unzipped to the disk.

    - echo "Set Directory Attributes"
    - attrib -r %APPDIR%\App_Data /s /d
    - icacls "%APPDIR%\App_Data" /grant IIS_IUSRS:(OI)(CI)F /t
    - icacls "%APPDIR%\App_Data" /grant IUSR:(OI)(CI)F /t
    - echo "---"

And this completes the PostInstall section.

Start - Start IIS Site

This section will ensure the IIS Site %SITE% is started using the following syntax:

  Start:
    - echo "Start IIS Site"
    - (%windir%\system32\inetsrv\appcmd start site %SITE%)
    - echo "---"

Start - Open Firewall

By default, the Windows firewall is enabled and will block traffic destined to the newly added IIS Site. You can setup rules to allow access to the IIS Site based on the TCP Port number %PORT%. I found that you can redundantly add the same firewall rule multiple times, so to keep things clean, and avoid a deploy failure, I wanted to ensure rules were being deleted before adding. Before deleting I actually add the rule to avoid getting an error.

    - echo "Open Firewall"
    - set FWNAME="%SITE% fw rule TCP Port %PORT%"
    - echo "Adding %FWNAME%"
    - netsh advfirewall firewall add rule name=%FWNAME% dir=in action=allow protocol=TCP localport=%PORT%
    - netsh advfirewall firewall delete rule name=%FWNAME%
    - netsh advfirewall firewall add rule name=%FWNAME% dir=in action=allow protocol=TCP localport=%PORT%
    - netsh advfirewall firewall add rule name=%FWNAME% dir=out action=allow protocol=TCP localport=%PORT%
    - echo "---"

That is it for the manifest. Save your file changes and get ready to deploy this application to your Windows Server.

Steps to Deploy this Application

  1. Load the Pipelines Agent on your destination Windows Server where you are deploying the application to. The Pipelines Agent will connect your Server to your Pipelines Account so you can deploy applications to the server.
  2. Pipelines create - In the WinIISBlog directory, where the distelli-manifest.yml file you just created exists, run the distelli create> command. This assume you have the Pipelines CLI Installed on this system.
  3. Remember to replace <username> with your Pipelines username. distelli create <username>/WinIISBlog

    This will create the application in your Pipelines Account.

  4. Pipelines push - Push the first release of the WinIISBlog application up to your Pipelines Account.
  5. distelli push -m \First Release\
  6. With your web browser log into the Pipelines web UI at pipelines.puppet.com/login.
  7. Find and click the Application name WinIISBlog.
  8. Create an Application Environment.
    1. Click Environments link.
    2. Click Create Environment link.
    3. Enter the "Name" WinIISBlog_Env and click Create Environment.
  9. Add your server to the Application Environment
    1. From the WinIISBlog_Env page, which you should be on, click Servers link.
    2. Click the Add Servers link.
    3. Find your Windows Server, you installed the agent on earlier, and check the Add Server box.
    4. Click the Add Selected Servers link.
  10. Deploy your First Release to the Environment
  11. Click Details link.
  12. In the Release list click the Deploy button for your "First Release".
  13. In the "New Deployment" dialog click the Deploy button.

The WinIISBlog application is now being deployed to your Windows Server in the WinIISBlog_Env environment. You can click the View Log button to watch the logging of the deployment phases. Note: The PreInstall of the IIS requirements can take a “more than expected” time to complete. If you have a failure deploying, as a suggestion, you can add more debugging by adding more echo statements to the distelli-manifest.yml. Remember that when you make changes you have to do a distelli push -m "Message" to update the Release in your Pipelines account.

The Complete Manifest

&lt;username&gt;/WinIISBlog:
  PkgInclude:
    - '*.zip'
  Env:
    # Define the TCP port you want the IIS application to listen on
    - PORT: "8085"
    # Define the Name for the IIS application
    - SITE: BlogEngine
    # Define the Directory full path where the IIS application should reside
    - APPDIR: c:\blog
  PreInstall:
    - echo "Begin PreInstall"
    - echo "Install any IIS Prerequisites"
    - dism /enable-feature /online /featurename:IIS-WebServer /all
    - dism /enable-feature /online /featureName:IIS-ASP /all
    - dism /enable-feature /online /featureName:IIS-ASPNET /all
    - dism /enable-feature /online /featureName:IIS-ASPNET45 /all
    - echo "---"
    - echo "Removing existing IIS Site"
    - for /F "tokens=*" %%a in ('%windir%\system32\inetsrv\appcmd list site %SITE%') do set RESPONSE=%%a
    - if "%RESPONSE%"=="" (
    -   echo "%SITE% doesn't exist"
    - ) else (
    -   echo "%SITE% does exist. Deleting"
    -   (%windir%\system32\inetsrv\appcmd delete site %SITE%)
    - )
    - echo "Create Application Directory"
    - rmdir /S/Q %APPDIR%
    - mkdir %APPDIR%
    - echo "---"
    - echo "Creating IIS Site"
    - (%windir%\system32\inetsrv\appcmd add site /name:%SITE% /physicalPath:%APPDIR% /bindings:http://*:%PORT%)
    - echo "---"
    - echo "Done PreInstall"
  PostInstall:
    - echo "Begin PostInstall"
    - echo "Unzip BlogEngine.NET to Application Directory"
    # Using Powershell version 2
    #- PowerShell (New-Object -COM Shell.Application).NameSpace('"%APPDIR%"').CopyHere((New-Object -COM Shell.Application).NameSpace('"%DIStELLI_INSTALLHOME%\BlogEngine.NET 3.1 (web).zip"').Items(), 1564);
    # Using Powershell version 3+
    - powershell add-type -assemblyname "system.io.compression.filesystem" ; [System.io.compression.zipfile]::ExtractToDirectory('"%DIStELLI_INSTALLHOME%\BlogEngine.NET 3.1 (web).zip"','"%APPDIR%"')
    - echo "---"
    - echo "Set Directory Attributes"
    - attrib -r %APPDIR%\App_Data /s /d
    - icacls "%APPDIR%\App_Data" /grant IIS_IUSRS:(OI)(CI)F /t
    - icacls "%APPDIR%\App_Data" /grant IUSR:(OI)(CI)F /t
    - echo "---"
    - echo "Done PostInstall"
  Start:
    - echo "Begin Start"
    - echo "Start IIS Site"
    - (%windir%\system32\inetsrv\appcmd start site %SITE%)
    - echo "---"
    - echo "Open Firewall"
    - set FWNAME="%SITE% fw rule TCP Port %PORT%"
    - echo "Adding %FWNAME%"
    - netsh advfirewall firewall add rule name=%FWNAME% dir=in action=allow protocol=TCP localport=%PORT%
    - netsh advfirewall firewall delete rule name=%FWNAME%
    - netsh advfirewall firewall add rule name=%FWNAME% dir=in action=allow protocol=TCP localport=%PORT%
    - netsh advfirewall firewall add rule name=%FWNAME% dir=out action=allow protocol=TCP localport=%PORT%
    - echo "---"
    - echo "Done Start"
How helpful was this page?
Puppet sites use proprietary and third-party cookies. By using our sites, you agree to our cookie policy.