Index
Installation too an arbitrary location (when you are root or the webmaster)
Most GNU/Linux distributions come with Apache pre-installed. In the following description, we assume a file system layout with:
/etc/httpd/httpd.conf - the main httpd configuration file
/var/log/httpd/error_log - log containing error messages
Creating a wiki instance
We need to know what USER and GROUP your Apache server runs on, so issue this command:
> egrep "^User|^Group" /etc/httpd/httpd.conf User wwwrun Group nogroup
This shows a typical result "wwwrun.nogroup", which we will use now:
How to create a wiki instance
Security warning
Make sure that your data/ directory is not accessible through your web server, or at least forbid the web server to serve anything below the data/ directory. The web server need to serve moin.cgi and the stuff below htdocs only!
Also make sure that the data/ directory and its subdirectories are not readable or writeable by other users than the web server user and root. If you need to give world rw permissions to get it working, be aware that you are doing an very unsecure setup, that can be compromised by other users of that system.
Creating a wiki instance
Now choose a name for the new wiki instance you want to create (maybe reflecting its use). We use an instance named "mywiki" in this example.
Do not use the name 'wiki', it is reserved for internal use.
Follow the sections below matching your type of installation, either:
install to "Arbitrary location" (you need to be root for that), or
install to "Home directory" (possible as a normal user, if allowed).
Only Arbitrary location
Now choose a directory (called WIKILOCATION) where your wiki should reside. This could be PREFIX/share/moin (PREFIX see ../BasicInstallation) or any other directory.
You also need to know which USER and GROUP moin will be run as (usually the same as your web server uses).
> export SHARE=/usr/share/moin # general: PREFIX/share/moin > export WIKILOCATION=$SHARE # or any other directory > export USER=www-data # the user moin will run as > export GROUP= www-data # the group moin will run as
Only Home directory
> export SHARE=~/share/moin # general: PREFIX/share/moin > export WIKILOCATION=~ # use home directory
Both
> export INSTANCE=mywiki # choose a nice name. do NOT use "wiki"! > cd $WIKILOCATION > mkdir $INSTANCE # make a directory for this instance > cp -r $SHARE/data $INSTANCE # copy template data directory > cp -r $SHARE/underlay $INSTANCE # copy underlay data directory > cp $SHARE/config/wikiconfig.py $INSTANCE # copy wiki configuration sample file
Only Arbitrary location
> chown -R $USER.$GROUP $INSTANCE # USER.GROUP has to match your web server setup > chmod -R ug+rwX $INSTANCE # USER.GROUP may read and write > chmod -R o-rwx $INSTANCE # no world access - use this for better security
Only Home directory
> chmod -R a+rwX $INSTANCE/data # moin running under web server uid/gid needs to r/w this > chmod -R a+rwX $INSTANCE/underlay # and this directory
Be aware that this setup is UNSECURE and can be compromised by other system users. Better check if it can be done with more restrictive access mode. Ask your web server administrator for details.
Both
Now edit wikiconfig.py. The default settings should work fine in most cases. You will have to change some setting.
sitename = 'My Wiki' ...
[Add more important setup options. This duplicates parts in HelpOnConfiguration, but much better for the user.]
See more options on page HelpOnConfiguration.
.
Installing moin.cgi
cd $WIKILOCATION/$INSTANCE mkdir cgi-bin cp $SHARE/moin/server/moin.cgi cgi-bin chown -R $USER.$GROUP cgi-bin chmod -R ug+rx cgi-bin
Apache configuration
These commands add some lines at bottom of "/etc/httpd/httpd.conf" (you maybe have to move them to the right place):
# again: DO NOT use /wiki for both! That doesn't work. > 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
The Alias line you only need once; the ScriptAlias line is needed once for each wiki instance (of course, each one with another wiki name and path).
Edit wikiconfig.py again so moin knows under which URL it will find the htdocs stuff:
url_prefix = '/wiki'
That is all, restart your Apache server (usually "/etc/init.d/apache restart") and try to access your new-born wiki with the URL "http://127.0.0.1/mywiki/". You should see the FrontPage, try to edit and save it, and if that works, see if your edit is reflected on the RecentChanges page.
Home directory installation (normal user)
Installation into your shell account's home directory is typically used on a host shared by many users and where you are not the root user. This usually implies that you cannot change the httpd.conf file, and also you cannot copy files into the machine's cgi-bin and htdocs directories. For this situation, Apache includes the UserDir directive, which maps all URLs that start with "/~username" to a directory in your home directory, where you have write permissions and thus can install MoinMoin.
The examples use "jh" (Juergen Hermann) as the user's name, which means you have to replace your own one whereever "jh" appears.
Making sure /~username URLs work
This kind of setup can only work if your webmaster has configured the host's Apache server so that the UserDir mechanism works. Here's how to check for this:
> ls -ld ~/public_html drwxr-xr-x 2 jh users 35 Jan 31 00:29 public_html
If this does not show a listing like above, then you might need to create the public_htmldirectory. Note that this directory must be readable (r-x) by the web server.
> lynx -error_file=/dev/stderr -dump http://localhost/~jh/ >/dev/null URL=http://localhost/~jh/ (GET) STATUS=HTTP/1.1 200 OK
You see here that we get a "200 OK" status response, which means that you can access your public_html area. If it does not work, you will probably get a "403 Forbidden" or a "404 Not Found" response. The first one normally indicates that you need to fix the permissions of your home directory (~) or your ~/public_html. But we also need to be able to execute CGI scripts, so we test that, too.
> mkdir -p ~/public_html/cgi-bin > cat > ~/public_html/cgi-bin/test.cgi #!/bin/sh echo Content-Type: text/plain echo echo IT WORKS <CTRL-D> > chmod a+rx ~/public_html/cgi-bin/test.cgi > lynx -dump http://localhost/~jh/cgi-bin/test.cgi IT WORKS
If you see anything else than "IT WORKS", then you are not allowed to execute CGI scripts. How you get that to work is not in the scope of this description, ask your webmaster!
Setting up a wiki instance
How to create a wiki instance
Security warning
Make sure that your data/ directory is not accessible through your web server, or at least forbid the web server to serve anything below the data/ directory. The web server need to serve moin.cgi and the stuff below htdocs only!
Also make sure that the data/ directory and its subdirectories are not readable or writeable by other users than the web server user and root. If you need to give world rw permissions to get it working, be aware that you are doing an very unsecure setup, that can be compromised by other users of that system.
Creating a wiki instance
Now choose a name for the new wiki instance you want to create (maybe reflecting its use). We use an instance named "mywiki" in this example.
Do not use the name 'wiki', it is reserved for internal use.
Follow the sections below matching your type of installation, either:
install to "Arbitrary location" (you need to be root for that), or
install to "Home directory" (possible as a normal user, if allowed).
Only Arbitrary location
Now choose a directory (called WIKILOCATION) where your wiki should reside. This could be PREFIX/share/moin (PREFIX see ../BasicInstallation) or any other directory.
You also need to know which USER and GROUP moin will be run as (usually the same as your web server uses).
> export SHARE=/usr/share/moin # general: PREFIX/share/moin > export WIKILOCATION=$SHARE # or any other directory > export USER=www-data # the user moin will run as > export GROUP= www-data # the group moin will run as
Only Home directory
> export SHARE=~/share/moin # general: PREFIX/share/moin > export WIKILOCATION=~ # use home directory
Both
> export INSTANCE=mywiki # choose a nice name. do NOT use "wiki"! > cd $WIKILOCATION > mkdir $INSTANCE # make a directory for this instance > cp -r $SHARE/data $INSTANCE # copy template data directory > cp -r $SHARE/underlay $INSTANCE # copy underlay data directory > cp $SHARE/config/wikiconfig.py $INSTANCE # copy wiki configuration sample file
Only Arbitrary location
> chown -R $USER.$GROUP $INSTANCE # USER.GROUP has to match your web server setup > chmod -R ug+rwX $INSTANCE # USER.GROUP may read and write > chmod -R o-rwx $INSTANCE # no world access - use this for better security
Only Home directory
> chmod -R a+rwX $INSTANCE/data # moin running under web server uid/gid needs to r/w this > chmod -R a+rwX $INSTANCE/underlay # and this directory
Be aware that this setup is UNSECURE and can be compromised by other system users. Better check if it can be done with more restrictive access mode. Ask your web server administrator for details.
Both
Now edit wikiconfig.py. The default settings should work fine in most cases. You will have to change some setting.
sitename = 'My Wiki' ...
[Add more important setup options. This duplicates parts in HelpOnConfiguration, but much better for the user.]
See more options on page HelpOnConfiguration.
Setting up public_html and testing the installation
Now we create the public part of the wiki, which is directly accessible by the web browser.
> cd ~/public_html > cp -r ~/share/moin/htdocs wiki
Edit $WIKILOCATION/$INSTANCE/wikiconfig.py again so moin knows under which URL it will find the htdocs stuff, the data, and the underlay:
... data_dir = '/home/jh/mywiki/data/' data_underlay_dir = '/home/jh/mywiki/underlay/' url_prefix = '/~jh/wiki' ...
> cd ~/public_html > mkdir -p cgi-bin > cp $SHARE/server/moin.cgi cgi-bin > chmod -R a+rx cgi-bin
To be able to execute the CGI script in your home directory, you need to extend Python's path within that script, and possibly adapt the bang path (that is the first line of the script). So, change "moin.cgi":
#! /usr/bin/python2.3 ... import sys sys.path.extend(['/home/jh/mywiki', '/home/jh/lib/python2.3']) ...
Finally, you can test your wiki installation by running the MoinMoin CGI Diagnosis:
> lynx -dump http://localhost/~jh/cgi-bin/moin.cgi?action=test
And now, your wiki should work and is available at the URL "http://localhost/~jh/cgi-bin/moin.cgi". Conclude your tests by editing and saving the FrontPage and checking out RecentChanges, which should reflect that edit.
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.
Missing permission to serve the `mywiki` directory
In some linux distributions (like SuSE 9.0) serving of 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/apach2/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 serving 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/local/moin/mywiki/cgi-bin/moin.cgi"> Order deny,allow Allow from all </Directory>