IIS Websites and Application Pools

Last updated

The IIS Web Site and Application Pool feature is one of the configuration features you can enable as you define the steps in your deployment process.

Configuring IIS is an essential part of deploying any ASP.NET web application. Octopus has built-in support for configuring IIS Web Sites, Applications, and Virtual Directories. To deploy to IIS,

  1. From your project's overview page, click DEFINE YOUR DEPLOYMENT PROCESS.
  2. Click ADD STEP, and then select the Deploy to IIS step.
  3. Give the step a name.
  4. Select the package feed and enter the package ID of the package to be deployed.
  5. Choose the IIS deployment type:

Understanding the difference between Sites, Applications, and Virtual Directories is important to understand how to use the IIS Websites and Application Pools features in Octopus. Learn more about Sites, Applications, and Virtual Directories in IIS.

Deploy IIS Web Site

You need to fill out the following fields for an IIS Web Site deployment:

Field Meaning Examples Notes
Web Site Name The name of the IIS Web Site to create (or reconfigure, if the site already exists). MyWebSite
Physical path The physical path on disk this Web Site will point to. /Path1/Path2/MySite
#{MyCustomInstallationDirectory}		 You can specify an absolute path, or a relative path inside the package installation directory.
Application Pool name Name of the Application Pool in IIS to create (or reconfigure, if the application pool already exists). MyAppPool
.NET CLR version The version of the .NET Common Language Runtime this Application Pool will use.
  • v2.0
  • v4.0
Choose v2.0 for applications built against .NET 2.0, 3.0 or 3.5.
Choose v4.0 for .NET 4.0 or 4.5.
Identity Which account the Application Pool will run under.
  • Application Pool Identity
  • Local Service
  • Local System
  • Network Service
  • Custom user (you specify the username/password)
Start mode Specifies whether the IIS Web Site and/or Application Pool are started after a successful release.
  • IIS Application Pool and IIS Web Site
  • IIS Application Pool Only
  • Do not start either
Bindings Specify any number of HTTP/HTTPS bindings that should be added to the IIS Web Site.
Authentication modes Choose which authentication mode(s) IIS should enable.
  • Anonymous
  • Basic
  • Windows
You can select more than one authentication mode.

Deploy IIS Virtual Directory

The IIS Virtual Directory step requires a parent Web Site to exist in IIS before it runs. You can create a chain of steps like this:

  1. Make sure the parent Web Site exists in IIS and is configured correctly
  2. Create any number of Web Applications and Virtual Directories as children of the parent Web Site

You need to fill out the following fields for an IIS Virtual Directory deployment:

Field Meaning Examples Notes
Parent Web Site name The name of the parent IIS Web Site. Default Web Site, MyWebSite The parent Web Site must exist in IIS before this step runs. This step will not create the Web Site for you.
Virtual path The relative path from the parent IIS Web Site to the Virtual Directory. If you want a Virtual Directory called MyDirectory belonging to the Site MySite as part of the Application MyApplication you would set the Virtual Path to /MyApplication/MyDirectory. All parent applications/directories must exist. Does not need to match the physical path.
Physical path The physical path on disk this Virtual Directory will point to. /Path1/Path2/MyDirectory, #{MyCustomInstallationDirectory}. You can specify an absolute path, or a relative path inside the package installation directory.

The Virtual Path and Physical Path do not need to match which is one of the true benefits of IIS. You can create a virtual mapping from a URL to a completely unrelated physical path on disk. See below for more details.

Deploy IIS Web Application

The IIS Web Application step requires a parent Web Site to exist in IIS before it runs. You can create a chain of steps like this:

  1. Make sure the parent Web Site exists in IIS and is configured correctly
  2. Create any number of Web Applications and Virtual Directories as children of the parent Web Site

You need to fill out the following fields for an IIS Web Application deployment:

The Virtual Path and Physical Path do not need to match which is one of the true benefits of IIS. You can create a virtual mapping from a URL to a completely unrelated physical path on disk. See below for more details.

Field Meaning Examples Notes
Parent Web Site Name The name of the parent IIS Web Site. Default Web Site, MyWebSite The parent Web Site must exist in IIS before this step runs. This step will not create the Web Site for you.
Virtual Path The relative path from the parent IIS Web Site to the Web Application. If you want a Web Application called MyApplication belonging to the Site MySite you would set the Virtual Path to /MyApplication. All parent applications/directories must exist. Does not need to match the physical path.
Physical path The physical path on disk this Web Application will point to. /Path1/Path2/MyApplication, #{MyCustomInstallationDirectory}. You can specify an absolute path, or a relative path inside the package installation directory.
Application Pool name Name of the Application Pool in IIS to create (or reconfigure, if the Application Pool already exists).
.NET CLR version The version of the .NET Common Language Runtime this Application Pool will use. v2.0, v4.0 Choose v2.0 for applications built against .NET 2.0, 3.0 or 3.5. Choose v4.0 for .NET 4.0 or 4.5.
Identity Which account the Application Pool will run under. Application Pool Identity, Local Service, Local System, Network Service, Custom user (you specify the username/password)

How Octopus Deploys your Web Site

Out of the box, Octopus will do the right thing to deploy your Web Site using IIS, and the conventions we have chosen will eliminate a lot of problems with file locks, leaving stale files behind, and causing multiple Application Pool restarts. By default Octopus will follow the conventions described in Deploying packages and apply the different features you select in the order described in Package deployment feature ordering.

Avoid using the Custom Installation Directory feature unless you are absolutely required to put your packaged files into a specific physical location on disk.

Octopus performs the following steps:

  1. Acquire the package as optimally as possible (local package cache and delta compression).
  2. Create a new folder for the deployment (which avoids many common problems like file locks, leaving stale files behind, and multiple Application Pool restarts).
  3. Example: C:\Octopus\Applications\[Tenant name]\[Environment name]\[Package name]\[Package version]\ where C:\Octopus\Applications is the Tentacle application directory you configured when installing Tentacle).
  4. Extract the package into the newly created folder.
  5. Execute each of your custom scripts and the deployment features you've configured will be executed to perform the deployment following this order by convention.
  6. As part of this process the IIS Web Site, Web Application, or Virtual Directory will be configured in a single transaction with IIS, including updating the Physical Path to point to this folder.
  7. Output variables and deployment artifacts from this step are sent back to the Octopus Server.

You can see exactly how Octopus integrates with IIS in the open-source Calamari library.