After you have downloaded and installed MoinMoin, you will want to "have a wiki". As explained at the bottom of ../BasicInstallation, you have to copy several directories and files. This way, you can have as many wikis as you want, and you can easily upgrade MoinMoin: only the original files will be overwritten, not your copies.

Every time you copy those files (and modify the configuration of your server accordingly), you create what is called a wiki instance. Each wiki instance is independent from the others, with a different configuration, different pages, different users, etc.

Some of the steps you need to take depend on which web server and which operating system you use. They are described on dedicated pages, which you should read (at least the beginning) before reading this one. Some other steps are common to every webserver and operating system (copying files around, setting permissions), and this is what is described here.

Linux users can use createinstance.sh (a bash script that creates the instance) instead of doing all steps manually:

1. If anything is unclear, just read the sections below for more hints.
2. Have a look into the script before running it, if all settings are correct for your setup:
   • USER and GROUP should be the user and group used by your web-server for running moin.

   • SHARE is where the shared files were copied to, see install.log from the setup.py install step

3. The script takes a single parameter: the location of your wiki instance (see "Choose a location" section below):

   # ./createinstance.sh /path/to/mywiki

4. Now continue in section "Tune configuration"

Read this first

Security warnings

Note to Windows users

All the commands below are Linux commands. The text descriptions that introduce them should be enough to help you understand what you need to do. Use the Windows Explorer, or the appropriate text-mode commands.

Choose a wiki name

Choose a unique name for the new wiki instance you want to create. It should be a short word, something that reflects what you intend to use the wiki for, like the name of your organization, of your team, of the project you are working on, etc.

The name "mywiki" is used as an example in the various commands below.

Choose a location

Choose a directory on your disk, it will contain all the files needed for your wiki instance. At the beginning, your wiki instance will use approximately 10 MB of disk space. Then of course, it will grow depending on the way your wiki is used. A personal wiki, even with many pages, might only use 30 MB or 40 MB of disk space. A popular wiki, or a wiki with many files attached to the pages, might use much more, of course.

If you are the administrator (or root) of the server, you can use anything you like or that makes sense to you, for example /usr/local/var/moin, /mnt/wikis, etc.

If you are a simple user, you will probably only be allowed to write in your personal, "home" directory. Choose a subdirectory that makes sense to you, for example the share/moin subdirectory.

Collect some important information

This is where the instructions differ according to the web server and operating system you use, and whether you are the administrator or a simple user. See the appropriate pages for your web server and operating system combination.

On Linux, the export command will be used to remember the collected information. Windows users should write it down carefully (maybe cutting-and-pasting in a Notepad window), or store it in environment variables if they use the command prompt.

• PREFIX is the prefix you used during the ../BasicInstallation

• SHARE is the name of the share directory, as discussed at the bottom of ../BasicInstallation

• WIKILOCATION is the name of the directory that will contain your wiki instance

• INSTANCE is the directory containing the wiki instance. It cannot be an existing directory readable through Apache, otherwise it will fail.

If you are an administrator, you also need to collect the following:

• USER is the user name of the web server

• GROUP is the name of the group to which the web server belongs

Now, Linux folks, let's store these settings in memory:

> export PREFIX=/usr                # this might be something else
> export SHARE=$PREFIX/share/moin   # this should be correct for most people
> export WIKILOCATION=$SHARE        # this is just an example
> export INSTANCE=mywiki            # this is just an example

Administrators also need the following two lines:

> export USER=www-data              # this is just an example
> export GROUP=www-data             # this is just an example

Copy the files

To create your new instance, you first need to create a directory named like your instance, inside the WIKILOCATION. Then you need to copy the data and underlay directories from your SHARE directory into your instance directory. Finally, you need to copy the wikiconfig.py file from the config directory into the instance directory.

Linux folks need to just type these commands:

> 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

• Note that you just need to keep one underlay directory on your system if you are running multiple wikis (e.g. in a farm.)

Set permissions

Administrators

Administrators need to restrict the permissions of the files, so that only the web server (and the administrator of course) can read and write them. For maximum security, no other user on the machine should be able to read or write anything in the wiki instance directory. Don't forget that this directory contains sensitive information, notably the (encrypted) passwords of the wiki users.

On Linux, the following commands should be enough:

> chown -R $USER.$GROUP $INSTANCE   # check that USER and GROUP are correct
> chmod -R ug+rwX $INSTANCE         # USER.GROUP may read and write
> chmod -R o-rwx $INSTANCE          # everybody else is rejected

Normal users

Normal users, on the contrary, need to broaden the permissions of the files, so that the web server can read and write them. On recent Windows versions, and on some versions of Linux and other systems, access control lists can be used to that effect. They are, however, powerful and complicated, much beyond the scope of this document. Ask a knowledgeable person about them.

Without them, normal users have to allow everybody to access the instance directory. This is the only way the web server can enter it and do its work. This is, of course, VERY INSECURE, since any other user and program on the server can read the directory. You should not use such a setup for a wiki open to the public.

On Linux, the following commands will open the instance directory to the whole world:

> chmod -R a+rwX $INSTANCE

Note:

• it is also possible to put the web server and the normal user in the same group, and then only open the instance directory to the members of that group. This is a bit more secure (depending on who else is in the group), but you need the cooperation of the server administrator; he is the one setting up groups.

• the best other possibility is that the server administrator sets up suexec to execute CGI scripts in user directories under the user id of that user. You don't need to give world permissions that way, so it is a quite secure setup, but you also need cooperation of the administrator.

Tune configuration

Now, you need to tune the configuration of your web server and of your wiki instance. Look at the appropriate help page for your web server, then come back here to tune the settings of your wiki instance.

Edit wikiconfig.py. The default settings should work fine in most cases, but there are some things that you will probably want to change, like the name and logo of your wiki! Read the comments inside wikiconfig.py, they will guide you through this process.

HelpOnConfiguration contains all the details about all the options, in case the comments in wikiconfig.py are not enough.

Using MoinMoin with Twisted

Twisted is an event-driven networking framework for many kinds of applications. For MoinMoin Twisted is used as a web server that just imports MoinMoin persistently. This has the advantage that the Python interpreter and all Python scripts (including Twisted itself and also MoinMoin) is only loaded and initialized one time, and that data can be cached in memory from request to request, enhancing the performance of MoinMoin.

• First do ../BasicInstallation and ../WikiInstanceCreation.

Besides the general installation you need 3 files:

1. the script /path/to/cgi-dir/mointwisted (see "Starting the server" below)

2. the webserver script file like mointwisted.py (which needs to be in the same directory where your working directory is).

3. the configuration file like /path/to/wikiconfig-dir/wikiconfig.py

Install Twisted

First, install Twisted (see URL above). Many Linux distributions have Twisted packages. Please refer to the documentation of Twisted for installation information.

Configuring the Twisted server

Copy the file wiki/server/mointwisted.py to your wiki directory. Edit and adapt the settings to your needs.

System path configuration

If you did a standard install, and you are not a developer, you probably want to skip this section. Otherwise, you might want to add the path to moin and config file, like that:

sys.path.insert(0, '/path/to/moin')
sys.path.insert(0, '/path/to/wikiconfig')

Config class options

If you did a standard install, the default options might be just what you need. Check and change what you like:

Configuring wikiconfig.py

The sample config file should be just fine.

Don't change url_prefix_static as the default value is hardcoded in the Twisted server.

Starting the server

on Unix

On GNU/Linux, Mac OS X or another POSIX-like OS, copy wiki/server/mointwisted to your wiki directory. You might want to adapt PYTHONPATH and the path to twistd.

Start the server with ./mointwisted start and test your wiki at http://localhost:8080/. Stop the server with ./mointwisted stop.

For more options run ./mointwisted without arguments.

If you want to start the server via initscript make sure mointwisted finds montwisted.py on startup!

on Windows

Copy wiki/server/mointwisted.cmd to your wiki directory. You might have to change the path pointing to the python-scripts directory.

Double click mointwisted.cmd to start the server. It will create a new terminal window. To stop the server, close the terminal window.