QuarkNet Forums Directory Structure Forums (BOINC) Library (MediaWiki) Site Customization BOINC configuration Access Controls Style Sheets Wiki System Messages Wiki Skins

QuarkNet Forums

At the end of October, 2008, Marge asked Eric to set up a site to host forums and wikis for QuarkNet, independent of the ELabs forums and wikis. There's no good place to document this (yet), and since it is hosted on the ANL ELabs cluster it makes at least some sense to document the setup here. I will probably move these notes to the new QuarkNet wiki, once it is up and running. Or not.

The software used to support the forums is based on the BOINC forums, as used by Einstein@Home, SETI@Home, and other BOINC projects, but modified by Eric for I2U2 (and now QuarkNet). The changed code is kept in CVS at spy-hill.net. (I may set up a CVS server for this on the same machine, just to make version control easier.)

Directory Structure

The QuarkNet forum site is hosted on www10.i2u2.org (but we'll give it a different name). Here is the directory layout of the server:

• The web server and database software are all installed under /usr/local, and built in /usr/local/src/.
• The web server configuration is in /usr/local/apache/conf, with the site specifics in the subdirectory /usr/local/apache/conf/local.d in the file quarknet.conf
• The web content is all under /home/quarknet, with separate subdirectories for separate software components (for easier management).
• Web server logs are under /var/log/httpd, but could be redirected to /home/quarknet/log_www10/ if desired.

Forums (BOINC)

The discussion forums use the forum software from BOINC, which is under /home/quarknet/boinc. The files used to present web pages are in the html subdirectory (this preserves the directory structure used by BOINC and Bolt).

The BOINC html subdirectories are:

• html/user - presentation code (the stuff that generates the web pages)
• html/inc - supporting code (utilities and underlying functionalilty)
• html/user_profile -where user profile pages and UOTD are kept
• html/project - project-specific settings
• html/ops - control panel, for administration of the site (restricted access)
• html/cache - cached copies of important pages (unused for QuarkNet?)
• html/languages - support for other languages
  • html/languages/translations - translations of messages from English to other languages
  • html/languages/project_specific_translations - customized messages
  • html/languages/compiles - compiled form of the messages

The reason for html/project is to collect all project-specific settings in one place, allowing us to replace the entire contents of the user and inc directories as part of a software upgrade.

In addition to the usual BOINC directories above, we have added:

• html/include - custom support files which are not a part of the BOINC source code. These include additions such as forum attachments, debugging messages, reCAPTCHA support, expanded user roles.
• html/attachments - where we store files which are attached to forum posts. Must be writeable by the web server.
• html/upload_tmp - temporary directory for user files which are uploaded (for attachments). Must be writesable by the web server.
• html/user/view - forum attachment files are copied here for viewing
• html/user/img - image files (merge this with images ?)
• html/ops/usage - webalizer usage statistics
• html/user/graphics - images copied from http://quarknet.fnal.gov/graphics

Library (MediaWiki)

The "Library" for QuarkNet is a wiki implemented with the MediaWiki software, the same software used by Wikipedia (but not with their same open access and editing policies). This is on www10 in the directory /home/quarknet/library, with the following files and directories:

• library/LocalSettings.php - file containing all custom settings for the wiki
• library/DatabaseSettings.php - separate file containing database user/password info (do not store this in public CVS!). This file is included by the LocalSettings.php file.
• library/QNpermissions.php - file containing access controls (permissions) based on group membership, which in turn is based on user's role in the forums.
• library/extensions directory containing files or subdirectories to implement MediaWiki extensions (such as for BOINC co-authentication)
• library/upload - directory tree containing files (images or documents) uploaded to the wiki. Must be writeable by the web server daemon user (www-data on www10).
• library/skins - files supporting different display "skins"

Site Customization

Settings that let you configure the site and change appearance are collected into a small set of files, both to make it easier to manage and to make it easier to update -- you can then just drop in replacments for most files, keeping customizations separate.

BOINC configuration

The BOINC forum code has some settings (like turing account creation on/off) in the file config.xml in the top level directory, /home/quarknet/boinc. Keep in mind though that BOINC is a system for managing distributed computations, and the config.xml file is primarily for the computational side of the project. Still, it's necessary for the web site too, as in contains database access information and other web site settings.

The web site customizations are in the files:

• boinc/html/project/project.inc - main settings
• boinc/html/project/quarknet-stuff.php - for functions that are specific to the QuarkNet site.
• boinc/html/project/quarknet-roles.php - definition of user Roles, and supporting functions. But see also ../include/roles.php for generic functions for handling roles.
• boinc/html/include/ contains supporting files that are not a part of BOINC, for things like forum attachments and keywords, reCAPTCHA, debugging messages, Google Calendar display, and user roles.

Access Controls

This site has a roles-based access control system, which means that each user signs on to a unique personal account, and then they are granted permissions based on their role in the Virtual Organization. Only someone classified as Staff can visit the Staff area. Fellows are the only ones allowed to read and post in the forums (in their own areas). The few people classified as an Administrator or Developer can go anywhere and can cont rol the site via the control panel.

There is an elegant way to implement this, but I have not yet implemented it. Instead, becasue we use BOINC for the forums and MediaWiki for the Library we have to configure both to work together, and this is distributed over a few different files:

• boinc/html/project/quarknet-roles.php contains the definition of user "roles", which in BOINC are called "special users". The function user_has_role($x) can be used to test that a user has a particular role. The functions category_is_private($c), check_reading_is_allowed(,), and check_posting_is_allowed(,) all control the read/write access policies for the forums. Note that these functions refere to forum categories and rooms by their numerical database ID. This is awkward, but that's how it works.

• boinc/html/project/quarknet-stuff.php contains customized definitions of functions which restrict access to web pages in general, such as the staff area and control pannel. The function check_access_auth($path) controls access to the staff area (/staff) or control panel (/ops). This is invoked by page_head() which is used to build the header for every web page, so every web page is checked automatically for access authorization.

• boinc/html/project/BOINCAuthPolicy.php contains a function of the same name which provides a mapping from the "special user" roles in the BOINC code to "groups" in the wiki. Basically, this looks at the "special user" bits and assigns the user to a wiki group. Then read/write access to the wiki is granted based on group membership, in another file.

• library/QNpermissions.php is read in by LocalSettings.php to define group permissions for wiki users, based on the group assigned in the file BOINCAuthPollicy.php. This is where you can control who can read the wiki, who can write to the wiki, and who is given special permissions such as protect, patrol, rollback, move, and block. The technical details of how this works are documented in the User rights management page of the MediaWiki manual.

Style Sheets

The overall look of the site is controlled to a good degree (but not completely, alas) via Cascading Style Sheets (CSS). Since the style of the site is project-specific, we keep the files in html/project. But since that directory is not visible to the web, we make soft links from html/user to the files in html/project. Edit the files in the project directory, and they will be publicly available via the user directory.

Here are the CSS files:

• project/quarknet.css - main style sheet for the whole site
• project/front_page.css - additional style for just the main (portal) page
• ops/control_panel.css = style sheet for the control panel pages
• user/navbar.css - horizontal nav bar pull-down menus (not yet finished)

The style sheet for the wiki can be modified as described below, instead of editing CSS files.

Wiki System Messages

A good deal of the wiki configuration can be stored in the wiki, such as the contents of the navigation sidebar. Go to the page Special:Allmessages for a list of all system messages. Press the "Show only modified" button to show a list of only those items which do not use the default values. Of particular interest are:

• ''Mainpage'' - name of the main page for the wiki. We set this to ''Main_Page'', but note that this will be redirected by the web server to the overall main site page, not the main wiki page.
• ''Sidebar'' - the navigation sidebar at the left of every page. (The syntax is awkward. You enter the "innards" of links, but without the double square brackets.)
• "Monobook.css" - any style sheet definitions entered here are added to the style sheet for any page displayed with the Monobook skin (which is the default).

These "system messages" are all pages in the wiki in the "MediaWiki" namespace, so you get also view and edit them quickly by going to their pages directly. For example to change the sidebar edit the page MediaWiki:Sidebar.

Wiki Skins

Wiki skins allow you or the user to easily change the overall look and feel of the site. The default skin is called "Monobook". The files that create a skin are kept in a separate subdirectory, called skins.

You can make changes to the skin by altering the Style Sheet (CSS). For the entire wiki you can edit the page MediaWiki:Monobook.css. If this exists, it is appended to the style sheet for every wiki page.

If you set $wgAllowUserCss=true then users can also add their own modifications to the style sheet, by creating their own page User:Username/monobook.css (note the name is all lowercase here). This can add server load, but that's not an issue for us yet. It also provides a way users can screw themselves up. But right now it's turned on.

Eric has created two additional skins for I2U2, and they are also available here for QuarkNet. Both can be accessed automatically by replacing index.php in the URL with the name of the skin (eg. use body.php instead, which should just be a softlink to the file index.php

• kiwi - a simple skin with no wiki controls, for use in displaying glossary entries as a pop-up
• body - just serves the bare content of the article, with no wiki controls or decorations, and body tags removed. This is to facilitate using the body of the wiki article in a different web page (as a "mash-up").

It would be possible to develop a custom skin for QuarkNet which looks more like the other web pages, but the easiest way to do this would be to start with the Monobook skin and edit that, rather than creating a new skin from scratch.