## Please edit system and help pages ONLY in the master wiki!
## For more information, please see MoinMoin:MoinDev/Translation.
## DO NOT TRANSLATE THIS PAGE / SUBPAGES OF THIS PAGE.
##master-page:Unknown-Page
##master-date:Unknown-Date
#acl -All:write Default
#format wiki
#language en
#pragma section-numbers off

= Server Installation =
How to setup !MoinMoin for various web servers / gateway interfaces.

{{{#!wiki important
Please note that you require server admin experience for a server installation. It is not in the scope of this documentation to teach you (web) server configuration/administration, but just to show you how !MoinMoin is installed. If you are unsure about your experience level, please try the Quick Installation first. 
}}}


== MoinMoin and WSGI ==
!MoinMoin is a [[http://wsgi.org/|WSGI]] application, therefore the best environment to run a !MoinMoin instance in is a WSGI-aware one.

Here are some of them:
 * '''[[http://httpd.apache.org|Apache]]''' with '''[[http://code.google.com/p/modwsgi|mod_wsgi]]''':
 '''This is the recommended deployment when using Apache. It is very fast and easy to setup.'''
 * '''standalone server''' shipped with !MoinMoin: reasonably fast, also used for the [[../QuickInstall|Quick Installation]]
 * More WSGI server options can be found there: http://wiki.python.org/moin/WSGIImplementations

Also we will cover some legacy deployment methods for serving !MoinMoin from non-WSGI-aware setups. The needed adapters are included in the !MoinMoin distribution.
 * '''CGI''': the classic protocol for web application serving - awfully slow but works (almost) everywhere.
 * '''FastCGI''' / '''SCGI''' / '''AJP''': fast, and in the case of FastCGI, quite widespread.


== Apache with mod_wsgi ==
The details of how to install ''mod_wsgi'' or ''Apache'' is out of scope of this document. Please follow the install instructions for each respective software package.  The [[http://httpd.apache.org/docs/|Apache documentation]] is here, and the  [[http://code.google.com/p/modwsgi/wiki/ConfigurationGuidelines| mod_wsgi instructions]] has set-up details. Some users have documented their install process in detail on the user-supported [[http://moinmo.in/HowTo|how-to]] page on the !MoinMoin wiki.

If everything has been configured to your liking, you can test your setup with the application contained in `test.wsgi` (please read the hints included in the file).

Some further hints for usage of mod_wsgi:
 * If possible, use mod_wsgi's ''daemon mode'' (not the ''embedded mode'').  This can prove more secure since it seperates the WSGI apps from the actual Apache process.
 * If you use Windows, there is no ''daemon mode'', thus you have no other choice than to use ''embedded mode''.


== MoinMoin specific installation ==

=== MoinMoin installation ===
You may, but do not need to, install !MoinMoin to system specific locations via the use of `setup.py`.

(!) You can place the !MoinMoin package (a directory called `MoinMoin/` containing most of the code) anywhere you like, no specific location in the filesystem is required.

If you choose to use `setup.py`, you can install !MoinMoin using:
{{{
python setup.py install --force --record=install.log --prefix='/usr/local' --install-data=/srv
# or alternatively, to the default system location:
python setup.py install --force --record=install.log
# --force is important, without it setup.py might not overwrite outdated files at the destination
}}}

With `--install-data=/path` you could change the prefix of the wiki instance directory (`share/moin`) to `/path`. 

/!\ Please note that using `setup.py` as shown above will overwrite all files at the destination. So if you modified files there, your modifications will be lost. However it won't remove outdated files there so if you had used `setup.py` before for the same destination, maybe clean up at the destination before installing a new moin version.

(!) If you need to modify files, do not do so in their original location, but copy them to some safe place first and then edit them there.

The file `install.log` will contain a complete log of installed files.

You may want to keep it in case you have trouble locating some of the file(s) mentioned below.

=== Python path setup ===

Code: From here on we will use `/moin/code` to refer to the ''parent directory'' of the `MoinMoin/` package directory.

Config: You can place the wiki config files (they are just Python code) anywhere you like, no specific location is required. We will use `/moin/config` to refer to the directory that contains your wiki config files.

To make !MoinMoin and Python find the needed files, you need to make those locations known: 
 * Python needs to be able to find the `MoinMoin` code package - this is needed so that `from MoinMoin import ...` can work. ( (!) This is '''not''' needed if you choose to do a system-wide installation.)
 * Python needs to be able to find the wiki configuration files so that !MoinMoin is able to import them.

For this to work, you can simply edit `moin.wsgi` (or in case you deploy with CGI/FCGI/etc.: the corresponding script for these deployment methods from the `wiki/server/` directory). There is already example code in those files, just remove the comment (# hash character) and change them accordingly:

{{{
sys.path.insert(0, '/moin/code')
sys.path.insert(0, '/moin/config')
}}}

You can place `moin.wsgi` anywhere you like. Just make your web server find and use it.


=== MoinMoin wiki configuration ===
Although the code is now ready to run, your wiki is not configured yet.

You now have to create your wiki configuration within the `/moin/config/` directory.


==== Single wiki ====
Just copy the file `wiki/config/wikiconfig.py` from the distribution archive to `/moin/config/`.

The file is thoroughly commented to ease you through the configuration. Make sure that if you configure paths in the file, that those paths are '''absolute''' paths. This way you ensure that the needed files are definitely found and save yourself some troubles.
The essential configuration directives are:
 * `data_dir`: this should point to where the particular data of your wiki should be stored. (see below)
 * `data_underlay_dir`: !MoinMoin comes with (pre-made) system and help pages. This directive should point to the directory where you put those (see below)
 * `interwikiname`: This should be a short descriptive identifier for your wiki. It needs to be unique and should '''never''' be changed later
 * `sitename`: This will be the name of your wiki for display purposes

/!\ We don't require any specific file system locations, but please be careful: `data_dir` contains sensitive informations that '''must not''' be read by anything or anyone except the running moin wiki code. For example, you '''must not''' make `data_dir` accessible directly via the web server, thus you '''must not''' copy it to a directory below document root of your web server. Any other permanent storage location on a fast local filesystem will be fine.

You need to copy the complete contents of the `wiki/data/` directory we provide in the distribution archive to the location you specified as `data_dir`. The same goes for `wiki/underlay/` and the location you specified as `data_underlay_dir`.


==== Multiple wikis ====
Just copy the files `wiki/config/wikifarm/*` from the dist archive to `/moin/config/`.

Now follow the directions as for a single wiki (see above) for each of your farm wikis.

Special wiki farm hints:
 * You need a separate `data_dir` and `data_underlay_dir` per wiki
 * If you want to share some settings for your wikis, put them into `farmconfig.py` - they will be inherited by `mywiki`
 * The settings that need to be different are put into `mywiki.py`
 * If you need more than 1 wiki, add files like `mywiki.py` and reference them from `farmconfig.py` as you see for `mywiki`


==== Static file serving ====
!MoinMoin also comes with some static files like images, CSS, Javascript, Java applet files, etc. (see the `MoinMoin/web/static/htdocs/` directory in the distribution archive). They are needed for things like styling, icons and additional client-side functionality.

!MoinMoin serves those files by a built-in static file server at the path '/moin_staticXYZ' (XYZ like in !MoinMoin version X.Y.Z, e.g. `/moin_static190` for moin 1.9.0).

Please note that this path is relative to the script root, so:
 * if you run your wiki script at `/mywiki`, the URL for the static files server will be `/mywiki/moin_staticXYZ`. You need to configure `url_prefix_static` in your wiki config to match this.
 * if you run your wiki script at `/`, the URL for the static files server will be `/moin_staticXYZ` - and it will automagically match the default value of `url_prefix_static`, so no need to configure it.


=== Running MoinMoin with Apache / mod_wsgi ===
Now you should be able to simply run the `moin.wsgi` script the same way you ran `test.wsgi` above.


=== Running MoinMoin with other WSGI servers ===
Have a look at `moin.wsgi` and the documentation of your web server's WSGI support. As WSGI is a standard, it should be quite similar and easy to adapt.


=== Running MoinMoin with CGI, FastCGI, SCGI or AJP ===
If you are not running a WSGI capable server and want to deploy !MoinMoin with one of the other methods (like CGI, FastCGI, SCGI or AJP), just use the appropriate script for the desired method from `wiki/server/` (instead of `moin.wsgi`):
 * `moin.cgi`: serves both CGI '''and''' FastCGI requests.
 * `moin.scgi`: serves SCGI capable servers
 * `moin.ajp`: serves AJP capable servers

Now edit that script (similarly as shown above for `moin.wsgi`) to make Python find the moin code and wiki configuration files.

For setting up your particular web server to speak any of these protocols to the moin application, please refer to the web server's documentation.

/!\ When using the scripts for FastCGI, SCGI or AJP ('''not''' CGI), be aware that they can also act as externally spawned processes to the web server. Via the means of commandline parameters they can be bound to an interface or UNIX socket and also do threading or forking for performance.

Try running `moin.cgi --help` for an example. When run without any options by the web server, control of sockets and the like is left to the web server.

Note: The non-WSGI deployment scripts use [[http://trac.saddi.com/flup|flup]] to convert FastCGI/SCGI/AJP/CGI to WSGI (we bundle flup with moin). Please see the flup documentation for more details.


=== Running MoinMoin with anything else ===
In the unlikely case none of the above deployment methods work for you, you can try to:
 * find some WSGI module for ''anything'', or some ''anything''-to-WSGI middleware
 * use it to run the moin WSGI application

Alternatively, you can also run moin with any of the supported methods (on some other IP or some other port) and use your (unsupported) main web server as a proxy.


=== Testing your setup ===
You can test if everything works by following these steps:

 * Access the URL you have configured for your wiki and you should see something that looks similar to the [[http://moinmo.in/|MoinMoin homepage]].
 * Go to the !WikiSandBox page in your wiki.
 * Try to edit it and save your changes.
 * If that works, see if your edit is shown on the RecentChanges page.
 * If you see it, congratulations, your new wiki works! :)


== Troubleshooting ==
When things go wrong and reading the docs does not help, just:
 * ask concrete questions on the MoinMoin:MoinMoinChat
 * and wait until someone answers