--- /dev/null Thu Jan 01 00:00:00 1970 +0000
+++ b/FEL/admin/install.rst Mon Feb 05 16:54:45 2018 +0100
@@ -0,0 +1,223 @@
+==========================
+Downloading and Installing
+==========================
+
+Downloading
+===========
+The recommended way to download moin2 is to clone
+the moin2 Mercurial repository or its mirror. Open a terminal
+window or a command prompt, cd to the directory that will hold
+your project root directory and enter either one of the commands
+below::
+
+ hg clone http://hg.moinmo.in/moin/2.0 moin-2.0
+
+ OR
+
+ hg clone http://bitbucket.org/thomaswaldmann/moin-2.0 moin-2.0
+
+Now make sure your work directory is using the default branch::
+
+ hg up -C default
+
+An alternative installation method is to download the bz2 archive
+from http://hg.moinmo.in/moin/2.0 and unpack it. Once unpacked,
+continue to follow the instructions below.
+
+Installing
+==========
+Before you can run moin, you need to install it:
+
+Using your standard user account, run the following command
+from the project root directory. Replace <python> in the command
+below with the path to a python 2.7 executable. This is usually
+just "python", but may be "python2.7", "/opt/pypy/bin/pypy"
+or even <some-other-path-to-python>::
+
+ <python> quickinstall.py
+
+ OR
+
+ <python> quickinstall.py <path-to-venv>
+
+The above will download all dependent packages to the PIP cache,
+install the packages in a virtual environment, and compile the translations
+(`*.po` files) to binary `*.mo` files. This process may take several minutes.
+
+The default virtual environment directory name is:
+
+ * ../<PROJECT>-venv-<PYTHON>/
+
+where <PROJECT> is the name of the project root directory, and <PYTHON>
+is the name of your python interpreter. As noted above, the default
+name may be overridden.
+
+Check the output of quickinstall.py to determine whether there were
+fatal errors. The output messages will normally state that stdout
+and stderr messages were written to a file, a few key success/failure
+messages will be extracted and written to the terminal window, and
+finally a message to type "m" to display a menu.
+
+If there are failure messages, see the troubleshooting section below.
+
+Typing "./m" (or "m" on Windows) will display a menu similar to::
+
+ usage: "./m <target>" where <target> is:
+
+ quickinstall update virtual environment with required packages
+ docs create moin html documentation
+ extras install OpenID, Pillow, pymongo, sqlalchemy, ldap, upload.py
+ interwiki refresh contrib/interwiki/intermap.txt (hg version control)
+ log <target> view detailed log generated by <target>, omit to see list
+
+ new-wiki create empty wiki
+ sample create wiki and load sample data
+ restore * create wiki and restore wiki/backup.moin *option, specify file
+ import19 <dir> import a moin 1.9 wiki/data instance from <dir>
+
+ run * run built-in wiki server *options (--port 8081)
+ backup * roll 3 prior backups and create new backup *option, specify file
+ dump-html * create a static HTML image of wiki *options, see docs
+ index delete and rebuild indexes
+
+ css run Stylus and lessc to update theme CSS files
+ tests * run tests, output to pytest.txt *options (-v -k my_test)
+ coding-std correct scripts that taint the repository with trailing spaces..
+ api update moin api docs (files are under hg version control)
+
+ del-all same as running the 4 del-* commands below
+ del-orig delete all files matching *.orig
+ del-pyc delete all files matching *.pyc
+ del-rej delete all files matching *.rej
+ del-wiki create a backup, then delete all wiki data
+
+While most of the above menu choices may be executed now, new users should
+do::
+
+ m sample # in Windows
+ ./m sample # in Unix
+
+to create a wiki instance and load it with sample data. Next, run the
+built-in wiki server::
+
+ m run # in Windows
+ ./m run # in Unix
+
+As the server starts, about 20 log messages will be output to the
+terminal window. Point your browser to http://127.0.0.1:8080, the
+sample Home page will appear and more log messages will be output
+to the terminal window. Do a quick test by accessing some of the
+demo items and do a modify and save. If all goes well, your installation
+is complete. The built-in wiki server may be stopped by typing ctrl-C
+in the terminal window.
+
+Next Steps
+==========
+
+If you plan on contributing to the moin2 project, there are more
+instructions waiting for you under the Development topic.
+
+If you plan on using this wiki as a production wiki,
+then before you begin adding or importing data and registering users
+review the configuration options. See the sections on configuration for
+details. Be sure to edit `wikiconfig.py` (or `wikiconfig_editme.py`) and
+change the settings for:
+
+ * interwikiname
+ * SECRET_KEY
+ * secrets
+
+If you plan on just using moin2 as a desktop wiki (and maybe
+help by reporting bugs), then some logical menu choices are:
+
+ * `./m docs` - to create docs, see User tab, Documentation (local)
+ * `./m extras` - to install Pillow for manipulating images
+ * `./m del-wiki` - get rid of the sample data
+ * `./m new-wiki` or `m import19 ...` - no data or moin 1.9 data
+ * `./m backup` - backup wiki data as needed or as scheduled
+
+Warning: Backing up data at this point may provide a false sense
+of security because no migration tool has been developed to migrate
+data between moin2 versions. In its current alpha state, there
+may be code changes that impact the structure of the wiki data or
+indexes. Should this occur, first try rebuilding the indexes with the
+`./m index` command. If that fails, you must start over with an empty
+wiki and copy and paste the contents of all the old wiki
+items into the new wiki. While no such changes are planned,
+they have happened in the past and may happen in the future.
+
+If you installed moin2 by cloning the Moin2 Mercurial repository,
+then you will likely want to install updates on a periodic basis.
+To determine if there are updates available, open a terminal
+window or command prompt, cd to your project root, and enter the
+command below::
+
+ hg incoming
+
+If there are any updates, a brief description of each update will
+be displayed. To add the updates to your cloned repository, do::
+
+ hg pull -u
+
+After pulling updates, it is best to also rerun the quickinstall process
+to install any changes or new releases to the dependant packages::
+
+ m quickinstall # in Windows
+ ./m run # in Unix
+
+Troubleshooting
+===============
+
+PyPi down
+---------
+Now and then, PyPi might be down or unreachable.
+
+There are mirrors b.pypi.python.org, c.pypi.python.org, d.pypi.python.org
+you can use in such cases. You just need to tell pip to do so::
+
+ # put this into ~/.pip/pip.conf
+ [global]
+ index-url = http://c.pypi.python.org/simple
+
+Bad Network Connection
+----------------------
+If you have a poor or limited network connection, you may run into
+trouble with the commands issued by the quickinstall.py script.
+You may see tracebacks from pip, timeout errors, etc. within the output
+of the quickinstall script.
+
+If this is the case, you may try rerunning the "python quickinstall.py"
+script multiple times. With each subsequent run, packages that are
+all ready cached (view the contents of pip-download-cache) will not
+be downloaded again. Hopefully, any temporary download errors will
+cease with multiple tries.
+
+ActiveState Python
+------------------
+While ActiveState bundles pip and virtualenv in its distribution,
+there are two missing files. The result is the following error
+messages followed by a traceback::
+
+
+ Cannot find sdist setuptools-*.tar.gz
+ Cannot find sdist pip-*.tar.gz
+
+To install the missing files, do the following and then rerun
+"python quickinstall.py"::
+
+ \Python27\Scripts\pip.exe uninstall virtualenv
+ \Python27\Scripts\easy_install virtualenv
+
+Other Issues
+------------
+
+If you encounter some other issue not described above, try
+researching the unresolved issues at
+https://bitbucket.org/thomaswaldmann/moin-2.0/issues?status=new&status=open.
+
+If you find a similar issue, please add a note saying you also have the problem
+and add any new information that may assist in the problem resolution.
+
+If you cannot find a similar issue please create a new issue.
+Or, if you are not sure what to do, join us on IRC at #moin-dev
+and describe the problem you have encountered.