In this tutorial, you will learn about some tips to help you get an existing Episerver website up and running on your local PC. As a contractor, I frequently work with different clients on different projects. The first hurdle when working with a new client on a legacy project is being able to get the existing site up and running on your development machine. If you are lucky, you might be working with an existing team and they can help you get everything you need. In other situations, you may be the only developer. In these situations, you will need to figure everything out yourself.

Getting an existing site up and running can be stressful, especially if there are no set-up instructions. Whenever I have found myself in this situation, I am often just starting working with a new company so there is pressure to show them I can add value quickly. It would not be acceptable to waste weeks of time just getting the site to run! This is why it's important to know how to get a site up and running. In this guide, I will walk you through the process that I follow when I'm trying to get an unknown website up and running. If you find yourself in a similar situation, this tutorial should get you unstuck 🔥🔥🔥

Where To Start?

I'm assuming at this point that you've got a copy of the websites source code, all media assets and a backup of the database. You have successfully compiled the site, and installed a corresponding website in IIS. When you view the site in a browser, some form of error message is thrown.

If the error message is a friendly error, e.g. not an ASP.NET yellow stack trace exception, the first task is to go to the web.config and disable custom errors. In the web.config there are two sections you need to update:

Note the mode, should be set to 'Off'. The second part is making sure the errorMode is set to DetailedLocalOnly. In most situations, except this to be set to Custom. Custom mode will hide the IIS message 😢

The reason why you need to update two things within web.config is simple. One section deals with error pages on an application basis, the other section deals with errors thrown by IIS. Either one of these settings can hamper your investigation skills if not set correctly!

Finding The Log Files

Checking your website's log files should always be one of your first go-to moves, however, in some builds simply finding the logs can be painful. In modern versions of Episerver the logs, by default are in the App_data folder. A lot of companies will change this location to follow good practices. Keeping the logs within the webroot isn't advisable as they can be read remotely via a browser, so it's very normal for people to change the log location to be outside the webroot.

The problem with changing the logging location is that finding where the logs get created can be hard. To find this location, you will need to open up EPiServerLog.config and find the fileLogAppender file location property. The value of fileLogAppender will be the folder you need to check!

Troubleshooting Your Episerver Website

After accessing the logs, you will usually find some entry that will give you a hint as to what is wrong. In the majority of situations, the reason a site fails to load can be broken into the following categories:

Missing Epi Products: If the site is reliant on one of the other Episerver bolt-ons, like the CMO, then you will need to install it before your site works. One tip to spot if your site is using the CMO is that is you should see errors complaining about ComponentArt.Web.Visualization in the thrown exception. Also, in the web.config you should see a reference to this handler:

If you need to install the CMO you can either use the old school deployment centre to install it, or you could use the trick below:

Missing Assemblies: As .NET moves closer towards a Nuget based world, missing binaries is becoming less of an issue than it was a few years ago. Life is not perfect and some applications still require you to install them. If you need to get a legacy system working that can not be installed via Nuget, like Episerver CMO, you may not have all the assemblies you need to run your website in source control alone.

To fix this issue you will need to install all missing assemblies. The easy way to do this is to get a working copy of the production files and then use a diff tool like Beyond Compare, to compare the differences between the two bin folders. Find what assemblies you are missing locally and copy them over.

In most cases, as soon as you copy over the files and re-run the site everything works 😊😊. If you encounter missing assemblies in source control, I would strongly recommend creating a Libs folder in your solution and add the missing assemblies into it. You can now add these missing files to source control so the next developer won't have the same issues. You are a good person 👍.

Missing Databases: This is another fairly standard root cause. The site is reliant on more than just the CMS database. The best way to determine how many databases a site uses is to go into the connection string settings in the web.config. Check that everything listed is installed in your local SQL server.

It is very common for a website to communicate with more than one database. A CRM system, a web API powered by its own database, a queue, or even different Episerver products like the CMO (it has its own database). If databases are missing then your website won't work!

Missing VPP Folders: The VPP system was made obsolete in Episerver CMS 7.5, however, for legacy projects a lot of sites still require the vpp folder to run successfully. If you have a missing VPP folder, corrupt file content etc.. then your website can

My first tip is to make sure that you have the latest version of the VPP folder. Copy it from production to make sure. Second, you need to make sure the project is pointing to the correct location. In EPiServerFramework.config, check where the appData property is pointing and copy your VPP files to the appropriate place.

There's no one size fits all set of instructions to get every single Episerver website up and running. Each website is a bespoke work of art and engineering. Each website has bespoke parts and designs that make it one of a kind. This is why getting a site up and running can be frustrating and make you want to pull your hair out.

My best advice is to always focus your time on fully understanding what the problem is and how the site works. You will get far more value understanding the site and it's nuances and consciously understanding how to fix the site, than just hacking away until you get lucky and the site works. Good luck! Happy Coding 🤘