NOTE: This is a SupplementalDocument topic which is not included with the official TWiki distribution. Please help maintain high quality documentation by fixing any errors or incomplete content. Put questions and suggestions concerning the documentation of this topic in the comments section below! Use the Support web for problems you are having using TWiki.

New TWiki Admin Steps

Introduction

I'm creating this as a separate topic for now to get feedback. The content can later be refactored into appropriate topics as needed. This is based on my own experiences of setting up a TWiki installation in a corporate setting (intranet) with the expectation of using some sort of authentication (like LDAP). We first attempted a Windows install, it never worked, we went to a SunSolaris machine instead which does work for the most part (but it still has some issues).

This is based on the version we are currently running (TWikiRelease04Sep2004). I haven't upgraded yet in part because I haven't finished figuring out the old version! I want to make sure I have a working configuration and figure out how to maintain the customizations to the documentation that I've already made before upgrading. Plus, politically it just isn't good timing. I'm not a server admin and the server admin who is handling that end of things for us is doing this on a volunteer basis and is not a member of our department. We just got our TWiki installation setup in early January 2006, so it is too soon to ask for a potentially troublesome upgrade. Our server admin person isn't always quick to respond or overly cooperative as is. This installation is just a "proof of concept" anyway so that I can get appproval for funding for our server and a server admin who will dedicate more time to this project.

Step One: Customize Structure and Content

I first added an additional web (beyond the Main, TWiki, and Sandbox webs that come as part of the install) to be our primary content container. I also changed the colors defining the webs (used in YouAreHere and the Site Map) a bit.

I have not yet changed edit permissions on anything since this TWiki install is not yet "public" to others in the company (anyone who knows the exact address of the site can get to it, but I'm not really worried about people stumbling across the site and messing things up at this point). However, I plan to change permissions to prevent editing by non-Admins for quite a few topics, especially any topics which have settings for variables, preferences, etc.

I customized most of the topics that came as part of the distribution. These are just some of the examples:

Topic Customized	Type of Customization
AdminTools	Added sections with links to YouAreHere, every WebLeftBar topic (all webs), the template pages such as WebTopicEditTemplate, WebTopBar, etc. and other topics that need lots of customizing in the beginning of a TWiki deployment.
PeterThoeny	Added a note at the beginning to indicate to the internal users more about who PeterThoeny is, why his name shows up all over our internal Twiki site, and a comforting notice that no, PeterThoeny does not have access to our internal site.
TWikiEnhancementRequests	Put a note in to make more obvious that it is a link to the TWiki.org site for TWiki enhancements and that if they want an enhancement specific to our site they should contact me.
WebLeftBar	I made the appearance consistent across webs. Also, while I didn't change the actual names of WebTopicList and WebIndex, I changed the links from WebLeftBar to say TopicList (detailed) and TopicList (brief) as well as added a brief explanation to those pages about the naming differences. This just helps users figure out which version they want to look at and makes both easily accessible from the WebLeftBar. In addition, I of course changed the TWiki.org link at the very top to say the name of our own site.
Main	I added some content to the very top that explained the difference between a wiki in general, TWiki in particular, and our particular TWiki installation in order to decrease confusion about the relationships between the three.
TWikiLogos	The old set of logos came with our TWiki install and I wanted to use the updated logos in a few places (such as the really tiny one in the "This site is powered by..." declaration. So I renamed the original topic to OldTWikiLogos and copied the new one from TWiki.org over.

Step Two: Configuration of Plugins, Authentication, & Authorization

I've attempted to install/configure the LdapPlugin, but I haven't been able to make this work yet. I need to find someone in my company who knows some perl and/or more about Ldap to figure it out for me. I'm not a perl programmer and while I have an email from someone internal with the ldap settings specific to my company, I may have something wrong and not realize it. Further, there is still the problem that using Ldap will only authenticate someone, it won't translate Ldap groups into Twiki groups very easily for authorizing. To do that requires perl programming. Then of course there is the problem of making sure that someone who hasn't registered yet can't edit as TWikiGuest. I got a bit of code from SteveRJones to handle this problem (he mentions it in ApachePasswordsUnix2). So I'll have to wait until I've proved my concept and can get funding to tackle these problems. Until then I'm using BasicAuthentication, i.e. remembering who people are based on their IP address. But in the long run this must all be working in order to have company support.

Some topics that have helped me at this stage: ApachePasswordsUnix2, GroupManagementTools, LdapAuthenticationHowTo, LdapGroup, LdapPlugin, LdapPluginDev, ManagingUsers, TWikiUserAuthentication, BasicAuthentication

Step Three: Creation of TWikiForms

I've had trouble with TWikiForms. I wanted to use a BasicForm like TWiki.org uses for generating important TWikiMetaData that I could use in improving searches etc. See my help question at MetaDataBreaksWithNewTopic for an updated status on this problem. Once it is fixed and I can use it in the way I describe in my Support question, I think this could potentially be a good customization. I would eventually like to create other TWikiForms for use in my TWiki install as well.

Some topics that have helped me at this stage: BasicForm, BasicFormHowTo, FormsConfusion, TWikiForms, EditingMetaDataViaUI

Any Additional Important Notes

One of the things that really confused me when I first started was how to go about changing settings. I'm more accustomed to a traditional software model and was expecting to need to set important site preferences in the backend somewhere like in TWiki.cfg. It took me a surprisingly long time (days) to figure out that the way to make changes to settings was to edit the topic they are in. See my comments on TWikiPreferencesComments for more details on this.

Another confusing thing for me was figuring out which topics I needed to go to for changing which types of settings. For instance, it took me awhile to figure out that the topic to change the appearance of the left navigation bar was WebLeftBar. As I figured these things out, I added them to the AdminTools screen so that I could easily locate them again in the future (and added a link to AdminTools in the MyNameLeftBar topic so that it would show up in the My Links section of the left nav bar). This is why I have sections on Template pages and WebLeftBars, as well as links to the Site Map and YouAreHere in my AdminTools topic.

Some topics that have helped me at this stage: InstantEnhancements

Suggestions

As you can see, I've had some difficulties with several aspects of this whole process. This topic is not necessarily meant as a means of finding solutions--I know the Support web is for that purpose. This is merely to demonstrate some issues that new admins will experience, some pointers in the right direction, and a call to improve the existing documentation.

I think this is a pretty good start to this topic. Please add your own thoughts on information that new Admins should know that is currently spread out in a hundred different places and should be pulled together in one central topic. I'll add to this myself as I think of things. I think ultimately this should involve a massive overhaul of the TWiki Distribution documents, a task I'm more than happy to do if it saves someone else time and effort. Interestingly enough, I stumbled across a useful topic today (Feb 14, 2006) in the Sandbox of all places: TWikiConfigs. It looks like the start of a useful document for new admins. Perhaps something like this could be updated and included as part of a package for new admins. I know I haven't added links to some very basic and important topics for beginners (I can even think of a few now--like the TWikiAdminCookBook) but they can be added as we go along. My hope is that eventually these tips/suggestions/whatever will eventually be incorporated into improved documentation.

-- Contributors: AmandaSmith

Comments & Questions about this Supplemental Document Topic

I used the "I" form because some of it was specific to my approach. Plus, I plan on refactoring it with any additional comments later on, at which point the form will change anyway. Thanks for adding the header/footer text for me. I haven't been around long enough to really know how folks here want to categorize things.

-- AmandaSmith - 15 Feb 2006

Thanks Amanda for contributing this. I added the standard header and footer text for SupplementalDocuments. For these docs it is better to use neutral form instead of "I".

-- PeterThoeny - 15 Feb 2006