~ubuntu-branches/ubuntu/natty/moin/natty-updates

« back to all changes in this revision

Viewing changes to wiki/underlay/pages/HelpOnInstalling(2f)ApacheOnLinux/revisions/00000001

  • Committer: Bazaar Package Importer
  • Author(s): Jonas Smedegaard
  • Date: 2008-06-22 21:17:13 UTC
  • mto: This revision was merged to the branch mainline in revision 18.
  • Revision ID: james.westby@ubuntu.com-20080622211713-inlv5k4eifxckelr
ImportĀ upstreamĀ versionĀ 1.7.0

Show diffs side-by-side

added added

removed removed

Lines of Context:
 
1
## Please edit system and help pages ONLY in the master wiki!
 
2
## For more information, please see MoinMoin:MoinDev/Translation.
 
3
## page was renamed from HelpOnInstalling/ApacheOnUnix
 
4
##master-page:Unknown-Page
 
5
##master-date:Unknown-Date
 
6
#acl -All:write Default
 
7
#format wiki
 
8
#language en
 
9
This page describes the particular steps that need to be taken to create a wiki instance using MoinMoin on Linux with the Apache web server. '''You should have already performed the ../BasicInstallation. '''Installations on other Unices like FreeBSD are very similar.
 
10
 
 
11
On this page two installation scenarios are discussed:
 
12
 
 
13
 1. You have '''Administrator Rights '''(you are user 'root' or may use sudo)  for a server and are able to install and modify files almost anywhere on the machine, and notably able to modifiy the Apache configuration.
 
14
 1. You are a '''Simple User,''' only able to write files into your home directory, and unable to alter the master Apache configuration file.
 
15
 
 
16
The following options are not mentioned here:
 
17
 * using '''suEXEC'''
 
18
 * using '''FastCGI ''' (see ../FastCgi)
 
19
 * using '''mod_python''' (see ../ApacheWithModPython)
 
20
 * setting up a '''Root Wiki''' (see HelpOnConfiguration/ApacheVoodoo)
 
21
 * For more advanced configurations and some tricks see also HelpMiscellaneous.
 
22
 
 
23
 
 
24
'''Table of contents''' <<TableOfContents>>
 
25
 
 
26
== Administrator Scenario ==
 
27
The exact location of the various Apache configs varies - often used locations are: {{{/etc/httpd/, /etc/apache/ or /etc/apache2/}}}. You should have at least ''some'' know-how of how to set up and deal with Apache, especially when it comes to virtual host setup. If you do not know what we are talking about, please read about ''Configuration Files'' and ''Apache Virtual Host documentation ''in the [[http://httpd.apache.org/docs/|Apache documentation]].
 
28
 
 
29
On Apache2 it is quite usual to have a directory (like /etc/httpd/conf.d) for virtual hosts. So every file ending with ''.conf'' will be included into the main Apache configuration file. To look if this is true for your configuration, search for the word "Include".
 
30
 
 
31
=== Create a wiki instance ===
 
32
Creating a wiki instance involves copying files around and setting appropriate permissions. Before you can proceed, you need to know what user and group your Apache server runs as. The easiest way to know this is to issue this command:
 
33
 
 
34
{{{
 
35
> egrep "^User|^Group" /etc/httpd/httpd.conf
 
36
User wwwrun
 
37
Group nogroup
 
38
}}}
 
39
This shows a typical result: "`wwwrun.nogroup`". Other common results are "`nobody.nogroup`", "`apache.apache`" and "`www-data.www-data`". You can of course use your own. What matters is that you know which ones are in use, because you will need them to set file permissions.
 
40
 
 
41
Once you have gathered this information, read ../WikiInstanceCreation and follow the steps described there.
 
42
 
 
43
=== Install moin.cgi ===
 
44
There is one last file you need to copy, the bridge between Apache and Moin``Moin: the CGI script that Apache will call every time a wiki page is requested, and that will in turn invoke all the Moin``Moin components to handle the request. You can actually put this script anywhere you like (all the paths to the files Moin``Moin needs can be configured to match your filesystem layout), but for the sake of simplicity and security, we suggest you follow the instructions below, unless you think you know better.
 
45
 
 
46
We will create a `cgi-bin` subdirectory in the instance directory. Using the environment variables defined in ../WikiInstanceCreation, run the following commands:
 
47
 
 
48
{{{
 
49
> cd $WIKILOCATION/$INSTANCE
 
50
> mkdir cgi-bin
 
51
> cp $SHARE/server/moin.cgi cgi-bin
 
52
> chown -R $USER.$GROUP cgi-bin
 
53
> chmod -R ug+rx cgi-bin
 
54
> chmod -R o-rwx cgi-bin
 
55
}}}
 
56
 
 
57
=== Configure moin.cgi ===
 
58
When `moin.cgi` is launched, it imports a Moin``Moin module that in turn imports other modules and the configuration file. While the Moin``Moin modules should always be found in a properly configured system (as described in ../BasicInstallation), it is likely that the configuration file will not be found. Edit the `moin.cgi` script to correct that. Add these lines near the top of the file:
 
59
 
 
60
{{{
 
61
import sys
 
62
sys.path.insert(0, '..')
 
63
}}}
 
64
 
 
65
An even better way is to use the absolute path name of the directory that contains the `wikiconfig.py` file instead of `'..'`.
 
66
 
 
67
=== Configure Apache ===
 
68
Now that every file is in place and properly locked down (as far as the filesystem is concerned), we need to configure Apache so that it offers access to the right files, and no others. However, since the default Apache configuration varies a lot depending on the distribution you use, and since administrators often make important additions and changes to it, we cannot give exact instructions that cover all cases. Instead, we will first describe roughly what needs to be done, and then give a few specific lines that you should add at the appropriate place in your Apache config.
 
69
 
 
70
Your Apache should be set up so that:
 
71
 
 
72
 * Access to your instance directory is denied (sane Apache installations should actually deny access to the whole server, and then only allow a few specific directories).
 
73
 * An '''Alias''' is set up to redirect requests from `/moin_static160/` (in the URL - see also `url_prefix_static` configuration variable) to the `htdocs` directory (in the `share` directory, as discussed at the bottom of ../BasicInstallation). Please note that `url_prefix_static` will change with every moin release!
 
74
 * A '''!ScriptAlias''' is set up to redirect requests from whatever you want (we suggest you use your instance name, for example `/mywiki`) to the CGI script you just copied.
 
75
 
 
76
The following commands will add two lines at the bottom of your Apache config file. These lines only cover the last two items listed above. You have to check the first one by yourself (there is too much variation in Linux distributions). Note that you may have to move the two lines to the appropriate place in your config file -- maybe near other similar lines.
 
77
 
 
78
{{{
 
79
> echo "" >>/etc/httpd/httpd.conf
 
80
> echo "Alias /moin_static160/ \"$SHARE/htdocs/\"" >>/etc/httpd/httpd.conf
 
81
> echo "ScriptAlias /mywiki \"$WIKILOCATION/$INSTANCE/cgi-bin/moin.cgi\"" >>/etc/httpd/httpd.conf
 
82
}}}
 
83
 
 
84
So this would add two lines like the both below to a config file (possibly you use one for each virtual server):
 
85
 
 
86
{{{
 
87
Alias /moin_static160/ /usr/local/share/htdocs/
 
88
ScriptAlias /mywiki /usr/local/share/moin/mywiki/cgi-bin/moin.cgi
 
89
}}}
 
90
 
 
91
You only need to define the Alias for `htdocs` once, no matter how many wikis you run with the 1.6.0 version of moin. You need to define a different script alias for each wiki instance you intend to run. So you could also define the Alias in a central Apache configuration file and only define the ScriptAlias in virtual host configurations.
 
92
 
 
93
=== Configure MoinMoin ===
 
94
Finally, check that the `wikiconfig.py` file in the instance directory contains correct paths for:
 
95
 * `url_prefix_static` (static stuff like css/img/js)
 
96
 * `data_dir` (the instance data directory) and
 
97
 * `data_underlay_dir` (the instance underlay directory).
 
98
 
 
99
You can use relative paths for the directories, but note that they are relative to the CGI script, not the configuration file! Better '''use absolute paths''', and save yourself some headaches.
 
100
 
 
101
Here are the settings you should have in the config file if you followed all our suggestions:
 
102
 
 
103
{{{
 
104
    data_dir = '../data/'  # better use absolute path
 
105
    data_underlay_dir = '../underlay/'  # better use absolute path
 
106
    url_prefix_static = '/moin_static160' # depends on moin version
 
107
}}}
 
108
There are other settings you will likely want to alter, look at the bottom of ../WikiInstanceCreation for more details about them.
 
109
 
 
110
=== Test the wiki ===
 
111
Everything should work fine now. It is time to '''restart the Apache server''' (usually with "`/etc/init.d/apache restart`", sometimes with "`apachectl restart`") and perform the following steps:
 
112
 
 
113
 * Run the ''Moin``Moin CGI Diagnosis'': connect to "`http://127.0.0.1/mywiki?action=test`" (or the name and port you have defined in the Apache configuration file). Verify that the displayed information is correct. Check that the directories listed under ''Checking directories...'' are ''OK''.
 
114
 * Access your new wiki with the URL "`http://127.0.0.1/mywiki/`" (or the name and port you have defined in the Apache configuration file). You should see some wiki page - read it.
 
115
 * Then go to the WikiSandBox page.
 
116
 * Try to edit it and save your changes.
 
117
 * If that works, see if your edit is reflected on the Recent``Changes page.
 
118
 * If you see them, congratulations, your new wiki works! :)
 
119
If something goes wrong, have a look at Troubleshooting, at the bottom of this page.
 
120
 
 
121
 
 
122
== Simple User Scenario ==
 
123
On machines shared by many people, simple users typically have no access to the root account, cannot modify the `httpd.conf` file, and cannot copy files into the system-wide `cgi-bin` and `htdocs` directories. In that case, Apache can be set up so that each user can host a web site in the home directory of his or her shell account, using the `UserDir` directive. If the machine administrator decides to use it, all URLs that start with "`/~username`" will be redirected to a directory in the users' home directories, where they have write permission and can install Moin``Moin.
 
124
 
 
125
As an example, we will consider the case of a user named "`mm`". Of course, wherever you see "`mm`" below, you will replace it with your own username.
 
126
 
 
127
=== Make sure /~username works ===
 
128
The home directory installation can only work if the administrator (root) has allowed it. So, the first step is of course to check that it works. Typically, Apache is set up so that the `public_html` subdirectory in the home directory is used as the web site root. So, the first first step is to check if that directory exists.
 
129
 
 
130
{{{
 
131
> ls -ld ~/public_html
 
132
drwxr-xr-x   2 mm       users        4096 Nov 30 00:29 public_html
 
133
}}}
 
134
If the directory does not exist, create it, and be sure it can be read and entered by the web server.
 
135
 
 
136
{{{
 
137
> mkdir public_html
 
138
> chmod a+rx public_html
 
139
> ls -ld ~/public_html
 
140
drwxr-xr-x   2 mm       users        4096 Nov 30 00:35 public_html
 
141
}}}
 
142
Now, check if the "`/~mm`" URL works:
 
143
 
 
144
{{{
 
145
> lynx -error_file=/dev/stderr -dump http://localhost/~mm/ >/dev/null
 
146
URL=http://localhost/~mm/ (GET)
 
147
STATUS=HTTP/1.1 200 OK
 
148
}}}
 
149
If you get a "`200 OK`" response code, then it works, and you can go on to the next check. If you get a "`403 Forbidden`" or a "`404 Not Found`" response, then maybe something is wrong with your directory, or maybe the whole thing has not been enabled by your administrator.
 
150
 
 
151
 * Check the permissions for your home directory (`~`) and your `public_html` directory. The first one should at least end with "`--x`", and the second one, as we saw above, with "`r-x`".
 
152
 * It also possible that the administrator has set up another name for the personal web site directory. "`public_html`" is just the usual default, but anything can actually be used. There is no way to know, you have to ask the administrator (root).
 
153
 * Finally, if the personal web site feature is disabled, maybe you can ask the administrator to enable it?
 
154
Once you have checked you can read the files in the directory, you need to check that you are also able to execute CGI scripts in that directory. Use the following commands to create a simple CGI script in the appropriate location:
 
155
 
 
156
{{{
 
157
> mkdir -p ~/public_html/cgi-bin
 
158
> cat > ~/public_html/cgi-bin/test.cgi
 
159
#!/bin/sh
 
160
echo Content-Type: text/plain
 
161
echo
 
162
echo "CGI scripts work"
 
163
<CTRL-D>
 
164
> chmod a+rx ~/public_html/cgi-bin/test.cgi
 
165
> lynx -dump http://localhost/~jh/cgi-bin/test.cgi
 
166
CGI scripts work
 
167
}}}
 
168
If you get anything else than "`CGI scripts work`", then something went wrong. Check the directory permissions as above, try other names (or ask about them). The sad truth might be that you are not allowed to execute CGI scripts. You would then have to ask the administrator (root) for that permission.
 
169
 
 
170
Once you get it, you can set up your wiki instance in the `public_html` directory. :)
 
171
 
 
172
=== Create a wiki instance ===
 
173
Creating a wiki instance involves copying files around and setting appropriate permissions. Read ../WikiInstanceCreation and follow the steps described there.
 
174
 
 
175
=== Install the htdocs files ===
 
176
The web server needs to access these files, so we need to copy them into the "`public_html`" directory. Just use this:
 
177
 
 
178
{{{
 
179
> cd ~/public_html
 
180
> cp -R ~/share/moin/htdocs moin_static160
 
181
> chmod -R a+rX moin_static160
 
182
}}}
 
183
 
 
184
=== Install moin.cgi ===
 
185
There is one last file you need to copy, the bridge between Apache and Moin``Moin: the CGI script that Apache will call every time a wiki page is requested, and that will in turn invoke all the Moin``Moin components to handle the request. You need to put this file in a directory for which CGI scripts execution is enabled. By default, this should work:
 
186
 
 
187
{{{
 
188
> cd ~/public_html
 
189
> mkdir cgi-bin
 
190
> cp $SHARE/server/moin.cgi cgi-bin
 
191
> chmod -R a+rx cgi-bin
 
192
}}}
 
193
 
 
194
=== Configure moin.cgi ===
 
195
When `moin.cgi` is launched, it imports a Moin``Moin module (that in turn imports other modules and the configuration file). Since everything has been installed in your home directory, it is likely none of these will be found. Edit the `moin.cgi` script to correct that. Add these lines near the top of the file:
 
196
 
 
197
{{{
 
198
import sys
 
199
sys.path.insert(0, '/home/mm/lib/python2.4')
 
200
sys.path.insert(0, '/home/mm/lib/python2.4/site-packages')
 
201
sys.path.insert(0, '/home/mm/share/moin/mywiki')
 
202
}}}
 
203
Of course, you need to adapt the paths to your situation. The first two lines should help locate the Moin``Moin modules, the last one should help locate the `wikiconfig.py` file.
 
204
 
 
205
'''Note:''' You might also need to edit the first line of the file, to point to the correct version of Python. The default should be fine, but a line like "`#! /usr/bin/python2.4`" might help you if the default does not work.
 
206
 
 
207
'''Note 2:''' In this file there is a line reading {{{request = RequestCGI()}}}. If you have a complex mod_rewrite case, you might want to add {{{properties = {'script_name': '/mywiki'} }}} in the parentheses. This will let MoinMoin generate URLs that start with {{{/mywiki}}} and not the path that the webserver passed to MoinMoin:
 
208
 
 
209
{{{
 
210
def handle_request(req, env, form):
 
211
    request = RequestCGI(req, env, form, properties = {'script_name': '/mywiki'})
 
212
    request.run()
 
213
}}}
 
214
 
 
215
=== Configure MoinMoin ===
 
216
Finally, check that the `wikiconfig.py` file in the instance directory contains correct paths for `url_prefix_static` (the htdocs directory), `data_dir` (the instance data directory) and `data_underlay_dir` (the instance underlay directory). You can use relative paths for the directories, but note that they are relative to the CGI script, not the configuration file! It is better to use '''absolute paths''', and save yourself some headaches.
 
217
 
 
218
{{{
 
219
    data_dir = '/home/mm/share/moin/mywiki/data/'
 
220
    data_underlay_dir = '/home/mm/share/moin/mywiki/underlay/'
 
221
    url_prefix = '/~mm/moin_static160'
 
222
}}}
 
223
=== Test the wiki ===
 
224
Everything should work fine, now. It is time to perform the following steps:
 
225
 
 
226
 * Run the ''Moin``Moin CGI Diagnosis'': {{{> lynx -dump http://localhost/~mm/cgi-bin/moin.cgi?action=test}}}
 
227
 * If it worked, try to access your new-born wiki with the URL "`http://127.0.0.1/~mm/cgi-bin/moin.cgi`". You should see some wiki page - read it.
 
228
 * Now go to the WikiSandBox page.
 
229
 * Try to edit it and save your changes.
 
230
 * If that works, see if your edit is reflected on the Recent``Changes page.
 
231
 * If you see them, congratulations, you have a new wiki! :)
 
232
 
 
233
If something goes wrong, have a look at Troubleshooting, below.
 
234
 
 
235
== Troubleshooting ==
 
236
See also ../TroubleShooting for generic stuff.
 
237
 
 
238
The first thing to do when your wiki does not work as expected is to issue the command "`tail /var/log/httpd/error_log`" to display the most recent errors. Usually, you will get a hint on what went wrong, like missing file system permissions.
 
239
 
 
240
=== Adding permission to serve the htdocs directory ===
 
241
In some (sane) Linux distributions (like SuSE 9.0) serving directories other than the document-root "`/srv/www/htdocs`" with Apache is switched off by default for security reasons in "`/etc/httpd/httpd.conf`" (or for Apache2 "`/etc/apache2/httpd.conf`"):
 
242
 
 
243
{{{
 
244
# forbid access to the entire filesystem by default
 
245
<Directory />
 
246
  Options None
 
247
  AllowOverride None
 
248
  Order deny,allow
 
249
  Deny from all
 
250
</Directory>
 
251
}}}
 
252
To allow Apache to serve directories outside of the document root you have to add these lines to "`/etc/httpd/httpd.conf`" (in SuSE it is recommended to create a new "`http.conf.local`" and include this file in "`/etc/sysconfig/apache2`"):
 
253
 
 
254
{{{
 
255
Alias /wiki/ "/usr/share/moin/htdocs/"
 
256
<Directory "/usr/share/moin/htdocs/">
 
257
   Order deny,allow
 
258
   Allow from all
 
259
</Directory>
 
260
ScriptAlias /mywiki "/usr/share/moin/mywiki/cgi-bin/moin.cgi"
 
261
<Directory "/usr/share/moin/mywiki/cgi-bin">
 
262
   Order deny,allow
 
263
   Allow from all
 
264
</Directory>
 
265
}}}
 
266
Of course, you need to adapt the paths to your particular situation.