.NET and Open Source: better together

RTur.net

  • Join Us on Facebook!
  • Follow Us on Twitter!
  • LinkedIn
  • Subcribe to Our RSS Feed

BlogEngine.NET Deployment Guide

Requirements

  • .NET framework 4.0 or higher
  • IIS 7.0 or higher

Download BlogEngine.NET

  1. Download latest BlogEngine.NET web package from http://blogengine.codeplex.com/releases
  2. Extract content of the downloaded .zip file, you should see BlogEngine.Web folder with all website files in it.

Copy (FTP) files to web server

  1. Open FTP connection to the web server you going to deploy BlogEngine to using client like FileZilla or similar.
  2. Create folder for application, for example "blog"
  3. Copy all files from downloaded and unzipped BlogEngine.Web folder to your web server "blog" folder

Configure IIS

  1. Open IIS manager, select web site, right-click and select "Add virtual directory". Select "blog" folder as site directory.
  2. Right-click created virtual directory and select "Convert to application".
  3. Make sure select application pool that uses .NET 4.0 and integrated pipeline mode.image
  4. Right-click "Application Pools" and select "Advanced Settings". Notice what user runs this application pool.image
  5. If it is not "Network service", change it to run under "Network service" identity.

Set file permissions

  1. Right-click "blog/App_Data" folder in the Windows explorer and select "Properties", then "Security".
  2. If "Network service" is not one of the users listed, click "Edit" then "Add" and add "Network service" user to the list. Select "Modify" permission and click "Ok". image
  3. Optionally give "Network service" modify permission on /blog/web.config folder - changing timestamp on web.config used to recycle application pool when installing new extensions.

Login


1. Open web browser and navigate to your site, for example http://rtur-rus/blog. You should see home page loaded with no errors.
2. Click "Login" link and log in using "admin" as both user name and password. You should be redirected back to home page and see administration widget added to the right side bar.

Setting up Database Provider

 

  1. Connect to your database using tool like "SQL Server Management Console". Select Security/Logins, right-click and select “new login”. Enter login for your blog, just for simplicity here it will be admin for login name and “Admin987” as password. You should use strong password and meaningful name for production site.image
  2. Right-click "Databases" node and select "New database”. Enter a name for your database, for example “blog”, and click “ok”.image
  3. After login and database are created, set “admin” with permissions for this database. Right-click “admin” under “security/logins” and select “properties”. Give admin permissions as shown below.image
  4. Open SQL script under /setup/SQLServer/MSSQLSetup.2.6.0.0.sql and copy all text.image
  5. Back to SQL server management studio, select “new query” and paste SQL script copied in the previous step. Make sure you have “blog” database selected and click “execute” button. All should run without any errors and generate database tables and data. image
  6. Move /setup/SQLServer/SQLServerWeb.Config to the site root. Rename existing Web.Config to Web.XML.Config and file you just moved to Web.Config. Open Web.Config in any text editor and change connection string to match SQL Server name, database (catalog), user ID and password. Save and close configuration file. image
  7. You should be able to navigate to your site at this point image
  8. placeholder.

Post-setup and personalization

Once BlogEngine is up and running, you can go through these steps to enable/disable functionality you need, such as email, RSS, spam protection etc. Most of these steps are optional and only need to change and improve default behavior.

Email setup

BlogEngine sends email notifications to the blog author when new comment received, if someone subscribes to comment notifications or email newsletter this user will also get emails when new comment added to the thread or new post published.

Email settings can depend on what your host allows you to use. For example, gmail typically requires ports like 465 or 587 to be opened and SSL enabled, and some hosts will only let their own email accounts to be used. If your host allows gmail, here is standard settings that should work. If you click “test mail settings” button and get error message for both ports, you need to contact your host and verify what email settings you can use.image

Spam protection

  1. When comment moderation enabled in the admin/settings any comment will be posted only after administrator approves it. 
  2. Recaptcha is a service provided by Google that protects blog from comments posted by spam bots. You can sign up for a recaptcha application key for free at google.com/recaptcha.image
  3. To setup recaptcha for your blog, go to appearance/extensions, enter application keys you got in the previous step and enable extension.image
  4. After Recaptcha enabled, you should see challenge/response box added to the comment form that user will need to pass before comment will be published.image
  5. Another comment protection feature is Akismet – you can subscribe for Akismet account here: http://akismet.com/wordpress/ image
  6. Similar to Recaptcha, you need to fill up application key and enable extension to setup Akismet. Once enabled, every comment will be sent to Akismet service to identify if this is a spam. If it is, BlogEngine will automatically send it to “spam” folder.image

Google Analytics

  1. Google analytics provides statistics on blog usage. You can subscribe to it at google.com/analytics. image
  2. During sign up, google will provide you a script that you need to add to admin/settings/custom code section in the admin: image
  3. This script will monitor user access to your blog and all statistics will be available to blogger at google.com/analytics.

Syndication (RSS)

BlogEnging has built-in syndication capabilities (posts, comments, categories, tags etc) accessible over syndication.axd handler. You can enhance it by using FeedBurner – service that combines RSS feeds with statistics on their usage. With FeedBurner you can see how many users subscribed to your feeds, how they access your blog from RSS readers and what posts they read.

  1. Subscribe to FeedBurner at http://feedburner.google.com.image
  2. Enter FeedBurner URL as “Alternative feed URL” in the admin/settings/feed. image
  3. Access feed statistics at http://feedburner.google.com.

Customization options

BlogEngine is highly customizable and extendible application. Here are some most common options to make your blog look and behave differently.

Custom themes

Themes can be installed from online gallery by going to /admin/appearance/themes/gallery and selecting theme to install. Or it can be created manually - technically theme is a folder with required templates, styles and resources. All installed themes located in the /themes folder.

BlogEngine supports 2 template styles, standard ASPX used in WebForms and Razor - more modern template engine used in ASP.NET MVC and WebPages.

ASPX theme contains site.master which defines overall site layot, commentview.ascx and postview.ascx with comment and post layouts. 
 
Razor theme uses site.cshtml, postview.cshtml and commentview.cshtml for the same exact purposes. Other files in the theme folder can be images, styles and optional supporting templates. If theme requires stylesheets and javascritps, it is better to add them to /styles and /scripts folders where they will be bundled and minimized for better performance. Usually only files in the /theme/<yourcustomtheme> folder have to be modified if you want to make changes to the theme.

User controls

User controls are specific to ASPX themes, for Razor themes closest equivalent would be a helper function. BlogEngine has two kind of controls: code only controls, that located at App_Code/Contols, such as "blogroll", "categorylist" etc. and user controls in "User controls" folder. They both can be used by the theme which can define control and show control output within theme HTML.

Widgets

Widgets are controls that managed by widgets framework. To use widgets, theme must include at least one widget zone. Zone provides admin UI allowing to add, modify and remove any installed widget. Widgets can be installed similar to themes by going to admin/widgets/gallery and selecting widget to install. Installed widgets added to /widgets folder, typically there edit.ascx to provide edit functionality and widget.ascx that represents widget UI.

Extensions

Extensions are functions that react to events happening on the blog, like serving post or adding comment. For example every time before serving post to the user, BlogEngine checks if there any extensions subscribed to "post serving" event and, if there is, post will be passed to extension first. Extension has an opportunity to modify post or cancel sending post to the client all together. This can be very powerful and useful in many scenarios. Extensions can be downloaded from admin/extensions/gallery.

Integration with other applications

BlogEngine can be installed as sub-application within another ASP.NET 4.0 application. For this, you can create a folder within existing application, for example "blog", and configure this folder as application in IIS.image

To configure folder as application, first you need to add virtual directory pointing to this folder to IIS and then convert virtual directory to application. This application has to use .NET 4.0 integrated application pool.

Full integration with existing application requires to merge 2 ASP.NET sites and although possible but can be extensive work.

Security and authentication

BlogEngine.NET is multi-blog and multi-user application. When installed in sub-folder under another application, security (membership) is separated for all. For example we have WebApp in the root and BlogEngine.NET installed in sub-folder as application “blog”. There are two sub-blogs created under “blog”, sub1 and sub2.

Below is web.config from parent (WebApp) application. It uses forms authentication and ASP.NET membership provider. This provider uses local SQL Server database to store membership tables with users and roles. This is a standard default configuration you get with new web application template out of the box.

<system.web>
  <authentication mode="Forms">
    <forms loginUrl="~/Account/Login.aspx" timeout="2880" />
  </authentication>

  <membership>
    <providers>
	<clear/>
	<add name="AspNetSqlMembershipProvider" type="System.Web.Security.SqlMembershipProvider" connectionStringName="ApplicationServices"
	 enablePasswordRetrieval="false" enablePasswordReset="true" requiresQuestionAndAnswer="false" requiresUniqueEmail="false"
	 maxInvalidPasswordAttempts="5" minRequiredPasswordLength="6" minRequiredNonalphanumericCharacters="0" passwordAttemptWindow="10"
	 applicationName="/" />
    </providers>
  </membership>

  <roleManager enabled="false">
    <providers>
	<clear/>
	<add name="AspNetSqlRoleProvider" type="System.Web.Security.SqlRoleProvider" connectionStringName="ApplicationServices" applicationName="/" />
	<add name="AspNetWindowsTokenRoleProvider" type="System.Web.Security.WindowsTokenRoleProvider" applicationName="/" /> 
    </providers>
  </roleManager>
</system.web>

BlogEngine.NET can use either XML or database for membership. By default, it uses XML and stores users and roles data in the App_Data folder. But you can change it in web.config setting default provider be a database provider. All tables required for membership created during database setup step.

<system.web>
  <machineKey validationKey="D9F7287EFDE8DF4CAFF79011D5308643D8F62AE10CDF30DAB640B7399BF6C57B0269D60A23FBCCC736FC2487ED695512BA95044DE4C58DC02C2BA0C4A266454C" decryptionKey="BDAAF7E00B69BA47B37EEAC328929A06A6647D4C89FED3A7D5C52B12B23680F4" validation="SHA1" decryption="AES"/>

  <authentication mode="Forms">
    <forms timeout="129600" name=".AUXBLOGENGINE" protection="All" slidingExpiration="true" loginUrl="~/Account/login.aspx" cookieless="UseCookies"/>
  </authentication>

  <membership defaultProvider="XmlMembershipProvider">
    <providers>
	  <clear/>
	  <add name="XmlMembershipProvider" type="BlogEngine.Core.Providers.XmlMembershipProvider, BlogEngine.Core" description="XML membership provider" passwordFormat="Hashed"/>
	  <add name="SqlMembershipProvider" type="System.Web.Security.SqlMembershipProvider" connectionStringName="BlogEngine" applicationName="BlogEngine"/>
	  <add name="DbMembershipProvider" type="BlogEngine.Core.Providers.DbMembershipProvider, BlogEngine.Core" passwordFormat="Hashed" connectionStringName="BlogEngine"/>
    </providers>
  </membership>

  <roleManager defaultProvider="XmlRoleProvider" enabled="true" cacheRolesInCookie="false">
    <providers>
	  <clear/>
	  <add name="XmlRoleProvider" type="BlogEngine.Core.Providers.XmlRoleProvider, BlogEngine.Core" description="XML role provider"/>
	  <add name="SqlRoleProvider" type="System.Web.Security.SqlRoleProvider" connectionStringName="BlogEngine" applicationName="BlogEngine"/>
	  <add name="DbRoleProvider" type="BlogEngine.Core.Providers.DbRoleProvider, BlogEngine.Core" connectionStringName="BlogEngine"/>
    </providers>
  </roleManager>
</system.web>

So by default we get two completely separate memberships. When user logs into main site, ASP.NET will create authentication cookie that looks something like:

.ASPXAUTH=4DCD213779D68B7CAF462F46….

And when user goes to WebApp/blog and logs in, another authentication cookie created:

.AUXBLOGENGINE-96d5b379-7e1d-4dac-a6ba-1e50db561b04=57CAB5B9….

This one is BlogEngine.NET cookie and it is prefixed with blog ID to distinct one blog from the other. When logged into WebApp/blog/sub1, there will be yet another cookie:

.AUXBLOGENGINE-7b30c686-a3d6-4f45-9f0e-e3ac101dee97=82CD8B9CA9….

This way user “admin” from one blog can’t administer another blog that also happened to have user with the same name etc. – we  want this separation in the multi-blog and multi-user environment.

Upgrade from previous version

The cleanest way to upgrade is to start from a new installation, and then copy your existing data and settings into new blog.

1.  Backup

Make a full backup of your existing BlogEngine installation.  This is very important.  If anything goes wrong, you can always restore to your backup.

2.  Install latest version

Install latest BlogEngine version on your computer, in a new folder.

3.  Web.config file (for non-database installations)

You should be able to use web.config as is, unless you made modifications required for your specific functionality, hosting restrictions etc. Compare web.config you backed up in the first step to new web.config to identify if there is anything you need to change.

4.  Web.config file (for database installations)

If you will be using a Database for data storage, Web.config files you can use are located in the /setup/ folder.  Start from these sample web.config files, and copy your specific connection string into the sample web.config file.  For example, for SQL Server, in the /setup/SQLServer folder is a file named SQLServerWeb.Config.  For MySQL, the file is /setup/MySQL/MySQLWeb.Config, etc.  Copy this file to the blog root, delete the existing Web.config file in the blog root, and then rename this sample config file to Web.config (i.e. rename SQLServerWeb.Config to Web.Config).

At this point, the Web.config file you copied to the blog root and renamed contains a sample DB connection string.  The sample DB connection string will look similar to:

connectionString="Data Source=MySQLServer;User ID=user;Password=password;persist security info=False;initial catalog=BlogEngine;"

Replace this sample connection string with the connection string in your existing Web.config file.

If you have any other specific customizations to your existing Web.config file (e.g. appSettings), add those into this Web.config file.

5.  Database Upgrade Script (for database installations)

If you are using a Database to store your data in, you will need to run the DB upgrade script.  Each of the /setup folders has an upgrade script.  For SQL Server, it is MSSQLUpgradeFrom2.5to2.6.sql.  For MySQL, it is MySQLUpgradeFrom2.5To2.6.sql, etc.  Run this script in your existing DB.  If you are upgrading from a version prior to 2.5, you will need to first run the upgrade script(s) to get your DB up to v2.5.  For example, if you are upgrading from v2.0, you will need to first run the 2.0to2.5 and then 2.5to2.6.

6.  App_Data folder (for BOTH database and non-database installations)

Delete all of the files and folders inside App_Data in the new installation. Next, copy all of your App_Data contents (files/folders) from your existing blog to the new App_Data folder.

Note:  This step should still be performed even if you are using a database since even with a database, the App_Data folder is still used for storing miscellaneous files.

7.  Theme folder, Robots.txt & Other Custom Files

If you have a custom theme, copy your custom theme folder into the v2.6 "themes" folder.  Similarly, if you have customized the robots.txt file, or if you have any other custom files/folders, copy those into the v2.6 folder you have been working on.

8.  Deploy to Web Server

Because you will have files on your web server that no longer exist (or have been moved) in older version, it is best to delete all of the BlogEngine.NET files and folders on your web server, and then upload the new version files and folders you prepared in the previous steps.

Please make sure you have a backup of everything you will delete (see step 1).

9.  Check App_Data folder Write Permissions

If you deleted the App_Data folder in the previous deployment step, you may need to double check that Write permissions are still set on the new App_Data folder you uploaded.  Even if you are using the Database storage option, certain items such as files & images you include in your blog posts are still saved in the App_Data folder.  BlogEngine.NET can only save files in the App_Data folder if Write permissions are enabled for the ASP.NET account.

[password:davinci]