Gentoo Archives: gentoo-commits

From: "Joshua Saddler (nightmorph)" <nightmorph@g.o>
To: gentoo-commits@l.g.o
Subject: [gentoo-commits] gentoo commit in xml/htdocs/proj/en/gdp/doc: gorg.xml
Date: Wed, 28 Apr 2010 19:17:57
Message-Id: 20100428191753.02BA52C06E@corvid.gentoo.org
1 nightmorph 10/04/28 19:17:52
2
3 Added: gorg.xml
4 Log:
5 Added gorg guide to our stuff, after finding the raw unformatted text in the cached interwebs. neysx's site is down, and this stuff is too valuable to lose. i rewrote the guideXML and cleaned it up where necessary. inspired by bug 317609.
6
7 Revision Changes Path
8 1.1 xml/htdocs/proj/en/gdp/doc/gorg.xml
9
10 file : http://sources.gentoo.org/viewcvs.py/gentoo/xml/htdocs/proj/en/gdp/doc/gorg.xml?rev=1.1&view=markup
11 plain: http://sources.gentoo.org/viewcvs.py/gentoo/xml/htdocs/proj/en/gdp/doc/gorg.xml?rev=1.1&content-type=text/plain
12
13 Index: gorg.xml
14 ===================================================================
15 <?xml version='1.0' encoding='UTF-8'?>
16 <!DOCTYPE guide SYSTEM "/dtd/guide.dtd">
17 <!-- $Header $ -->
18
19 <guide>
20 <title>How to Install Gorg</title>
21
22 <author title="Author">
23 <mail link="neysx"/>
24 </author>
25 <author title="Editor">
26 <mail link="nightmorph"/>
27 </author>
28
29 <abstract>
30 This guide describes how to install and configure gorg.
31 </abstract>
32
33 <!-- The content of this document is licensed under the CC-BY-SA license -->
34 <!-- See http://creativecommons.org/licenses/by-sa/2.5 -->
35 <license/>
36
37 <version>1</version>
38 <date>2010-04-28</date>
39
40 <chapter>
41 <title>Introduction</title>
42 <section>
43 <body>
44
45 <p>
46 Gorg is a back-end XSLT processor for an XML-based web site. XML source files
47 are transformed and served on-the-fly. Output files and their dependencies are
48 cached. Its main features are:
49 </p>
50
51 <ul>
52 <li>Works with apache, lighttpd or webrick (ruby's own web server) </li>
53 <li>Uses efficient caching</li>
54 <li>
55 Generates consistent HTTP headers when several web nodes serve the same
56 content
57 </li>
58 <li>
59 Implements its own compression (aka mod_gzip), i.e. it does not rely on the
60 web server to compress its output
61 </li>
62 <li>Supports client-side caching</li>
63 <li>Your XSL can accept and write cookies</li>
64 <li>
65 Provides its own search engine (site indexing will be substantially updated
66 in a later version)
67 </li>
68 </ul>
69
70 <p>
71 Gorg allows you to serve your own local copy of
72 <uri>http://www.gentoo.org</uri>. It can use either a cgi or a fastcgi script
73 with apache or lighttpd, or even use its own stand-alone web server. Its name is
74 short for <b>G</b>entoo.<b>org</b> because it was created with Gentoo's site in
75 mind when it was felt that a replacement for AxKit was required.
76 </p>
77
78 <p>
79 Gorg has been tested on x86, amd64, alpha, sparc, ppc, mips &amp; hppa with the
80 following packages:
81 </p>
82
83 <pre caption="Test environment">
84 >=net-www/apache-2.0.55
85 >=www-apache/mod_fcgid-1.0.8
86
87 >=dev-lang/ruby-1.8.4
88 >=dev-libs/fcgi-2.4.0
89 >=dev-ruby/ruby-fcgi-0.8.6
90 >=dev-libs/libxml2-2.6.23
91 >=dev-libs/libxslt-1.1.15
92 <comment>(In the unlikely case you want to fiddle with gorg's own search engine)</comment>
93 >=dev-db/mysql-4.0.26 <comment>(up to and including 5.*)</comment>
94 >=dev-ruby/ruby-dbi-0.0.21
95 >=dev-ruby/mysql-ruby
96 </pre>
97
98 </body>
99 </section>
100 </chapter>
101
102 <chapter>
103 <title>Installing Gorg</title>
104 <section>
105 <body>
106
107 <p>
108 Define your USE flags to allow apache with or without mod_fcgi, or not depending
109 on how you want to use it. The <c>mysql</c> USE flag is only required for the
110 integrated search engine.
111 </p>
112
113 <impo>
114 You might have to keyword some dependencies for your architecture. You can
115 keyword the required packages or accept a foreign architecture. gorg has been
116 installed and tested on x86, amd64, alpha, sparc, ppc, mips &amp; hppa.
117 </impo>
118
119 <pre caption="Emerging gorg">
120 <comment>(<b>With</b> apache support)</comment>
121 # <i>echo www-servers/gorg fastcgi apache -mysql >> /etc/portage/package.use</i>
122
123 <comment>(<b>Without</b> apache support)</comment>
124 # <i>echo www-servers/gorg -fastcgi -apache -mysql >> /etc/portage/package.use</i>
125
126 <comment>(Check dependencies are available for your architecture)</comment>
127 # <i>emerge -pv gorg</i>
128
129 <comment>(Install gorg)</comment>
130 # <i>emerge gorg</i>
131 </pre>
132
133 </body>
134 </section>
135 </chapter>
136
137 <chapter>
138 <title>Configuring Gorg</title>
139 <section>
140 <title>Configuring apache</title>
141 <body>
142
143 <note>
144 You may skip this section if you are not going to use apache at all.
145 </note>
146
147 <p>
148 If you want to use fastcgi, which you should anyway, you'll need to add <c>-D
149 FCGID</c> to the <c>APACHE2_OPTS</c> variable in
150 <path>/etc/conf.d/apache2</path>.
151 </p>
152
153 <p>
154 Then, integrate the apache configuration directives from the provided sample
155 file <path>/etc/gorg/vhost.sample</path> into your own vhost configs, e.g.:
156 <path>/etc/apache2/vhosts.d/10_gorg.conf</path>. Comments in the sample config
157 file will guide you.
158 </p>
159
160 <p>
161 Finally, copy or symlink the (c)cgi scripts from
162 <path>/usr/lib/ruby/site_ruby/&lt;ruby-version&gt;/gorg/fcgi-bin/gorg.fcgi</path>
163 and
164 <path>/usr/lib/ruby/site_ruby/&lt;ruby-version&gt;/gorg/cgi-bin/{gorg,search}.cgi</path>
165 into your web site (f)cgi directories and check they are executable. You
166 should copy <path>search.cgi</path> only if you are going to use the integrated
167 search engine.
168 </p>
169
170 </body>
171 </section>
172 <section>
173 <title>Configuring gorg</title>
174 <body>
175
176 <p>
177 Create a copy of the sample config file <path>/etc/gorg/gorg.conf.sample</path>
178 named <path>/etc/gorg/gorg.conf</path> and <b>edit</b> it. Comments will help
179 you define your own parameters. You need to define at least your web document
180 root directory.
181 </p>
182
183 <p>
184 If you do not want to use the default <path>/etc/gorg/gorg.conf</path> config
185 file, you'll need to define an environment variable called <c>GORG_CONF</c> that
186 points to the config file.
187 </p>
188
189 <impo>
190 If you use caching, and it is recommended that you do so, do make sure that the
191 cache directory defined in your config file has proper permissions. If you use
192 apache, the apache user needs full access to that directory.
193 </impo>
194
195 </body>
196 </section>
197 <section>
198 <title>Getting the missing files</title>
199 <body>
200
201 <p>
202 Assuming you'll serve your local copy of CVS, or a copy if, or symlinks to it,
203 you need to download some files from the <path>dyn</path> directory.
204 </p>
205
206 <pre caption="Get the missing files">
207 <comment>(Go to your htdocs directory)</comment>
208 $ <i>cd /path/to/your/document/root</i>
209 /htdocs $ <i>cd dyn</i>
210 /htdocs $ <i>wget -O news-index.xml http://www.gentoo.org/dyn/news-index.xml?passthru=1</i>
211 /htdocs $ <i>cd ..</i>
212 <comment>(Do the same for any other data you may need from the /dyn directory)</comment>
213 </pre>
214
215 <p>
216 You also need to make the pictures available to your browser. The
217 <path>images</path> directory is one level above <path>htdocs</path>. Just
218 define a symlink to it and you're set.
219 </p>
220
221 <pre caption="Make a symlink to the pictures">
222 /htdocs $ <i>ln -si ../images images</i>
223
224 <comment>(It should look like this:)</comment>
225 /htdocs $ <i>ls -l</i>
226 drwxr-xr-x 3 neysx users 128 Sep 14 17:45 css
227 drwxr-xr-x 31 neysx users 744 Oct 26 00:03 doc
228 drwxr-xr-x 3 neysx users 544 Nov 2 16:53 dtd
229 drwxr-xr-x 3 neysx users 168 Nov 3 16:24 dyn
230 -rw-r--r-- 1 neysx users 1406 Jun 7 2003 favicon.ico
231 lrwxrwxrwx 1 neysx users 10 Oct 21 22:29 images -> ../images/
232 -rw-r--r-- 1 neysx users 190 Nov 9 2002 index.xml
233 drwxr-xr-x 16 neysx users 384 Apr 1 2004 main
234 drwxr-xr-x 17 neysx users 6960 Nov 3 15:34 news
235 drwxr-xr-x 8 neysx users 192 Oct 23 14:52 proj
236 drwxr-xr-x 4 neysx users 96 Sep 17 14:05 security
237 drwxr-xr-x 3 neysx users 736 Nov 2 16:40 xsl
238 </pre>
239
240 <p>
241 Your local CVS probably shows a few more entries, but at least those mentioned
242 above should be available and kept up-to-date. Also remember to keep your
243 <path>images</path> directory current.
244 </p>
245
246 </body>
247 </section>
248 </chapter>
249
250 <chapter>
251 <title>Running Gorg</title>
252 <section>
253 <title>The stand-alone web server</title>
254 <body>
255
256 <p>
257 The easiest way to try it out is to run <c>gorg</c>. It should display something
258 like:
259 </p>
260
261 <pre caption="Run gorg">
262 $ <i>gorg</i>
263
264 Starting the Gorg web server on port 8008
265
266 Hit Ctrl-C or type "kill 31479" to stop it
267 </pre>
268
269 <p>
270 Point your browser to <uri>http://localhost:8008</uri> and you should see your
271 favorite site.
272 </p>
273
274 </body>
275 </section>
276 <section>
277 <title>With apache</title>
278 <body>
279
280 <p>
281 Restart apache (<c>/etc/init.d/apache2 restart</c>) and visit
282 <uri>http://localhost</uri> assuming you're installing on your own
283 workstation.
284 </p>
285
286 <p>
287 If you used static fastcgi servers, you should see them with <c>top -u
288 apache</c>.
289 </p>
290
291 <p>
292 If it doesn't work, try the stand-alone web server (type <c>gorg</c>). If this
293 doesn't work either, check your <path>/etc/gorg/gorg.conf</path> config file. If
294 it does work, please check your apache config files and your logs.
295 </p>
296
297 </body>
298 </section>
299 </chapter>
300 </guide>