The following 545 words could not be found in the dictionary of 615 words (including 615 LocalSpellingWords) and are highlighted below:

able   about   above   absolute   according   account   action   actually   adapt   Add   add   Adding   additions   administrator   Administrator   administrators   advanced   Alias   alias   all   Allow   allow   allowed   almost   already   alter   always   an   An   and   another   anything   anywhere   Apache   apache   Apache2   apache2   apachectl   appropriate   around   ask   assume   at   Basic   be   because   been   Before   below   better   between   bin   board   born   bottom   bridge   but   By   by   call   can   cannot   case   cases   cat   cd   Changes   changes   Check   check   checked   Checking   chmod   chown   come   command   commands   common   complex   components   concerned   conf   config   configuration   Configure   configure   configured   congratulations   connect   consider   consult   containing   contains   contents   Contents   copied   copying   correct   course   cover   cp   Creating   Creation   decides   default   define   defined   denied   deny   Deny   describe   described   describes   details   dev   Diagnosis   different   dir   Dir   directive   directories   disabled   discussed   discussion   display   displayed   distribution   distributions   document   does   done   down   drwxr   dump   each   easiest   echo   edit   Edit   egrep   else   enable   enabled   entered   env   environment   errors   etc   every   everything   Everything   exact   exactly   example   execute   execution   exist   exists   expected   far   feature   few   file   files   filesystem   Finally   fine   follow   followed   following   For   for   Forbidden   form   Found   found   from   Front   gathered   generate   generic   get   give   go   goes   Group   group   handle   headaches   help   Help   her   hint   his   home   host   however   However   htdocs   httpd   if   If   import   important   imports   in   In   include   information   init   insert   install   Install   Installation   installation   Installations   installations   installed   Instance   instance   instead   Instead   instructions   intend   into   invoke   involves   issue   items   jh   Just   just   know   last   launched   layout   ld   least   let   lib   like   likely   line   lines   Linux   listed   local   localhost   locate   located   location   locked   log   look   lot   Ls   ls   lynx   machine   machines   main   Make   make   manual   many   master   match   matters   maybe   messages   might   Miscellaneous   missing   mkdir   mm   mod   modifiy   modify   module   modules   more   most   Most   move   much   mywiki   name   named   names   near   need   needs   new   next   no   nobody   nogroup   none   None   notably   note   Note   Nov   Now   now   null   Of   of   off   offers   often   On   on   Once   once   one   ones   only   Options   or   Order   Other   other   others   our   outside   Override   own   packages   page   Page   paragraphs   parenthesis   particular   passed   path   paths   people   perform   performed   permission   permissions   personal   place   plain   point   port   possible   pre   prefix   proceed   properly   properties   public   put   Python   python2   quite   read   Read   reading   reasons   recent   Recent   recommended   redirect   redirected   reflected   relative   replace   req   Request   request   requested   requests   response   restart   result   results   rewrite   right   root   roughly   Run   run   runs   rwx   rx   sad   sake   sane   save   saw   scenarios   script   Script   scripts   second   security   See   see   serve   server   serving   set   setting   settings   share   shared   shell   Shooting   should   shows   similar   simple   Simple   simplicity   since   Since   site   situation   so   So   Some   some   something   sometimes   specific   srv   standard   start   stderr   step   steps   stuff   Su   subdirectory   suggest   suggestions   sure   switched   sys   sysconfig   system   Table   tail   taken   Test   test   text   than   that   The   the   them   then   There   there   These   these   they   thing   think   this   This   time   to   To   too   top   tricks   Trouble   Troubleshooting   truth   try   turn   two   Two   Type   typical   typically   Typically   ug   unable   under   underlay   Unices   unless   up   use   Use   used   user   User   username   users   Using   using   usr   usual   usually   Usually   var   variables   variation   varies   various   Verify   version   very   want   way   We   we   web   webserver   weirder   went   what   What   whatever   When   when   where   wherever   which   While   whole   wide   wikiconfig   will   with   work   worked   works   would   write   wrong   wwwrun   xr   You   you   Your   your   yourself  

Clear message

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.

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.

Table of contents

Contents

  1. Administrator (root)
    1. Create a wiki instance
    2. Install moin.cgi
    3. Configure moin.cgi
    4. Configure Apache
    5. Configure MoinMoin
    6. Test the wiki
    7. Apache tricks
  2. Simple user (home directory installation)
    1. Make sure /~username works
    2. Create a wiki instance
    3. Install the htdocs files
    4. Install moin.cgi
    5. Configure moin.cgi
    6. Configure MoinMoin
    7. Test the wiki
  3. Troubleshooting
    1. Adding permission to serve the htdocs directory

Administrator (root)

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:

Some distributions use apache instead of httpd for the directory names, others may use weirder settings.

Create a wiki instance

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: 

> egrep "^User|^Group" /etc/httpd/httpd.conf
User wwwrun
Group nogroup

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.

Once you have gathered this information, read ../WikiInstanceCreation and follow the steps described there.

Install moin.cgi

There is one last file you need to copy, the bridge between Apache and MoinMoin: the CGI script that Apache will call every time a wiki page is requested, and that will in turn invoke all the MoinMoin components to handle the request. You can actually put this script anywhere you like (all the paths to the files MoinMoin 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.

We will create a cgi-bin subdirectory in the instance directory. Using the environment variables defined in ../WikiInstanceCreation, run the following commands: 

> cd $WIKILOCATION/$INSTANCE
> mkdir cgi-bin
> cp $SHARE/server/moin.cgi cgi-bin
> chown -R $USER.$GROUP cgi-bin
> chmod -R ug+rx cgi-bin
> chmod -R o-rwx cgi-bin

Configure moin.cgi

When moin.cgi is launched, it imports a MoinMoin module that in turn imports other modules and the configuration file. While the MoinMoin 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: 

import sys
sys.path.insert(0, '..')

You can also use the absolute name of the directory that contains the wikiconfig.py file instead of '..'.

Configure Apache

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.

Your Apache should be set up so that:

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. 

> echo "" >>/etc/httpd/httpd.conf
> echo "Alias /wiki/ \"$SHARE/htdocs/\"" >>/etc/httpd/httpd.conf
> echo "ScriptAlias /mywiki \"$WIKILOCATION/$INSTANCE/cgi-bin/moin.cgi\"" >>/etc/httpd/httpd.conf

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.

Configure MoinMoin

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.

Here are the settings you should have in the config file if you followed all our suggestions: 

    data_dir = '../data/'
    data_underlay_dir = '../underlay/'
    url_prefix = '/wiki'

There are other settings you will likely want to alter, look at the bottom of ../WikiInstanceCreation for more details about them.

Test the wiki

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:

If something goes wrong, have a look at Troubleshooting, at the bottom of this page.

Apache tricks

For more advanced configuration and some tricks see HelpMiscellaneous.

Simple user (home directory installation)

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 MoinMoin.

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.

Make sure /~username works

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. 

> ls -ld ~/public_html
drwxr-xr-x   2 mm       users        4096 Nov 30 00:29 public_html

If the directory does not exist, create it, and be sure it can be read and entered by the web server. 

> mkdir public_html
> chmod a+rx public_html
> ls -ld ~/public_html
drwxr-xr-x   2 mm       users        4096 Nov 30 00:35 public_html

Now, check if the "/~mm" URL works: 

> lynx -error_file=/dev/stderr -dump http://localhost/~mm/ >/dev/null
URL=http://localhost/~mm/ (GET)
STATUS=HTTP/1.1 200 OK

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.

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: 

> mkdir -p ~/public_html/cgi-bin
> cat > ~/public_html/cgi-bin/test.cgi
#!/bin/sh
echo Content-Type: text/plain
echo
echo "CGI scripts work"
<CTRL-D>
> chmod a+rx ~/public_html/cgi-bin/test.cgi
> lynx -dump http://localhost/~jh/cgi-bin/test.cgi
CGI scripts work

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.

Once you get it, you can set up your wiki instance in the public_html directory. :)

Create a wiki instance

Creating a wiki instance involves copying files around and setting appropriate permissions. Read ../WikiInstanceCreation and follow the steps described there.

Install the htdocs files

The web server needs to access these files, so we need to copy them in the "public_html" directory. Just use this: 

> cd ~/public_html
> cp -R ~/share/moin/htdocs wiki
> chmod -R a+rX wiki

Install moin.cgi

There is one last file you need to copy, the bridge between Apache and MoinMoin: the CGI script that Apache will call every time a wiki page is requested, and that will in turn invoke all the MoinMoin 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: 

> cd ~/public_html
> mkdir cgi-bin
> cp $SHARE/server/moin.cgi cgi-bin
> chmod -R a+rx cgi-bin

Configure moin.cgi

When moin.cgi is launched, it imports a MoinMoin 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: 

import sys
sys.path.insert(0, '/home/mm/lib/python2.3')
sys.path.insert(0, '/home/mm/lib/python2.3/site-packages')
sys.path.insert(0, '/home/mm/share/moin/mywiki')

Of course, you need to adapt the paths to your situation. The first two lines should help locate the MoinMoin modules, the last one should help locate the wikiconfig.py file.

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.

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: 

def handle_request(req, env, form):
    request = RequestCGI(req, env, form, properties = {'script_name': '/mywiki'})
    request.run()

Configure MoinMoin

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. 

    data_dir = '/home/mm/share/moin/mywiki/data/'
    data_underlay_dir = '/home/mm/share/moin/mywiki/underlay/'
    url_prefix = '/~mm/wiki'

Test the wiki

Everything should work fine, now. It is time to perform the following steps:

If something goes wrong, have a look at Troubleshooting, below.

Troubleshooting

See also ../TroubleShooting for generic stuff.

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.

Adding permission to serve the htdocs directory

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"): 

# forbid access to the entire filesystem by default
<Directory />
  Options None
  AllowOverride None
  Order deny,allow
  Deny from all
</Directory>

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"): 

Alias /wiki/ "/usr/share/moin/htdocs/"
<Directory "/usr/share/moin/htdocs/">
   Order deny,allow
   Allow from all
</Directory>

ScriptAlias /mywiki "/usr/share/moin/mywiki/cgi-bin/moin.cgi"
<Directory "/usr/share/moin/mywiki/cgi-bin">
   Order deny,allow
   Allow from all
</Directory>

Of course, you need to adapt the paths to your particular situation.

HelpOnInstalling/ApacheOnLinux (last modified 2007-04-01 02:20:37)