How to do a basic installation of MoinMoin on your system.
Before you can integrate MoinMoin into your web environment, you have to install the MoinMoin source code and data files using the standard Python distutils mechanism (setup.py). This page explains the steps you usually need to take to do this. For more details on the distutils installation process, consult the Installing Python Modules document in your Python documentation set.
The installation is similar on Windows and Linux (and other POSIX-type systems; for simplicity, we just say "Linux" in the docs).
We use text such as > command arguments to show what you have to type at the command prompt (also known as shell, terminal, etc.). In our examples "> " is the prompt, you don't have to type it in, you have to type what comes after it. Lines that do not begin with "> " are the answers to the commands you have typed. Read them carefully.
Check if Python is working
MoinMoin needs Python to run, so the first step is to check if an usable version of Python is installed and correctly set-up. If this is not the case, you will have to fix that before you can proceed.
The CHANGES file in the MoinMoin archive mentions what versions are supported. Python 2.3 is the minimum requirement for MoinMoin 1.7, but we suggest you use the latest Python release version.
You can download Python at http://www.python.org/download/.
If you are pretty sure an acceptable version of Python is installed but the commands below do not work, this may be because your Python files are not in the search path. Correctly setting the search path is outside the scope of this document; please ask for help on your favorite Python, Linux, or Windows discussion board.
If you have shell access, checking if Python is working is very simple. Just type the following command, and look at the result:
> python -V Python 2.4.4
If you don't have shell access, you can try using this pythontest.cgi script (it assumes that you are using a Linux kind of webserver). Upload the script to your cgi-bin directory, use chmod a+rx pythontest.cgi (or a similar command in your FTP program) to make it executable, and invoke it using your web browser.
If it doesn't display "CGI scripts work", well, then CGI scripts don't work. If it doesn't show one or more Python version numbers, then Python is not correctly installed. In both cases, before you can proceed, you will have to get in touch with the administrator of the server so that the problems get corrected.
Also be sure to read ../ApacheOnLinuxFtp after you've completed the ../BasicInstallation illustrated here.
To download the distribution archive, go to the download page and fetch the latest archive.
The next step is to unpack the distribution archive (which you have done already if you are reading this text from your hard drive). If you read this on the web, the distribution comes in a versioned .tar.gz archive, which you can unpack as shown below.
- On Windows
- On Linux
- You can use your favorite file manager -- it should be able to unpack them.
At any shell prompt, you can use the tar command.
The distribution archive will always unpack into a directory named moin-<version>, for example moin-1.7.0.
Here is how you would unpack the archive (using GNU tar) and enter the directory with the MoinMoin files:
> tar xzf moin-1.7.0.tar.gz > cd moin-1.7.0
You can install MoinMoin to either:
- a system location (if you have the necessary rights to do that -- on Linux you need to be root)
some specific location, like your home directory (Linux) or C:\moin (Windows).
The installation to a system location is easier, so choose that if possible.
If you have several versions of Python installed, please use the same version for setup and for running the wiki. Usually, the latest Python version will get the best results.
1. Recommended installation command for Linux (and MacOs X)
As you have chosen to not use a preconfigured package for your system this time it is highly recommended that you do not install MoinMoin into the default location. This is because otherwise, if you later want to install a moin package of your distribution this will overwrite your existing installation. The most common path for your own installations is below /usr/local (this is called the PREFIX). A command that should be ok for most Linux distributions and also MacOS X is
> python setup.py install --prefix='/usr/local' --record=install.log
This will install the shared files to '/usr/local/share/moin' and the moin code to /usr/local/lib/python2.x/site-packages/MoinMoin/.
2. Debugging setup process
If you have problems with the setup.py install step, try using the command:
> python -v setup.py --quiet install --record=install.log
The additional -v flag should provide you detailed verbose messages every step of the way.
On Linux, if you get an error like Invalid Python installation: cannot find /usr/lib/Python2.x/config/Makefile, you may not have the python module distutils installed, it's usually a part of the Python development libarary (python-dev). Some Linux distributions may not have installed it by default. For example, on Mandrake you need to install the python-devel package, on Debian it's called python-dev.
3. Installing to the default system location
> python setup.py --quiet install --record=install.log
This installs MoinMoin to the default system location (typically the Python directory, for example on Linux, inside /usr/lib/python2.x/site-packages/MoinMoin and /usr/share/moin). Look at the install.log file to see what was installed, and where.
4. Installing in the home directory or another specific location
Linux example, installing in the home directory:
> python setup.py --quiet install --prefix=$HOME --record=install.log
Windows example, installing in the C:\moin directory:
> python setup.py --quiet install --prefix="C:\moin" --record=install.log
All MoinMoin files will then be installed inside those directories, see install.log to know which files were installed, and where.
Note: You will likely see the following warning:
warning: install: modules installed to 'C:\moin\', which
is not in Python's module search path (sys.path) -- you'll
have to change the search path yourself
This means exactly what it says, you need to add your install directory to the search path of Python, or it won't find the MoinMoin code.
For example, if you are running using a webserver and standard CGI, edit moin.cgi and add your installation directory to the Python path, like this:
import sys sys.path.insert(0, 'C:/moin')
As a final step, if you have access to the shell or the command prompt, you can check that everything is correctly installed and ready to run. Start Python and type import MoinMoin. Nothing should be displayed in response to this command. Example:
> python Python 2.4.4 (...) Type "help", "copyright", "credits" or "license" for more information. >>> import MoinMoin >>>
If you get this instead:
>>> import MoinMoin Traceback (most recent call last): File "<stdin>", line 1, in ? ImportError: No module named MoinMoin >>>
then you have to tune your installation. Try modifying sys.path, as described above.
What has been installed
So, you have a ready-to-work MoinMoin installation now. Congratulations! Before you go on to configuring it, take a look at the various files and directories that have been installed.
It is important that you understand the different locations used in a MoinMoin setup, so read this carefully.
In the following descriptions, PREFIX is what you used with the setup.py command, or a default location if you didn't use the --prefix option. (Typical default values on Linux are /usr and /usr/local.) X.Y is the version of Python. Typically, this is 2.3, 2.4 or 2.5.
Look into install.log to find out about following important locations:
MoinMoin directory, usually PREFIX/lib/pythonX.Y/site-packages/MoinMoin -- this is where the MoinMoin source code is located
share directory, usually PREFIX/share/moin - this is where the templates are located
data directory (wiki pages, users, etc.) - only MoinMoin should access this
underlay directory (wiki pages) - only MoinMoin should access this
htdocs directory with html support files (images for the various themes, etc.) - the web server will need to access this
server - MoinMoin example startup files (like moin.cgi for CGI, and other files for other startup methods)
config - MoinMoin example configuration files (like wikiconfig.py)
bin directory with some scripts that help you use the MoinMoin shell commands
We talk of templates in the share directory because you usually will not use those files at that location, but copy them elsewhere when you need them. This way, you can set-up several wikis without problems, and easily upgrade to new MoinMoin versions. Please see WikiInstanceCreation