Building the docs site

From FedoraProject

(Difference between revisions)
Jump to: navigation, search
(1.3 el6-docs: Add cost, so that we don't conflict with packages from base repo)
(Add some notes and further documentation)
Line 5: Line 5:
 
==0. Set up an el6 machine==
 
==0. Set up an el6 machine==
  
For this test, I set up a fresh el6.5 Server machine and started httpd.
+
For this test, I set up a fresh el6.5 Server machine.
 
+
==1. Connect repos==
+
  
 
===1.1 optional subchannel===
 
===1.1 optional subchannel===
Line 13: Line 11:
  
 
===1.2 EPEL===
 
===1.2 EPEL===
$ sudo yum localinstall http://mirror.as24220.net/pub/epel/6/i386/epel-release-6-8.noarch.rpm
+
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===
 
===1.3 el6-docs===
Line 24: Line 23:
 
gpgcheck=0
 
gpgcheck=0
 
cost=1337</pre>
 
cost=1337</pre>
 +
 +
{{admon/tip|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 <pre>--dport 22</pre>:
 +
<pre>-A INPUT -m state --state NEW -m tcp -p tcp --dport 80 -j ACCEPT</pre>
 +
 +
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==
 
==2. Install Publican==
Line 31: Line 48:
  
 
==3. Configure the website==
 
==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
 
$ sudo vi /etc/publican-website.cfg
  
Line 40: Line 63:
 
tmpl_path: /usr/share/publican/templates
 
tmpl_path: /usr/share/publican/templates
 
# Where is the database?
 
# Where is the database?
db_file: /usr/share/publican/default.db
+
#db_file: /usr/share/publican/default.db
 +
db_file: /var/www/fedoradocs.db
 +
host: http://</pre>''path.to/your/server''<pre>
 
title: "Fedora Documentation"
 
title: "Fedora Documentation"
 
search: <p/>
 
search: <p/>
 
dump: 1
 
dump: 1
 
dump_file: /var/www/html/docs/DUMP.xml
 
dump_file: /var/www/html/docs/DUMP.xml
web_style: 2</pre>
+
web_style: 2
 +
</pre>
  
The '''publican-website.cfg''' file used in production should have the ''host:'' parameter set too.
+
{{admon/tip|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.}}
  
 
[http://jfearn.fedorapeople.org/en-US/Publican/4.0/html/Users_Guide/chap-Publican-Users_Guide-Building_a_website_with_Publican.html#sect-Publican-Users_Guide-Building_a_website_with_Publican-Building_a_website_using_RPM_packages PUG 7.2.1, step 4] '''NB: web_style parameter undocumented'''
 
[http://jfearn.fedorapeople.org/en-US/Publican/4.0/html/Users_Guide/chap-Publican-Users_Guide-Building_a_website_with_Publican.html#sect-Publican-Users_Guide-Building_a_website_with_Publican-Building_a_website_using_RPM_packages PUG 7.2.1, step 4] '''NB: web_style parameter undocumented'''

Revision as of 16:21, 31 March 2014

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.

Contents

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
Idea.png
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: /usr/share/publican/default.db
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

Idea.png
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/