Building the docs site

This page describes the process to build the Publican-driven Fedora docs site, referencing the Publican 4.0 User Guide.

The site is based on an EL6 machine, pulling packages from the el6-docs repo in Koji.

0. Set up an el6 machine

For this test, I set up a fresh el6.5 Server machine.

1.1 optional subchannel

Activate the optional subchannel in RHN. Instructions here

1.2 EPEL

Install the EPEL repository $ sudo yum install http://dl.fedoraproject.org/pub/epel/6/i386/epel-release-6-8.noarch.rpm

1.3 el6-docs

Create /etc/yum.repos.d/el6-docs.repo with the following contents:

[el6-docs]
name=Packages for the Fedora docs site
baseurl=http://kojipkgs.fedoraproject.org/repos/el6-docs/latest/x86_64/
enabled=1
gpgcheck=0
cost=1337

Why the cost?
We need to add a cost setting to the repo, as the el6-docs repo is built in Koji in a way that it also contains the buildroot, so that some packages are duplicates of what are in the base repo. By adding a cost, we're telling it to try to pull the packages from the base repo first

1.4 httpd

Install the Apache web server by running: $ sudo yum install httpd

Next, allow port 80 web traffic through the firewall by adding the following line to /etc/sysconfig/iptables, right below the line that contains --dport 22:

-A INPUT -m state --state NEW -m tcp -p tcp --dport 80 -j ACCEPT

Next, let's restart the firewall: $ sudo service iptables restart

Then we can start apache: $ sudo service httpd start

Last but not least, let's make sure the httpd daemon is configure to run on system boot: $ sudo chkconfig httpd on

2. Install Publican

$ sudo yum install publican publican-common-web

PUG 7.2.1, step 3 NB: package names out-of-date

3. Configure the website

First, let's make a copy of the empty database file that Publican will use, and place it in the '/var/www' directory. (This author has a fundamental hangup about placing data under the /usr directory on a server.)

$ sudo cp /usr/share/publican/default.db /var/www/fedoradocs.db

Next, let's edit the publican website configuration file

$ sudo vi /etc/publican-website.cfg

For this test, I set:

# where will the content be published to?
toc_path: /var/www/html/docs
# Where are the templates to build the TOCs?
tmpl_path: /usr/share/publican/templates
# Where is the database?
db_file: /var/www/fedoradocs.db
host: http://path.to/your/server
title: "Fedora Documentation"
search: <p/>
dump: 1
dump_file: /var/www/html/docs/DUMP.xml
web_style: 2

Setting the host parameter
The publican-website.cfg file used in production should have the host: parameter set to the fully qualified domain name and path of your document root.

PUG 7.2.1, step 4 NB: web_style parameter undocumented

4. Install the homepage

$ sudo yum install Fedora_Documentation-web-home

PUG 7.2.2, step 3

5. Install a document

I built and installed the Fedora 20 Release Notes

$ sudo yum install Fedora-Release_Notes-20-web-en-US

PUG 7.2.4

Done!

The site is visible at localhost/docs/