Installing Oqtane on IIS
By: Shaun Walker
It is possible to install Oqtane without using Visual Studio. However in order to do this you need to become familiar with the specifics of hosting a Blazor application. In this article we will install an Oqtane release locally on a Windows 10 machine using IIS.
Step 1 - Install IIS
*Note: even if you have IIS already installed you will want to ensure the appropriate options are enabled/disabled
- Use the search icon next to your Windows Start button to search for "Turn Windows features on or off"
- Scroll down to Internet Information Services and enable it ( this will enable the default options for IIS )
- Expand the Internet Information Services option ( using [+] ) and scroll down to World Wide Web Services and expand it as well
- Within Application Development Features make sure that WebSocket Protocol is enabled ( this is needed for SignalR )
- Within Common HTTP Features make sure WebDAV Publishing is disabled ( if it is enabled it will conflict with Blazor )
- click Ok to complete the installation
Step 2 - Install Url Rewrite Module
- Navigate to https://www.iis.net/downloads/microsoft/url-rewrite
- Download and install
Step 3 - Install .NET Core Hosting Bundle
- Navigate to https://dotnet.microsoft.com/permalink/dotnetcore-current-windows-runtime-bundle-installer
- Download and install ( note that the current .NET Core version is 6.0 )
- Restart your machine
Step 4 - Install LocalDB
*Note: this step is only required if you are doing a local install and want to use LocalDB for development. Oqtane also supports SQLite, MySQL, PostgreSQL, and SQL Server.
- Navigate to https://docs.microsoft.com/en-us/sql/database-engine/configure-windows/sql-server-express-localdb?view=sql-server-ver15
- choose Express Advanced or the LocalDB package in order to install LocalDB
*Note: If you have Visual Studio installed you can also install LocalDB by choosing the .NET Desktop Development workload in the Visual Studio installer.
Step 5 - Install Oqtane
*Note: Do NOT attempt to Publish a release directly from Visual Studio as there are critical build configurations which will not be included in the output if you try to use this approach.
- Download the latest Install package from https://github.com/oqtane/oqtane.framework/releases ( ie. Oqtane.Framework.3.1.0_Install.zip )
- Extract the files to a directory where you plan to host your application
Step 6 - Configure IIS App Pool
*Note: Blazor only supports one app pool per app when hosting with IIS and does not support virtual directories. Also Oqtane does not support IIS sub-applications at this time.
- Use the search icon next to your Windows Start button to search for "Internet Information Services (IIS) Manager"
- expand the top node identifying your machine in the left-hand pane
- right-click on Application Pools and select "Add Application Pool"
- provide a Name for the application pool ( ie "oqtane" )
- for .NET CLR version specify No Managed Code
- click Ok
- in the main Application Pools pane select the pool you just created
- in the right-hand Actions pane select the Advanced Settings option
- scroll down to Process Model and find the Identity option
- set the Identity to "LocalSystem" ( this provides the necessary permission for IIS to interact with the file system and LocalDB )
Step 7 - Configure IIS Website
- in Internet Information Services in the left-hand pane right-click on Sites and select "Add Website"
- provide a name ( ie. "oqtane" ) and use the Select... button to choose the Application Pool you created above
- specify the path to the root directory where you extracted the Oqtane files earlier
- specify a Host name ( ie. "oqtane.dev" ) - this host name needs to be mapped to the machine and the easiest method is to follow the instructions in Step 8
Step 8 - Add a Host entry
*Note: this step is only required for a local development environment - if you are running Oqtane in a shared or public environment, you would use a standard DNS configuration.
- Use the search icon next to your Windows Start button to search for "Notepad" and right-click the entry in the Best Match results and choose Run As Administrator
- choose File / Open and navigate to C:\Windows\System32\drivers\etc and open the "hosts" file
- add an entry to the file for the host name you created in the previous step and map it to 127.0.0.1 ( ie. "127.0.0.1 oqtane.dev" )
- choose File / Save
Step 9 - Navigate to Site
*Note: The Install Wizard may encounter errors if your user account does not have rights to create a database. In this case you should create a database manually prior to initiating the Install Wizard.
- open your favorite browser ( ie. Firefox Developer Edition ) and navigate to the host name you created above ( ie. http://oqtane.dev )
- the Oqtane install wizard should be displayed
- enter your database connection details ( if you are using LocalDB then you can simply accept the default settings )
- enter your site administrator password and email - click Install