The first rule of CWIKI is don't link to CWIKI! This Confluence site is autoexported to HTML. Please link only to the exported pages. Do not link directly to the wiki! The autoexport includes live links to allow easy editing of pages. By linking to the autoexport, we can scale the site for everyone's benefit.

• This Confluence site is maintained by the ASF community on behalf of the various Project PMCs.
• Each Confluence Space is managed by the respective Project community.
• Some Spaces may be open to contributions to all Confluence users. To register, follow the Log In link at the top right of any page.
• Confluence users can watch a Space to to receive notifications any changes, or receive a daily summary of all changes to the site. After logging in, follow the "Profile" link for details.
• Some Spaces are being used to create the Project documentation. Editing access to such Spaces might be restricted to Project committers or individuals who have filed a Contributor's License Agreement with the ASF.

Many thanks to Atlassian Software Systems for providing to the ASF a free license for this site.

FAQ

Is this the only ASF wiki?

There are two wiki systems in use at the Apache Software Foundation. One uses moin-moin (Python), and the other Confluence (Java).

The Confluence wiki has more finely grained permissions. Some groups are using it to create official project documentation by restricting access to committers and contributors who have filed a CLA. Other spaces that do not represent the official documentation are open to all Confluence users.

The Confluence wiki is autoexported to static HTML whenever edits occur, so that high-volume serving can be done. The look-and-feel of the autoexport can be changed, and some projects are working toward making the autoexport site look just like their main website.

Confluence also supports commenting on pages, which can be an interesting way to help build up a community. Even if a site is restricted to CLA-equipped authors, other people can still leave comments.

Shouldn't we use Apache-licensed software for our wiki?

Actually, quite a lot of the support software we use is not under the Apache License. In the case of Confluence, Atlassian provides the ASF and other open source organizations a free license, as their way of giving back to the open source community. JIRA and Confluence are built with quite a number of open source products. When we use Confluence, we are in fact "eating our own dog food" – only baked into a pie!

Who should we tell if the Confluence site is down?

File a ticket for the Confluence component or ping the infrastructure mailing list. In the meantime, the autoexported site will provide access to existing content.

How do we request a CWIKI Space?

• New Spaces can be created upon request from a ASF Project PMC
• File a ticket for the Confluence component.
  • Include the cwiki account name of a PMC member (preferably the PMC chair) who will help administer the space.
  • Also specify the key name for the Space. The key name cannot be changed.
    • If you use JIRA, you might want to use the same key name.
• When the Space is created, a $project-committer group (or equivalent) will also be created with full rights to the Project's Space.

Is this site backed up?

Yes, everything (MySQL, attachments, Tomcat config) for JIRA and Confluence is backed up locally and remotely to ajax. It's documented at:

https://svn.apache.org/repos/asf/infrastructure/trunk/docs/backups_issues.txt

JIRA and Confluence are downloadable (after a signup form) from www.atlassian.com. We have customized the JIRA source a bit (mainly the attachment copyright stuff), but this isn't crucial to have. The customized JIRA source is checked in at svn+ssh://issues.apache.org/var/local/svn/asf-jira/trunk/. Running 'maven' results in a JIRA webapp ready to go with all the relevant plugins.

Can we use the autoexport site as part of our main web site?

Only if everyone working on the autoexport site has a Contributors License Agreement on file.

But, otherwise, yes.

Each project has a folder on people.apache.org (minotaur) that is used as a staging area for the main websites. All of the autoexport sites are already being mirrored (via rsync) to a directory on p.a.o. All that's left is to rsync it again to your website staging folder.

The website folders are restricted to the members of each project group. A member from your project group must setup a cron job to mirror your autoexport site to your website folder. To do this

1. ssh to people.apache.org

   ssh people.apache.org

2. create a folder for your autoexport site under your website folder

   mkdir /www/$HOST.apache.org/$SPACE

3. add a rsync command using crontab

   crontab -e
   0 * * * * (/usr/local/bin/rsync -r /www/confluence-exports/$SPACE/ /www/$HOST.apache.org/$SPACE)
   <esc>:wq

where $HOST equals your project host name, and $SPACE equals your cwiki space name.

Can we use the mirror of the autoexport site as our main web site?

Yes. You can either name the home page for your site "index", so that it will load by default, or add a index.html to the root website folder that will redirect to the export folder.

<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN">
<html><head><META HTTP-EQUIV="Refresh" CONTENT="0;URL=./$SITE/home.html"></head>
<body><p>Loading ...</p></body>
</html>

Keeping the autoexport in a subfolder is recommended, since this leaves a place to store other files that might not be part of the autoexport.

If we use the wiki to maintain project documentation, are there any special considerations?

If you are using the cwiki Space like most projects use moin-moin, then you can set the edit rights for the space to Confluence users. Most projects use moin-moin like a sandbox or whiteboard, that is provided to the community as an online convenience.

Projects do not typically bundle a copy of moin-moin into a release. If you do plan to bundle a copy of the autoexport site into a release, then the requirement is that a Contributors License Agreement be on file from everyone who contributed anything greater than an incidental patch, to either the code or the documentation.

You must also update your autoexport theme to include the standard notice as a HTML comment.

<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
<!-- 
Licensed to the Apache Software Foundation (ASF) under one
or more contributor license agreements.  See the NOTICE file
distributed with this work for additional information
regarding copyright ownership.  The ASF licenses this file
to you under the Apache License, Version 2.0 (the
"License"); you may not use this file except in compliance
with the License.  You may obtain a copy of the License at

 http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing,
software distributed under the License is distributed on an
"AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
KIND, either express or implied.  See the License for the
specific language governing permissions and limitations
under the License. 
-->
<html>

The autoexport theme for each space can be edited through the AutoExport Plugin Configuration.

But what if we would like the community at large to help maintain the space?

If by "community at large", you mean any random passerby, and you plan to bundle the documentation into a release, then the answer would be no. If by "community at large", you mean people who take the trouble to file a CLA, then the answer is yes. But, you will need to be sure they have filed a CLA before granting edit access. Any ASF Member or Officer (including your PMC Chair) has access to the list of people who have filed a CLA with the ASF. Again, the touch point is whether you want to reserve the right to bundle the documentation with a release and/or check a copy into an ASF repository.

An individual person contributing documentation in this way is not required to be a "committer", but he or she does need to file a CLA, so that there is no doubt that the individual intends to contribute the copyright on the documentation to the ASF. Of course, whenever anyone makes "welcome and sustained contributions" to the documentation, it is appropriate to invite that person to become a committer and PMC Member, and share in the decision making.

One strategy is to allow confluence-users Comment Create rights. In this way, someone can at least leave a note about changes that could be made to a particular page. Incidental comments about a page would not require that a CLA be on file.

Projects can also setup multiple Spaces. One Space, open to all users, can be used as a conventional wiki. Then another Space with restricted editing permissions can be used to create the Project documentation.

Can we download a snapshot of the site to include with our distribution?

Since the site is on people, you can always obtain a copy by scp. A faster alternative is to use a cron job to zip up the site, so that you can download it as single file. For zip to work correctly, it should be fired from a shell script.

# Shell script to zip up site
cd /www/$HOST.apache.org
/usr/local/bin/zip -ur $SPACE.zip $SPACE/*

Mark the script executable (chmod u+x $SPACE-zip.sh) and add it to your cron jobs

crontab -e
* 0 * * * (/www/$HOST.apache.org/$SPACE-zip.sh)
<esc>:wq

Do not bundle a copy of a Space into an official distribution unless all of the content has been donated to the ASF and we have the appropriate CLAs on file!

Infrastructure Notes

The Confluence runbook is available (via secure access only) as a plain-text document in Subversion.

The CWIKI infrastructure is maintained by volunteer members of the Project PMCs using the site.

Please file a JIRA ticket to document any administrative changes that affect the installation rather than an individual space, such as installing a plugin. If appropriate, please also update this page.

Standard Groups

confluence-users	Any registered user
confluence-administrators	ASF PMC members helping with CWIKI administration
asf-cla	Users known to have a Contributor's License Agreement on file with the ASF
*-committers	Committers helping to administer a ASF Project Space

Projects may create other groups to fill special access needs.

Adding a Project Space

• New Spaces can be created upon request from a Project PMC
  • The PMC member requesting the site must have a CWIKI account setup. The request should include a keyname for the Space.
  • If the PMC uses JIRA, it makes sense to use the same Confluence space name and JIRA project name.
• Create a $project-committers group
• Add the PMC member requesting the Space to $project-committers and confluence-administrators so so that he or she can grant karma to other committers and create any other project groups or spaces on behalf of the project PMC.
• Create the Space.
• Give the $project-committers groups all rights to the Space.
  • As a fail-safe, it is strongly recommended that the confluence-administrators group also be given all rights to the Space.
• Give the confluence-users View, Export, and Comments-Create access (optional).
• Give the autoexport user view-only access to the site (required!).
• Remove the individual rights granted to your account by Confluence when the Space was created.
• Grant View and Export only rights to Anonymous. You may also allow anonymous users to comment, and they will have to respond to a Captcha prompt, to avoid spam.
• Goto Plugins, and Autoexport the initial site.
• From the Project website, link only the autoexport site.

Posting email alerts to a mailing list

One approach is to create a role account ($project-group) and use your project's moderator privileges to subscribe the account to your commits@ list. The profile for the account can be setup to watch the project space. The account will need confluence-user karma, because without at least that, the system wouldn't send the alerts. Some projects find the change-by-change reports to be so verbose as to be unhelpful, and so set the account to send daily summaries instead. Since the account is posting to an ASF mailing list, the emails should be in plain-text rather than HTML.

If the initial notifications from Confluence do not appear in your list's moderation queue, ask infrastructure to check for a "ezmlm-reject" line in the list's configuration, and remove it if present.

Installing Plugins

Any Confluence Administrator can install a plugin from the administration area in Confluence. Please file a JIRA ticket when installing or updating a plugin, to keep everyone apprised.

Restarting Confluence

If Confluence is down, first check the ASF Public Network Status page. If the service seems to be down, but Monitoring reports it as OK, then please email infra@ or post a JIRA ticket.

If the Monitoring status is showing that the service is offline, then the appropriate people have already been contacted. If the service stays offline for 24 hours, then please file a JIRA ticket.

opie

(For system administrators only) After executing a sudo command, the system will prompt for "Response"".

This is opie, a one time password tool. It lets you enter your password on your local machine (never going over the network), then the opiekey tool gives you a password that only works once, which you enter on the server (over the network).

To use it (and you should be, all ASF infrastructure people should be using opie instead of their regular passwords), you need to run opiepasswd on the server to set your password, then get an opie key tool (the unix command line tool is called opiekey). The man page for opiekey gives you a good example of how it's used.