I work frequently with numerous clients on different projects and the first big hurdle in being able to make any impactful changes is being able to get the existing site up and running on your development machine. In some instances, you might be working with an existing team and they can help you get everything you need, in some situations they have an amazing continuous integration process sorted and you can pull the source code from a repository, it magically works and off you go.. In other situations, you will be the only developer, the handover notes are next to nothing and it’s up to you to figure it all out. If you find yourself in these shoes, then getting a site up and running can be stressful. You are likely just starting with a new company and you want to show you have mad coding skills, but you can’t do a simple thing like get the site up and running. I’ve been in this situation far more times than I can remember (mainly as I’ve got a bad memory), so in today’s guide I’m going to cover the rough process I follow when I’m trying to get an unknown website up and running,
Where To Start?
Knowing where to start can be tricky. I’m assuming at this point that you’ve got a copy of the source code, a database, tried to compile the site and the beautiful site you were expecting to set your eyes on has been replaced by some form of error message. If the error message is a friendly error that’s masking the real problem, the first thing to do is go to the web.config and disable custom errors.
In the web.config there are two sections you should always check, first, the custom errors section:
<customErrors mode="Off"> <error statusCode="404" redirect="/page-not-found/" /> </customErrors>
Note the mode, should be set to ‘Off’.
Second, you need to make sure the errorMode is set to DetailedLocalOnly. In most situations, this will be set to ‘Custom’ and will hide the IIS message.
<httpErrors existingResponse="Auto" errorMode="DetailedLocalOnly"> <remove statusCode="404" subStatusCode="-1" /> </httpErrors>
In case you are confused as to why your web.config require two sections, the section for dealing with error pages on an application basis deals with errors thrown by IIS. Both of these can hamper your investigation skills.
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. Under the hood, Episerver uses Log4Net as the log handling provider. As Log4Net is so flexible, changing the location of the logs is easy and usually for ‘best practice’ keeping the logs within the webroot isn’t advisable, so it’s only normal people change the log location. The problem with changing the location is that finding it can be hard. Instead, you will need to open up ‘EPiServerLog.config’ and find the ‘fileLogAppender’ file location property. This should point you in the right direction to find the log files.
Troubleshooting Your Episerver Website
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 your 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:
As .NET moves closer towards a Nuget based world, missing binaries is becoming less of an issue than it was a few years ago, however, if you need to get a legacy system working that uses something like Episerver CMO, then you may not have all the files you need to run your website in source control.
To get around this issue, you will need to get a working copy of your project from the staging/live server and then use Beyond Compare or some other diff tool, to compare the differences between the two bin folders. In a lot of cases, you might find missing assemblies that as soon as you copy over, fix the site magically. If you do find this an issue I would strongly recommend creating a ‘Libs’ folder in your solution and add all the missing assemblies in there and commit it to your source control repo. This will likely save you a lot of time and will also make the lives easier of any other poor developer who might come after you and face the same situation.
This is another fairly standard one. The site you build is reliant on more than just the CMS database. The best way to figure this one out is to go into the connection string settings, either in the web.config or in its own connection string file and check that everything listed in there is installed on your PC. I’ve worked on projects where the website needed to communicate to CRM systems, web APIs powered by separate databases, bespoke backend systems, even different Episerver products like the CMO which has it’s own databases. If these things are missing then it can easily kill your website.
Missing VPP Folders
The VPP system was made obsolete in Episerver CMS 7.5, however, for legacy requirements a lot of sites still use them. If you have a missing VPP folder, corrupt file content etc.. then your website can fall over. First, I would always make sure you make the latest version of your VPP folder from live/staging. Second, you need to make sure the project is pointing to the correct location. In your ‘EPiServerFramework.config’ config files, check where the ‘appData’ property is pointing and copy your VPP files to the appropriate place.
There’s no one size fits all advice to get every single Episerver website up and running as each website is a bespoke work of art and engineering. Like a custom motorbike, for example, each website has bespoke parts and design that make it a one of a kind. 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. It’s easy to sit in front of your site endlessly trying this and that and praying the site will work.
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. The more you understand the site and the errors being thrown, the more ideas you can generate to try and fix them. Good luck!