From Fedora Project Wiki

 
(7 intermediate revisions by 2 users not shown)
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 machine.
+
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 22: Line 21:
 
baseurl=http://kojipkgs.fedoraproject.org/repos/el6-docs/latest/x86_64/
 
baseurl=http://kojipkgs.fedoraproject.org/repos/el6-docs/latest/x86_64/
 
enabled=1
 
enabled=1
gpgcheck=0</pre>
+
gpgcheck=0
 +
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 <code>--dport 22</code>:
 +
<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 30: 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 39: 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: /var/www/fedoradocs.db
 +
host: http://path.to/your/server
 
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'''
 +
 +
==4. Install the homepage==
 +
$ sudo yum install Fedora_Documentation-web-home
 +
 +
[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-Creating_installing_and_updating_the_home_page-rpm 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
 +
 +
[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-Installing_updating_and_removing_documents-rpm PUG 7.2.4]
 +
 +
==Done!==
 +
The site is visible at '''localhost/docs/'''

Latest revision as of 17:54, 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.

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: /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/