Installing and Upgrading

Installing Subtext

There are two ways to install Subtext:

Using the Microsoft Web Platform Installer

If you have console access to your web server (for example, you can remote desktop in or login directly) then installing Subtext is a breeze using the Web Platform Installer.

Just click here and let the installer do the heavy lifting. Once it's installed, go ahead and create a new blog.

Manual Installation

If you don't have console access to your web server but you can connect via FTP (this is common with hosting providers such as GoDaddy), there are a few additional steps to installing Subtext.

The basic process, which we will walk through in detail, is:
  1. Copy the Subtext files to your web server
  2. Create the Subtext content database
  3. Update web.config to point to your database
  4. Run through the installation wizard
  5. Create a blog

Note: If you are using GoDaddy, there is a helpful blog post here from a user who went through the install process and had to do some additional work. We recommend you check that out in addition to the below instructions.

Detailed installation steps:

  1. Download the latest release from Google Code. (Make sure to download the install/deployment release unless you plan on building the source yourself).
  2. Unzip the package into a directory on your local machine
  3. Set up your database.
    • If you are going to use SQL Express, the install package contains a database (.mdf) file already. No work needed.
    • If you are not going to use SQL Express or if your hosting provider has a database server available for you, do the following:
      1. Create a new database for your Subtext data.
      2. Make sure the Subtext database user (the user account that will be used for reading/writing the data) has owner permissions on the database. (This is necessary for the install process. You can downgrade permissions after install.)
      3. Open the Subtext web.config file and update the ConnectionString AppSetting value to match your database. For help in constructing the connection string, check out http://connectionstrings.com/
  4. Set up an IIS application for your blog (unless your hosting provider already has one set up for you).
  5. Copy the installation files from your local machine to the IIS application folder on your web server.
  6. Configure the custom 404 page.
  7. Navigate to your blog via the browser and follow the installation steps.
  8. Create a new blog.
  9. Optional: If you plan to use the "Photo Galleries" feature or the MetaWeblog API "MediaObject" interface to upload images for your blog posts (e.g., via Windows Live Writer or desktop blog publishing software) you'll need to give the ASP.NET account (on Windows 2000) or the Network Service account (on Windows Server 2003 and above) "Modify" rights to your /Images/ directory. If you don't have access to modify permissions directly, you may need to get some help from your service provider.



Upgrading Subtext

Whether you installed from the Web Platform Installer or the manual way, the upgrade process is the same... and it's manual.

The basic process, which we will walk through in detail, is:

  1. Back up your content
  2. Manually merge the new Subtext release into your blog
  3. Run through the automated database upgrade process

This screencast walks through using a new tool to upgrade.


The detailed process is as follows:

  1. Back up your content database and any files/images you've uploaded as part of your blog content
  2. If you are not using SQL Express as your database engine, make sure the Subtext database user (the user account that is used for reading/writing the data) has owner permissions on the database. (This is necessary for the upgrade process. You can revert permissions after the blog upgrade.)
  3. Make sure you can login to the HostAdmin section. On most blogs this would be the /HostAdmin/ directory of the site. For example "http://your.blog.com/HostAdmin/". If you forget your HostAdmin password, there is a query you can run in Query Analyzer to reset your password at the bottom of this page
  4. Download the latest deployment release of Subtext
  5. Prepare to merge the new Subtext deployment with your existing one
    • If you have console access to your web server, you can unzip the Subtext application in a folder directly on the server to make it easy
    • If you do not have console access to your web server but you can connect via FTP (this is common with hosting providers such as GoDaddy), you need to:
      1. Unzip the new Subtext deployment files to a folder on your local machine
      2. Download the entire existing Subtext deployment from your web server to your local machine
  6. Using a tool such as WinMerge or DiffMerge, you need to merge the changes you made to your old site (which will be in the folder with your existing deployment files) into the location where you unzipped the new Subtext deployment. Be sure to include:
    • Customizations (like the connection string for the database) in the web.config file
    • Custom skins you've added or created
    • Additional files you may have added into the blog
  7. Replace your old deployment of Subtext with the new one. The goal here is to get the new binaries and other files into your blog application folder while retaining all of your customizations and uploads
    • As you do the replacement, do it intelligently - if you didn't include your uploaded image files and such during the merge into the new deployment folder, don't just blindly delete them or forget to include them when you do the replacement or you'll have some missing images
    • If you have console access to your web server, you'll most likely be doing file copy operations to add/replace files in the blog application folder and delete files that don't exist anymore (and aren't customizations or uploads you made)
    • If you don't have console access to your web server, you'll most likely be doing some FTP operations to upload new/overwrite existing files in the blog application and delete files that don't exist anymore (and aren't customizations or uploads you made)
    • If you use the upload features of the blog to upload images, etc., and had to change folder permissions to make that work, be careful not to delete the blog's /Images/ folder or you'll need to reset those permissions.
  8. Visit your blog and follow the instructions presented in the upgrade wizard. This will perform any database upgrades that need to happen

If you explicitly gave your database user "owner" permissions in step 2, don't forget to revert them when you're done upgrading.

Forgot Your HostAdmin Password?

If you have forgotten your HostAdmin password or inadvertently deleted the HostAdmin record, you can run the following query on the database to reset the HostAdmin account with the password "password". Use this carefully as it will leave your blog open to attack temporarily.

IF 0 = (SELECT COUNT(1) FROM subtext_Host)
  INSERT subtext_Host
  SELECT 'DesiredUserName'
    , 'sIHb6F4ew//D1OfQInQAzQ=='
    , 'SPYxRrEmM0CGLgjg0ikCgQ=='
    , getdate()
ELSE
  UPDATE subtext_Host
  SET Password='sIHb6F4ew//D1OfQInQAzQ=='
    , Salt='SPYxRrEmM0CGLgjg0ikCgQ=='

NOTE: You'll need to restart the application in order to clear the old credentials out of the cache. You can do this by opening the Subtext Web.config, add a space at the end of the first line, and save.

Immediately change the password once you've logged into the HostAdmin tool.

If you need a tool for administering your SQL Server, you can download Microsoft SQL Server Management Studio Express. If you work with a hosting provider, they may already have a tool, or you may need to request access to administer your database remotely.