Creating a virtual XWiki environment

Creating a virtual XWiki environment

Basic information

Virtual XWiki Environment

• A Virtual XWiki environment allows you to run two or more XWiki instances on the same server. Each XWiki Virtual Server has its own database, so (for example) you can have sensitive sales data on one Virtual Server, and public information on another.

Performance

• A Virtual Server configuration performs a lot better than having multiple XWiki Servers running on the same hardware. This is fairly obvious when you consider that each instance of a full wiki installation would make use of it's own resources (a significant portion of which is the actual XWiki application itself).
• As an example, the xwiki.com server farm - which uses only two clustered Java instances - currently runs over 8000 individual XWiki's (as of the last count). This number is growing on a daily basis! Granted, you will need decent servers for that kind of volume.. but that's just an example of available performance under the virtual setup.

• Words used to identify something specific which will be referred to later
• Suggestions - advice from the School of Hard Knocks
• Examples.

Requirements

The following is a basic outline of what you will need to have (or be able to have done on your behalf) in order to configure the Virtual environment. They are not exhaustive, but if you're answering no to these, you may not be able to complete your configurations.

• You will need a little bit of IT knowledge, or at least have access to someone who can help with the main technical aspects of this installation.
• Choose one instance of XWiki that has been installed on your network. We'll refer to this server as the controller for the Virtual XWiki's. The database name for your proposed main installation should be "xwiki".
  • If you've still got to install the XWiki instance, please refer to the installation guide and complete this step first.
  • You will need administrator access to this wiki.
• Able to add network forwarding to your network address. So you should be able to point, say abc.def.com to the same IP address as xyz.def.com; this is an important requirement.
• Root priveledges to your database, or ability to create new databases and assign permissions to the new databases.
• Able to restart the java container (eg tomcat or jetty), or can have this restarted on demand.
  • A file will also have to be modified, so you will need to have write access to the files on the server as well.

Setting up the Virtual Servers

Getting ready.

• Write down the IP address of your xwiki controller.
• Write down the database username that is used by the xwiki controller.
• Find out what domain name you can use for the servers to be subdomained from. Typical examples are us.bigcompany.com, smallercompany.co.uk, etc. You will need to obtain the full name of the server you are using, or the proposed name for the server (eg ourxwikiserver.us.bigcompany.com or ourxwiki.smallercompany.co.uk). I'll call this ourxwiki.yourdomain.com for the time being.
  • I would recommend asking for a unique name (not using the actual server name), as this will be easier to work with if you ever cluster the server, or if the server is replaced by another one. Remember, it's easy to update a network record; but not so easy to update everyone's links for a new server name. This is only a recommendation and is NOT REQUIRED to setup a virtual xwiki.
• Decide on the names of your Virtual XWiki server(s), and the controller. While XWiki will assume www.yourdomain.com points to your main xwiki, it is better in the long run to specify this too.
  • Example:
    • internal = internal.ourxwiki.yourdomain.com
    • public = public.ourwiki.yourdomain.com
    • sales = sales.ourwiki.yourdomain.com
• Warn your users (if the server is active) and schedule few hours downtime for the XWiki server. It won't take near that time, but this will allow you to test and make sure all showstopper issues are covered.

The installation.

• Backup all affected XWiki databases now.
  • If your backup is not working, delay these steps until you can get it working. This prepares you for a possible revert of the system if anything goes wrong.
• Create (or have created) network pointers for your virtual server domains. ALL YOUR VIRTUAL XWIKI DOMAINS MUST POINT TO YOUR XWIKI CONTROLLER IP ADDRESS. XWiki will figure out what to do with the request based on this data.
  • Example:
    • internal.ourxwiki.yourdomain.com
    • public.ourwiki.yourdomain.com
    • sales.ourwiki.yourdomain.com
    • Also make sure you are pointing ourwiki.yourdomain.com to the same server!! This will point to your main server; and is an important step

Wiki Manager

From XWiki1.1 you can use the Wiki Manager that will take care of what you find in By hand chapter.

Simply install Wiki Manager Plugin and Wiki Manager Application and follow instructions.

By hand

• Edit your database and add a new database for all virtual servers. Note that XWiki version 0.9.840 and below require a datbase to be setup. You can also use existing databases if you are simply combining pre-existing XWiki servers. The xwiki controller database username must be granted all permissions to the virtual databases if not already granted.
  • Example:
    • "xwikiinternal" for internal.ourxwiki.yourdomain.com
    • "xwikipublic" for public.ourwiki.yourdomain.com
    • "xwikisales" for sales.ourwiki.yourdomain.com
• In your Class Editor, create a new class called "XWikiServerClass".
  • Click "Edit this Class"
    • Add a string property called "server"
    • Add another string property called "owner".
    • This part depends on your own preferences. If there are enough people wanting more details I'll add to this document, but it's not necessary: To make this easier to maintain, you can create the template and class sheet details as per the examples at the FAQ tutorial.
  • Create a new page for each of your Virtual Wiki's (as well as your main controller, don't forget!!) based on the following format:
    • XWiki.XWikiServerThisdatabasename, where Thisdatabasename is the name of the Virtual Server database.
      • THIS IS IMPORTANT: the text for This databasename MUST have it's first letter CAPITALIZED. This is regardless of your database setup!!!!!!!
    • In each document, (assuming you did not create a special class sheet and template), you must attach the XWikiServerClass object.
      • Fill in the "server" field listing the server name for each of your servers
        • Example:
          • internal.ourwiki.yourdomain.com
          • public.ourwiki.yourdomain.com
          • sales.ourwiki.yourdomain.com
      • Fill in the "owner" field with the owner user of the Virtual XWiki; for example XWiki.Admin.
  • Stop your java container (eg tomcat or jetty).
  • Open the xwiki.cfg file on the physical server (located under xwikiWEB-INF) and modify the xwiki.virtual entry to be 1. If you are certain xwiki.virtual does not exist, you can create it.
    • It is useful to setup xwiki.virtual.redirect (in the line below the xwiki.virtual) to point to your main wiki. This avoids potential problems in future should you ever accidentally delete your main xwiki document
  • You can now restart Tomcat and test your new links. The main controller link should work straight away
    • You will notice that your main wiki should work without any additional configuration.
      • If your Virtual Wikis were created from already existing databases, then they should not need any work either.
      • If the Virtual Wikis are new, clean databases you may need to carry out an import of the .xar base setup files (for XWiki10B1 or above).

--Author's notes: This is a first draft attempt, basing some data on the FAQ entry in the old .org site. Please post a comment if there are any issues; or email the xwiki-users email list.