Creating a Custom DotNetNuke Install
Working with DotNetNuke in an environment where you have separate silos for development, unit testing, end-to-end testing, as well as production, means that you need to have a number of different DNN installations. My personal belief is that DNN, as provided by the DNN Core Team, isn't really meant to be tampered with if you want to have a quick upgrade path when the DNN Core Team releases upgrades. But there is something of an "exception" to my personal rule. Items can be ADDED to the Core Release, and certain items can be removed. Now that I'm making those personal allowances... Let me talk about how to create a custom DNN Install.
My first objective was to provide a basic install that can come up and run without any of the DotNetNuke "branding", and, instead, include our own how-to pointers, what-to-do-next kind of instructions etc. (For all the DNNers out there - keep in mind - this is for internal distribution, not some kind of repackaging for public consumption). We are adapting a lot of our existing best practices, alterations on the DNN practices, etc, so when a fresh install is loaded out there for a our developers and release managers, we want to remind them about what exactly is expected of them next... by making it a part of the initial host and portal installation... the directions stare them down.
Now - what benefits could this have for "Joe Developer" on the street... Simple - Save yourself grief and agony by preconfiguring your DNN installation before deploying it. Very helpful... And there are even ways to do this where you can "port" your local development version of your site as well... (I want to upgrade my personal DNN site at some point - I'll use this approach when I do so and write up something on it.)
Finally, as an architect, and someone who wants to ensure that there's a low chance of anything going wrong from silo to silo, this helps maintain a baseline to prevent issues from moving from silo to silo being attestable to a configuration anomoly with DNN... That's not to say it still won't be probable - but it won't be the first place to look. (I've been deep in the trenches before - I know the system is always the first to blame while you look for a code oversight... *grin*)
Quick caveat... this is DotNetNuke 4 on ASP.NET 2.0. All of this should certainly apply to DNN 3 - but I haven't done any testing on that - so don't go quoting the man behind the blog.
So the first thing I'm looking at is how does DNN determine which modules to load during initial installation? For those that are saying "huh? you can't pick or chose!" aha... yes you can. Its actually been a DNN project for some time and a couple of versions ago (3.?) it actually came true. But how do you do it? How do you exclude them?
My journey began with going through the DNN host and portal templates. Now - Walking through this very creative, straight-forward, and intuitive template generated a lot of ideas about the possibilities for customizing the DNN installation. The three adjectives I just used can't really relay how impressed I was with this template file. I am so used to seeing developers go and put all these funky non-sensical attributes, poor-naming, and multiple xsds and crap in their XML, and then not even make the document structure make sense. You've been there... The template XML structures are clean, easy to read, easy to understand, and well documented (check out the Host Template and Portal Template documents contained in the document library zip from DNN). Don't get too intimidated by anything in the template doc - and especially don't be intimidated by its size. Just read it node by node. We're all in this together - we'll get through it... and watch your partner - we never leave a man behind! . ... moving on...
the host template
The host template allows you to configure the host settings at install time. Almost every host setting available on the Host / Settings screen in DNN is available in the host template. The bonus available here is the ability to instruct the installer to create portals automatically. The <portals> node will help you with that. Now - you don't necessarily configure the portal in the host template... you call the portal template that will be used to create each of the portals.
The primary host template may be the one file within the DNN deliverable which you'll need to modify. The file is Install/DotNetNuke.install.config ... Everything in this file is configurable. Whether you want to modify some of these or not is another thing. But regardless - it is editable.. Now... A good developer makes a copy of this file and works off the copy. The weathered developer who has spent agonizing hours reworking or fumbling with files makes two copies. A copy of the original. And a copy that will become our new install template... and then when we're done COPY your custom template over the original... (DNN's XCOPY upgrade path will overwrite your new file in the original's namesake - so copying instead of renaming saves you grief and rework.)
As you open the template, you will see two elements that should stand out as "uh - don't touch". If you're not adding your own scripts to run instead of the DNN scripts - don't mess with the <scripts> element. Also - I consider the <version> element to be reserved for the DNN Core Team. I'll let them increment DNN version numbers.
Now - Some of the great places to start modiying the host template is the <superuser> element. Any dnn-er with any experience can tell you the default username and password for the host and admin accounts on DNN. Good security dictates that if you're going to be able to customize the starting point for these kinds of accounts - then customize away. What this will ensure for me in my work is that whenever a release manager needs to set up a new installation - if he forgets to ensure the host password is changed I don't need to worry that the system is exposed.
The <settings> element has all of the Host settings that could be set for a DNN installation. Each setting is its own easy-to-read element. Big recommendation here - READ - Read the document that comes with DNN for more information here. Some of the things I am customizing, other than HostURL and some of the other obvious ones is <HelpURL>. We have our own best practices site internally where all kinds of help will be - and we'll link over to all the DNN doco, important forum topics, etc. So for us - this works well. And again - every new host we set up will have this without further configuration. SMTP server settings are another feature we will look to configure - big reason being - not every developer knows what that entry needs to be without looking it up. One of my objectives in my job is to simplify the life of the developers here - so - simplify away. It's a very small detail - but its the details that will slow you down every time - especially if you have to go hunt that information down.
The next node after <settings> is <desktopmodules> ... now - from what I can tell the need for this has been eliminated since the modules that come bundled with DNN no longer come delivered in their install points. So from a Host template standpoint - don't put any of your install-deployed modules here. I'll get to how to do that in a moment.
That brings us to the <portals> node. This is where you define which portals to create at install-time. Each portal you configure in it's own <portal> node and specify some of the unique attributes for the portal, like the portal name, the administrator account to create, portal aliases, etc. The most important child node for <portal> is the <templatefile> node. This is where you'll specify the more detailed specification for the portal.
Some fun ideas here - create your own help portal template that installs with each dnn install along with a starting site. Create a portal that maybe lays out all of the host modules in a bit more friendly format for your release manager. Anything where you want consistency between installs - your opportunities here are pretty nice. Now - if you're packaging for an initial production installation - this could prove to be a critical place where your portals are configured.
the portal template
The portal template allows you to configure the portal settings for a new portal, as well as create tabs, create modules on the tabs, and even set your skin for the tabs, portal, and containers.
So, Bill, are you telling me that I can define an entire portal structure in an XML file?
Yes.... Yes I am.
But Bill, doing all of that in XML could take a lot of time!?
Ah - I'm getting ahead of myself. But if you want to create a basic "starter page" this isn't a big deal. I'll talk more to pre-configured sites in a bit...
So the portal template gives you a way to pre-package a portal. DNN actually comes with a handful of these. A "Club or Organization Site" template.. the default DotNetNuke template... the Personal Site template... and the Small Business Site template. Now - a resourceful individual that has more time than myself could create e-commerce modules and then create a new E-Commerce template. These templates can be added to after your host is installed - so there isnt as much of an "oh - I have to wrap this up in my install" kind of urgency. However - in this case, I dont want to modify an existing template because DNN's XCOPY deployment would overwrite my edits when I upgrade DNN. So feel free to create your own templates here - copy an existing one if you want - whatever makes you comfy.
I want to create a portal template up front that will have all of my "corporate" starter elements. Again - there's a <settings> node with the ability to configure most of the portal settings. Following the <settings> node is the <roles> node. DotNetNuke allows you to configure portal-level roles for a new portal as it is created. The defaults work well in a basic database-driven authentication mode. However, if you're working with Active Directory and have mixed or AD-only authentication, you may want to tailor these to your primary groups within Active Directory. (In any AD-auth mode you can synchornize the groups a user is in within AD with their groups in DotNetNuke as long as the group names are the same.) So, for me, certainly some benefit since I can create some DNN roles that map to AD for those portals that are used internally... and I can do this once and the developers don't need to worry about including any common roles like a help-desk group that should be able to get in and verify a site is working.
After we have determined which roles we're going to create for our new portals that use this template, we can determine which tabs or pages should be created by default. Configuration of the page is much like what we would configure in the Page Settings screen, the name of the page, a parent page, if needed, the skin to be used, the container to be used, and even the permissions to assign to the page. Then we can configure which modules to place on the page and on which pane... and if our module supports the IPortable interface which allows for export and import of content, you can even specify which content to include in the module. This is some pretty powerful functionality right here. And for those developers who blow off the IPortable interface - right here - look right here - this is why it is important.
But Bill, we're still writing a LOT of XML to get this all configured. You said there's an easier way?
Yes there is. Log in to DotNetNuke as SuperUser / Host. On the Host menu, select "Portals". On the portals screen is the option to export a portal to a portal template... select the portal you want to use as your template, provide DNN with a filename and description, and finally, select whether or not you want to include content in the export. (Again, that's where IPortable comes in as far as exporting content from an existing portal.) After clicking "Export Template" DNN will create your template and save it to the server. In my case I received the message below..
The Portal Template Has Been Created to c:\hosting\webhost4life\member\wknaus\Portals\_default\cozysite.template
back to installing modules at install-time
Remember how I started my little journey of knowledge - I wanted to figure out how to pick and choose which modules get installed automatically with the host installation. This was a bit of a long trip - and I did find it. On the way, I found all the fun you can have with portal and host templates.
The modules, like IFrame, Text/HTML, etc have been ripped from the base DNN installation. However, they haven't been ripped from the actual DNN install process. Allow me another paragraph while I explain a cool detail of the base installer...
The base installer (actually, upgrader) in DotNetNuke will go through your host template and will use the portal templates you specify for any portals you want to create as specified in the host template. And you can use the host template to specify any of the module configurations that need to be added to the database and install-time. The base installer also includes an unheralded feature that will allow you to include any packaged Skins, Containers, or Modules in your base installation simply by including the .zip file in the right directory under /Install. Zip packages for modules you want to include in your default install should be placed in the /Install/Module/ folder. The DNN core team has included the "Private Assembly" version of your favorite DNN basic modules in this folder (go ahead, take a look, we'll be here when you get back)... Modules you will not find here are the three DNN project modules, blog, forum, and gallery. At install time, (i'm still researching "upgrade-time") the installer framework within DNN goes through each of these folders and processes their contents. Container, Language, and Skin folders make sense - zip packages for each of those. I'm still looking at how the Portal, Scripts, and Template folders under Install work. (I'll write a follow-up later and post a link in comments.)
If you've read all the way to this point and you're simply looking for how to strip the basic DotNetNuke modules from being installed, let me simplify. Prior to running your site for the first time, hence running through the install script and causing the default modules to be installed, go into the /Install/Module/ folder and remove the .zip files for the modules you wish to remove. It is actually simple if you don't get carried away with the basic install instructions. This works for all three ways for obtaining DotNetNuke, Install, Source, and Starter Kit. In the case of the starter kit, once you create your web site project - stop - delete the zip files from the project (permanently delete, not just remove) - then continue with the directions.
now, why is this all relevant?
So let's discuss a scenario a bit out of my own ball park but relevant to a number of DNN hosters. Say you're a web service provider that supports or wants to support DotNetNuke for your customers. In order to make DNN hosting attractive to your consumers, you buy one or two e-commerce modules from Snowcovered, bundle in the blog, forums and gallery projects from the DotNetNuke crew, download some of the community developed modules for news articles, who is online, that kind of deal... You now have an attractive set of modules to go along with your DNN install. You do the same for skins - buy a few, include a few. Finally, you get a bit more into coding (or hacking depending on your skill level and maybe some of the code already at your disposal) and create your own admin modules to allow your customers to manage things like their e-mail accounts, help desk tickets, etc and package each up in DNN fashion. Then you create a number of portal templates... an e-commerce portal, a community portal, your own twist on the small biz portal, and, for the gamerz, a clan portal. You can create a single custom installation of DotNetNuke with your module, skin and container packages, your modified host template, and your portfolio of portal templates... and for each of your customers run the same installer inside their web space for them, and the most you have to configure are the databases and connection strings in web.config... as well as your NTFS permissions (the number one cause of headaches for first-time, second-time, and third-time installers of DNN). The web service provider scenario is, or can be, a very real scenario for those companies that support DNN.
DotNetNuke provides this power to create a very unique product for your customer - whether they are end-user newbies that want a pre-loaded DNN install, or skilled developers which can now forget about the installation minutae and focus on developing modules and portals.
If you got something from this and have a specific question - leave a comment - and I 'll be happy to reply and help you out. Let me know what you think of this article, the information, the usefulness, and whether you'd like me to write another article on a specific topic found above. Thanks!