1
## Please edit system and help pages ONLY in the moinmaster wiki! For more
2
## information, please see MoinMaster:MoinPagesEditorGroup.
1
## Please edit system and help pages ONLY in the master wiki!
2
## For more information, please see MoinMoin:MoinDev/Translation.
3
3
## page was renamed from HelpOnInstalling/ApacheOnUnix
4
4
##master-page:Unknown-Page
5
5
##master-date:Unknown-Date
6
#acl MoinPagesEditorGroup:read,write,delete,revert All:read
6
#acl -All:write Default
9
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.
11
Two scenarios are possible. You might be the administrator (root) of the server, able to install and modify files almost anywhere on the machine, and notably able to modifiy the Apache configuration. You might also be a simple user, only able to write files into your home directory, and unable to alter the master Apache config file. The two scenarios are discussed below.
13
'''Table of contents''' [[TableOfContents]]
15
== Administrator (root) ==
16
Most GNU/Linux distributions come with Apache pre-installed. There is, however, some variation as to where exactly the various Apache files are located. You should consult your distribution manual, or ask on the appropriate discussion board. In the following paragraphs, we assume a (quite standard) file system layout with:
18
* `/etc/httpd/httpd.conf` - the main Apache configuration file
19
* `/var/log/httpd/error_log` - the log file containing Apache error messages
21
Some distributions use `apache` instead of `httpd` for the directory names, others may use weirder settings.
11
On this page two installation scenarios are discussed:
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.
16
The following options are not mentioned here:
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.
24
'''Table of contents''' <<TableOfContents>>
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]].
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".
23
31
=== Create a wiki instance ===
24
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:
55
62
sys.path.insert(0, '..')
58
You can also use the absolute name of the directory that contains the `wikiconfig.py` file instead of `'..'`.
65
An even better way is to use the absolute path name of the directory that contains the `wikiconfig.py` file instead of `'..'`.
60
67
=== Configure Apache ===
61
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 according to 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.
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.
63
70
Your Apache should be set up so that:
65
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).
66
* An alias is set up to redirect requests from `/wiki/` (in the URL) to the `htdocs` directory (in the `share` directory, as discussed at the bottom of ../BasicInstallation)
67
* A script alias 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.
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.
69
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.
72
79
> echo "" >>/etc/httpd/httpd.conf
73
> echo "Alias /wiki/ \"$SHARE/htdocs/\"" >>/etc/httpd/httpd.conf
80
> echo "Alias /moin_static160/ \"$SHARE/htdocs/\"" >>/etc/httpd/httpd.conf
74
81
> echo "ScriptAlias /mywiki \"$WIKILOCATION/$INSTANCE/cgi-bin/moin.cgi\"" >>/etc/httpd/httpd.conf
77
You only need to define the alias for `htdocs` once. You need to define a different script alias for each wiki instance you intend to run.
84
So this would add two lines like the both below to a config file (possibly you use one for each virtual server):
87
Alias /moin_static160/ /usr/local/share/htdocs/
88
ScriptAlias /mywiki /usr/local/share/moin/mywiki/cgi-bin/moin.cgi
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.
79
93
=== Configure MoinMoin ===
80
Finally, check that the `wikiconfig.py` file in the instance directory contains correct paths for the htdocs prefix, the instance data directory, and 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! You can also use absolute paths, and save yourself some headaches.
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).
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.
82
101
Here are the settings you should have in the config file if you followed all our suggestions:
86
data_underlay_dir = '../underlay/'
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
90
108
There are other settings you will likely want to alter, look at the bottom of ../WikiInstanceCreation for more details about them.
92
110
=== Test the wiki ===
93
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:
95
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''.
96
* 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 the Front``Page.
97
* If this is the case, try to edit it and save your changes.
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.
98
117
* If that works, see if your edit is reflected on the Recent``Changes page.
99
118
* If you see them, congratulations, your new wiki works! :)
101
119
If something goes wrong, have a look at Troubleshooting, at the bottom of this page.
103
=== Apache tricks ===
104
For more advanced configuration and some tricks see HelpMiscellaneous.
106
== Simple user (home directory installation) ==
122
== Simple User Scenario ==
107
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.
109
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.
132
146
URL=http://localhost/~mm/ (GET)
133
147
STATUS=HTTP/1.1 200 OK
136
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.
138
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`".
139
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).
140
153
* Finally, if the personal web site feature is disabled, maybe you can ask the administrator to enable it?
142
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:
188
sys.path.insert(0, '/home/mm/lib/python2.3')
189
sys.path.insert(0, '/home/mm/lib/python2.3/site-packages')
199
sys.path.insert(0, '/home/mm/lib/python2.4')
200
sys.path.insert(0, '/home/mm/lib/python2.4/site-packages')
190
201
sys.path.insert(0, '/home/mm/share/moin/mywiki')
193
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.
195
'''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.3`" might help you if the default does not work.
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.
197
'''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 parenthesis. This will let MoinMoin generate URLs that start with {{{/mywiki}}} and not the path that the webserver passed to MoinMoin:
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:
200
210
def handle_request(req, env, form):
205
215
=== Configure MoinMoin ===
206
Finally, check that the `wikiconfig.py` file in the instance directory contains correct paths for the htdocs directory, the instance data directory, and 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! You can also use absolute paths, and save yourself some headaches.
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.
209
219
data_dir = '/home/mm/share/moin/mywiki/data/'
210
220
data_underlay_dir = '/home/mm/share/moin/mywiki/underlay/'
211
url_prefix = '/~mm/wiki'
221
url_prefix = '/~mm/moin_static160'
214
223
=== Test the wiki ===
215
224
Everything should work fine, now. It is time to perform the following steps:
217
226
* Run the ''Moin``Moin CGI Diagnosis'': {{{> lynx -dump http://localhost/~mm/cgi-bin/moin.cgi?action=test}}}
218
* 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 the Front``Page.
219
* If this is the case, try to edit it and save your changes.
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.
220
230
* If that works, see if your edit is reflected on the Recent``Changes page.
221
231
* If you see them, congratulations, you have a new wiki! :)