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 & 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 & 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/<ruby-version>/gorg/fcgi-bin/gorg.fcgi</path> |
163 |
and |
164 |
<path>/usr/lib/ruby/site_ruby/<ruby-version>/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> |