From Fedora Project Wiki

 
(16 intermediate revisions by 2 users not shown)
Line 2: Line 2:


The site is based on an EL6 machine, pulling packages from the [http://kojipkgs.fedoraproject.org/repos/el6-docs/latest/x86_64/ el6-docs repo in Koji].
The site is based on an EL6 machine, pulling packages from the [http://kojipkgs.fedoraproject.org/repos/el6-docs/latest/x86_64/ 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 [https://access.redhat.com/kb/docs/DOC-11313 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:
<pre>[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</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==
$ sudo yum install publican publican-common-web
[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 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:
<pre># 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
</pre>
{{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'''
==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/