Apache CMS FAQ

This space is intended to list frequently asked questions and their answers for the Apache CMS.

Question/Answers

What is the Apache CMS?

See http://www.apache.org/dev/cms.html

How do we get started for our project?

• Setup an area in your SVN space that matches http://www.apache.org/dev/cms.html#layout. See http://svn.apache.org/viewvc/river/site/trunk/ as an example

• File a JIRA issue with Infrastructure asking for to be setup on the new CMS. See https://issues.apache.org/jira/browse/INFRA-3181.

• Consider using http://svn.apache.org/repos/asf/incubator/stanbol/site/tags/initial-site-content/ as a start, otherwise begin trying things out.

Where do I get help?

Send questions via email to site-dev@a.o

How do I run the cms build scripts?

You can check out the scripts which can from be used to build your site here: https://svn.apache.org/repos/infra/websites/cms/build/. The perl script that generates the *.html site files from *.mdtext is build_site.pl. The build_site.pl script has some Python dependencies. The easiest easiest way to install these is to use the Python setuptools. First check your version of Python (python --version) and follow the instructions to install the appropriate set of tools from here http://pypi.python.org/pypi/setuptools

After the python setuptools are installed other python dependencies can be installed as follows:

• sudo easy_install Pygments

• sudo easy_install ElementTree (Not completely sure that this is needed)

• sudo easy_install Markdown

How do I publish generated docs (eg. doxygen)?

First place all your generated docs into a local directory, let's call it foo/. Next create a compressed archive of foo/ by running

• $ tar -czf foo.tar.gz foo

Then in the CMS navigate to the directory you'd like to add that directory to. Pull up the Edit screen and type "foo/" into the form field. Then hit <return>. Fill in the file upload widget by pointing it at foo.tar.gz, click on "Quick Commit", add a log message, and hit Submit. Wait while the staging site builds the docs, and when that process is completed click "Publish Site" and Submit. Please note that the name of the local directory must match the name of the directory to be added to the CMS.

The way to maintain this setup is to use the CMS to delete stale doc trees and replace them with fresh versions. By doing this using the web interface you will not need to fuss with the staging repo at all (unlike what happens when you try to do this using svn directly). It will just work.

More sophisticated projects should be capable of scripting this into their release packaging process. The requests to the CMS would look something like this (in perl):

• $ua = LWP::UserAgent->new(requests_redirectable => ["GET"]);

  $ua->default_header(Accept => "application/json");

  $ua->credentials("cms.apache.org:443", "ASF Committers", $user, $passwd);

  $response = $ua->head("https://cms.apache.org/redirect?action=delete;uri=$path_to_old_doctree_on_the_website");

  • ## be careful here, if you screwed up the uri above you could wind up deleting your entire site.

  $delete_uri = $response->header("Location")

  • or die "Missing Location header";
  $delete_uri .= "/" unless $delete_uri =~ m!/$!;

  $response = $ua->post($delete_uri, [ submit => "Submit", message => "nuking stale docs for new release" ]);

  die $response->status_line unless $response->is_success; $add_uri = $delete_uri; $add_uri =~ s!/delete/!/add/!; ## put new doctree into foo.tar.gz

  $response = $ua->post($add_uri, Content_Type => 'form-data', Content => [

  • submit => "Submit", message => "new doctree", commit => 1, file => [ "foo.tar.gz" ],

  ]);

  ## Then use the http://s.apache.org/cms-cli script to publish the site (once the staging build has completed).