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.
- From your project’s overview page, click DEFINE YOUR DEPLOYMENT PROCESS.
- Click ADD STEP, and then select the Deploy to IIS step.
- Give the step a name.
- Select the package feed and enter the package ID of the package to be deployed.
- 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. |
| 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. |
| |
| Start mode | Specifies whether the IIS Web Site and/or Application Pool are started after a successful release. |
| |
| 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. |
| 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:
- Make sure the parent Web Site exists in IIS and is configured correctly.
- 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.
We use PowerShell to create virtual and physical directories. There is a known limitation with PowerShell which prevents the creation of virtual directories with a leading dot directly under the parent website in IIS. There are two workarounds for this. First, you can manually create a virtual directory on the server using the IIS manager. Alternatively, you can create a physical directory with the same name as your virtual directory’s target physical directory where your site or application will be installed. For example, you might create a physical directory in the website installation directory called .well-known, and then configure your IIS deployment step to create a virtual directory directly under the parent website directory. This issue has been documented here.
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:
- Make sure the parent Web Site exists in IIS and is configured correctly.
- 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:
- Acquire the package as optimally as possible (local package cache and delta compression).
- Create a new folder for the deployment (which avoids many common problems like file locks, leaving stale files behind, and multiple Application Pool restarts).
- Example:
C:\Octopus\Applications\[Tenant name]\[Environment name]\[Package name]\[Package version]\whereC:\Octopus\Applicationsis the Tentacle application directory you configured when installing Tentacle). - Extract the package into the newly created folder.
- 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.
- 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.
- 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.
How to Take Your Website Offline During Deployment
A IIS Website can be taken offline by placing a app_offline.htm file into the root directory of the website. The contents of that file will be shown to anyone accessing the site. This is useful if you do not want to users to access the site while the deployment is being performed. It recycles the App Pool, releasing any file locks the site may have.
This can be done by including an app_online.htm file in your website and then renaming it to app_offline.htm at the
start of the deployment. This can be done via a script or the IIS - Change App Offline step in the
community library.
Learn more
- Generate an Octopus guide for IIS and the rest of your CI/CD pipeline.
Help us continuously improve
Please let us know if you have any feedback about this page.
Page updated on Sunday, January 1, 2023