docs: update Windows installation documentation for Windows 7/Server 2008 R2 and newer

Update to the Windows installation documentation following my setup experience
on our production server.

Changes :

*   Use of Microsoft Visual C++ Compiler for Python 2.7 which simplifies matter
    versus installing Visual Studio 2008 Express, because it removes the need
    to use the Visual Studio 2008 command prompt. It is also a lot smaller to
    download and install. Unfortunately, this means the instruction will only
    work on the same platforms as those which are supported by the compiler.
*   For that reason, I split the documentation into newer and older Windows.
*   Added more explanations where I feel it was necessary based on my experience
*   Added explanation on Git (Warning : I did not try this part)
*   Instructions assumes x64 instead of Win32.
*   Clarified titles
*   Grammar

Potential issues:

*   I have the user install pip system wide so that virtualenv installation is
    easier (especially if using Python 2.7.9 which already includes pip). One
    may prefer to install virtualenv and the pip in the virtual environment (I
    know of no good reason, but it could happen).
*   Removed some line feeds that I found useless. I do not know the .rst
    format, they might be needed. It makes no difference when the documentation
    is generated using make.bat, so I am not sure

Potential improvements:

*   Instructions on using srvany.exe to install as a Windows service
*   Instructions to make a reverse proxy using Apache
*   Instructions to make a reverse proxy using IIS

docs/installation_win.rst

@@ -0,0 +1,238 b''
+.. _installation_win:
+
+
+Installation and upgrade on Windows (7/Server 2008 R2 and newer)
+================================================================
+
+First time install
+::::::::::::::::::
+
+Target OS: Windows 7 and newer or Windows Server 2008 R2 and newer
+
+Tested on Windows 8.1, Windows Server 2008 R2 and Windows Server 2012
+
+To install on an older version of Windows, see `<installation_win_old.html>`_
+
+
+Step 1 - Install Python
+-----------------------
+
+Install Python 2.x.y (x = 6 or 7). Latest version is recommended. If you need another version, they can run side by side.
+
+  DO NOT USE A 3.x version.
+
+- Download Python 2.x.y from http://www.python.org/download/
+- Choose and click on the version
+- Click on "Windows X86-64 Installer" for x64 or "Windows x86 MSI installer" for Win32.
+- Disable UAC or run the installer with admin privileges. If you chose to disable UAC, do not forget to reboot afterwards.
+
+While writing this Guide, the latest version was v2.7.9.
+Remember the specific major and minor versions installed, because they will
+be needed in the next step. In this case, it is "2.7".
+
+
+Step 2 - Python BIN
+-------------------
+
+Add Python BIN folder to the path
+
+You have to add the Python folder to the path, you can do it manually (editing "PATH" environment variable) or using Windows Support Tools that came preinstalled in Vista/7 and later.
+
+Open a CMD and type::
+
+  SETX PATH "%PATH%;[your-python-path]" /M
+
+Please substitute [your-python-path] with your Python installation path. Typically: C:\\Python27
+
+
+Step 3 - Install Win32py extensions
+-----------------------------------
+
+Download pywin32 from:
+http://sourceforge.net/projects/pywin32/files/
+
+- Click on "pywin32" folder
+- Click on the first folder (in this case, Build 219, maybe newer when you try)
+- Choose the file ending with ".amd64-py2.x.exe" (".win32-py2.x.exe" for Win32) -> x being the minor version of Python you installed (in this case, 7).
+  When writing this Guide, the file was:
+  http://sourceforge.net/projects/pywin32/files/pywin32/Build%20219/pywin32-219.win-amd64-py2.7.exe/download (x64)
+  http://sourceforge.net/projects/pywin32/files/pywin32/Build%20219/pywin32-219.win32-py2.7.exe/download (Win32)
+
+
+Step 4 - Install pip
+--------------------
+
+pip is a package management system for Python. You will need it to install Kallithea and its dependencies.
+
+If you installed Python 2.7.9+, you already have it (as long as you ran the installer with admin privileges or disabled UAC).
+
+If it was not installed or if you are using Python>=2.6,<2.7.9:
+
+- Go to https://bootstrap.pypa.io
+- Right-click on get-pip.py and choose Saves as...
+- Run "python get-pip.py" in the folder where you downloaded get-pip.py (may require admin access).
+(See http://stackoverflow.com/questions/4750806/how-to-install-pip-on-windows for explanations or alternatives)
+
+Note that pip.exe will be placed inside your Python installation's Scripts folder, which is likely not on your path.
+
+Open a CMD and type::
+
+  SETX PATH "%PATH%;[your-python-path]\Scripts" /M
+
+
+Step 5 - Kallithea Folder Structure
+-----------------------------------
+
+Create a Kallithea folder structure.
+
+This is only an example to install Kallithea. Of course, you can change it. However, this Guide will follow the proposed structure, so please later adapt the paths if you change them. Folders with NO SPACES are recommended. But you can try it if you are brave...
+
+Create the following folder structure::
+
+  C:\Kallithea
+  C:\Kallithea\Bin
+  C:\Kallithea\Env
+  C:\Kallithea\Repos
+
+
+Step 6 - Install virtualenv
+---------------------------
+
+.. note::
+   A python virtual environment will allow for isolation between the Python packages of your system and those used for Kallithea.
+   It is strongly recommended to use it to ensure that Kallithea does not change a dependency that another software uses or vice versa.
+   If you are using your server (or VM) only for Kallithea, you can skip this step, at your own risk.
+
+Install Virtual Env for Python
+
+In a command prompt type::
+
+  pip install virtualenv
+
+Virtualenv will now be inside your Python Scripts path (C:\\Python27\\Scripts or similar).
+
+To create a virtual environment, run::
+
+  virtualenv C:\Kallithea\Env
+
+
+Step 7 - Install Kallithea
+--------------------------
+
+In order to install Kallithea, you need to be able to run "pip install kallithea". It will use Python pip to install the Kallithea Python package and its dependencies.
+Some Python packages use managed code and need to be compiled.
+This can be done on Linux without any special steps. On Windows, you will need to install Microsoft Visual C++ compiler for Python 2.7.
+
+Download and install "Microsoft Visual C++ Compiler for Python 2.7" from http://aka.ms/vcpython27
+
+.. note::
+  You can also install the dependencies using already compiled Windows binaries packages. A good source of compiled Python packages is http://www.lfd.uci.edu/~gohlke/pythonlibs/. However, not all of the necessary packages for Kallithea are on this site and some are hard to find, so we will stick with using the compiler.
+
+In a command prompt type (adapting paths if necessary)::
+
+  cd C:\Kallithea\Env\Scripts
+  activate
+
+The prompt will change into "(Env) C:\\Kallithea\\Env\\Scripts" or similar
+(depending of your folder structure). Then type::
+
+  pip install kallithea
+
+(Long step, please wait until fully complete)
+
+Some warnings will appear. Don't worry, they are normal.
+
+
+Step 8 - (Optional) Install git
+-------------------------------
+Mercurial being a python package, it was installed automatically when doing "pip install kallithea".
+
+You need to install git manually if you want Kallithea to be able to host git repositories.
+
+See http://git-scm.com/book/en/v2/Getting-Started-Installing-Git#Installing-on-Windows for instructions.
+
+
+Step 9 - Configuring Kallithea
+------------------------------
+
+Steps taken from `<setup.html>`_
+
+You have to use the same command prompt as in Step 7, so if you closed it, reopen it following the same commands (including the "activate" one).
+
+When ready, type::
+
+  cd C:\Kallithea\Bin
+  paster make-config Kallithea production.ini
+
+Then, you must edit production.ini to fit your needs (IP address, IP port, mail settings, database, etc.) NotePad++ (free) or similar text editors are recommended, as they handle well the EndOfLine character differences between Unix and Windows (http://notepad-plus-plus.org/).
+
+For the sake of simplicity, run it with the default settings. After your edits (if any), in the previous Command Prompt, type::
+
+  paster setup-db production.ini
+
+(This time a NEW database will be installed. You must follow a different step to later UPGRADE to a newer Kallithea version)
+
+The script will ask you for confirmation about creating a NEW database, answer yes (y)
+
+The script will ask you for repository path, answer C:\\Kallithea\\Repos (or similar).
+
+The script will ask you for admin username and password, answer "admin" + "123456" (or whatever you want)
+
+The script will ask you for admin mail, answer "[e-mail]" (or whatever you want)
+
+If you make a mistake and the script doesn't end, don't worry: start it again.
+
+If you decided not to install git, you will get errors about it that you can ignore.
+
+
+Step 10 - Running Kallithea
+---------------------------
+
+In the previous command prompt, being in the C:\\Kallithea\\Bin folder, type::
+
+  paster serve production.ini
+
+Open your web server, and go to http://127.0.0.1:5000
+
+It works!! :-)
+
+Remark:
+If it does not work the first time, Ctrl-C the CMD process and start it again. Don't forget the "http://" in Internet Explorer.
+
+
+What this Guide does not cover:
+
+- Installing Celery
+- Running Kallithea as a Windows Service. You can investigate here:
+
+  - http://pypi.python.org/pypi/wsgisvc
+  - http://ryrobes.com/python/running-python-scripts-as-a-windows-service/
+  - http://wiki.pylonshq.com/display/pylonscookbook/How+to+run+Pylons+as+a+Windows+service
+
+- Using Apache. You can investigate here:
+
+  - https://groups.google.com/group/rhodecode/msg/c433074e813ffdc4
+
+
+Upgrading
+:::::::::
+
+Stop running Kallithea
+Open a CommandPrompt like in Step 7 (cd to C:\Kallithea\Env\Scripts and activate) and type::
+
+  pip install kallithea --upgrade
+  cd \Kallithea\Bin
+
+Backup your production.ini file now.
+
+Then, run::
+
+  paster make-config Kallithea production.ini
+
+Look for changes and update your production.ini accordingly.
+
+Then, update the database::
+
+  paster upgrade-db production.ini
+
+Full steps in `<upgrade.html>`_

docs/index.rst

@@ -1,66 +1,67 b''
 .. _index:
 
 .. include:: ./../README.rst
 
 Users Guide
 -----------
 
 **Installation:**
 
 .. toctree::
    :maxdepth: 1
 
    installation
    upgrade
+   installation_win
    installation_win_old
    installation_iis
    setup
 
 **Usage**
 
 .. toctree::
    :maxdepth: 1
 
    usage/general
    usage/git_support
    usage/performance
    usage/locking
    usage/statistics
    usage/backup
    usage/subrepos
    usage/debugging
    usage/troubleshooting
 
 **Develop**
 
 .. toctree::
    :maxdepth: 1
 
    contributing
    changelog
 
 **API**
 
 .. toctree::
    :maxdepth: 1
 
    api/api
    api/models
 
 
 Other topics
 ------------
 
 * :ref:`genindex`
 * :ref:`search`
 
 .. _virtualenv: http://pypi.python.org/pypi/virtualenv
 .. _python: http://www.python.org/
 .. _django: http://www.djangoproject.com/
 .. _mercurial: http://mercurial.selenic.com/
 .. _bitbucket: http://bitbucket.org/
 .. _subversion: http://subversion.tigris.org/
 .. _git: http://git-scm.com/
 .. _celery: http://celeryproject.org/
 .. _Sphinx: http://sphinx.pocoo.org/
 .. _vcs: http://pypi.python.org/pypi/vcs

docs/installation_win_old.rst

@@ -1,292 +1,291 b''
 .. _installation_win_old:
 
 
-Step by step Installation for Windows
-=====================================
+Installation and upgrade on Windows (XP/Vista/Server 2003/Server 2008)
+======================================================================
 
-
-Kallithea step-by-step install Guide for Windows
+First time install
+::::::::::::::::::
 
 Target OS: Windows XP SP3 32bit English (Clean installation)
 + All Windows Updates until 24-may-2012
 
 .. note::
 
    This installation is for 32bit systems, for 64bit windows you might need
    to download proper 64bit versions of the different packages(Windows Installer, Win32py extensions)
    plus some extra tweaks.
    These extra steps haven been marked as "64bit".
    Tested on Windows Server 2008 R2 SP1, 9-feb-2013.
    If you run into any 64bit related problems, please check these pages:
    - http://blog.victorjabur.com/2011/06/05/compiling-python-2-7-modules-on-windows-32-and-64-using-msvc-2008-express/
    - http://bugs.python.org/issue7511
 
 Step1 - Install Visual Studio 2008 Express
 ------------------------------------------
 
 
 Optional: You can also install MinGW, but VS2008 installation is easier.
 
 Download "Visual C++ 2008 Express Edition with SP1" from:
-http://www.microsoft.com/visualstudio/en-us/products/2008-editions/express
-(if not found or relocated, google for "visual studio 2008 express" for
-updated link)
+http://download.microsoft.com/download/E/8/E/E8EEB394-7F42-4963-A2D8-29559B738298/VS2008ExpressWithSP1ENUX1504728.iso
+(if not found or relocated, google for "visual studio 2008 express" for updated link. This link was taken from http://stackoverflow.com/questions/15318560/visual-c-2008-express-download-link-dead)
 
 You can also download full ISO file for offline installation, just
 choose "All - Offline Install ISO image file" in the previous page and
 choose "Visual C++ 2008 Express" when installing.
 
 .. note::
 
    Using other versions of Visual Studio will lead to random crashes.
    You must use Visual Studio 2008!"
 
 .. note::
 
    Silverlight Runtime and SQL Server 2008 Express Edition are not
    required, you can uncheck them
 
 .. note::
 
    64bit: You also need to install the Microsoft Windows SDK for .NET 3.5 SP1 (.NET 4.0 won't work).
    Download from: http://www.microsoft.com/en-us/download/details.aspx?id=3138
 
 .. note::
 
    64bit: You also need to copy and rename a .bat file to make the Visual C++ compiler work.
    I am not sure why this is not necessary for 32bit.
    Copy C:\Program Files (x86)\Microsoft Visual Studio 9.0\VC\bin\vcvars64.bat to C:\Program Files (x86)\Microsoft Visual Studio 9.0\VC\bin\amd64\vcvarsamd64.bat
 
 
 Step2 - Install Python
 ----------------------
 
 Install Python 2.x.y (x = 6 or 7) x86 version (32bit). DO NOT USE A 3.x version.
 Download Python 2.x.y from:
 http://www.python.org/download/
 
 Choose "Windows Installer" (32bit version) not "Windows X86-64
 Installer". While writing this guide, the latest version was v2.7.3.
 Remember the specific major and minor version installed, because it will
 be needed in the next step. In this case, it is "2.7".
 
 .. note::
 
    64bit: Just download and install the 64bit version of python.
 
 Step3 - Install Win32py extensions
 ----------------------------------
 
 Download pywin32 from:
 http://sourceforge.net/projects/pywin32/files/
 
 - Click on "pywin32" folder
 - Click on the first folder (in this case, Build 217, maybe newer when you try)
 - Choose the file ending with ".win32-py2.x.exe" -> x being the minor
   version of Python you installed (in this case, 7)
   When writing this guide, the file was:
   http://sourceforge.net/projects/pywin32/files/pywin32/Build%20217/pywin32-217.win32-py2.7.exe/download
 
   .. note::
 
      64bit: Download and install the 64bit version.
      At the time of writing you can find this at:
      http://sourceforge.net/projects/pywin32/files/pywin32/Build%20218/pywin32-218.win-amd64-py2.7.exe/download
 
 Step4 - Python BIN
 ------------------
 
 Add Python BIN folder to the path
 
 You have to add the Python folder to the path, you can do it manually
 (editing "PATH" environment variable) or using Windows Support Tools
 that came preinstalled in Vista/7 and can be installed in Windows XP.
 
 - Using support tools on WINDOWS XP:
   If you use Windows XP you can install them using Windows XP CD and
   navigating to \SUPPORT\TOOLS. There, execute Setup.EXE (not MSI).
   Afterwards, open a CMD and type::
 
     SETX PATH "%PATH%;[your-python-path]" -M
 
   Close CMD (the path variable will be updated then)
 
 - Using support tools on WINDOWS Vista/7:
 
   Open a CMD and type::
 
     SETX PATH "%PATH%;[your-python-path]" /M
 
   Please substitute [your-python-path] with your Python installation path.
   Typically: C:\\Python27
 
 
 Step5 - Kallithea folder structure
 ----------------------------------
 
 Create a Kallithea folder structure
 
 This is only a example to install Kallithea, you can of course change
 it. However, this guide will follow the proposed structure, so please
 later adapt the paths if you change them. My recommendation is to use
 folders with NO SPACES. But you can try if you are brave...
 
 Create the following folder structure::
 
   C:\Kallithea
   C:\Kallithea\Bin
   C:\Kallithea\Env
   C:\Kallithea\Repos
 
 
 Step6 - Install virtualenv
 ---------------------------
 
 Install Virtual Env for Python
 
 Navigate to: http://www.virtualenv.org/en/latest/index.html#installation
 Right click on "virtualenv.py" file and choose "Save link as...".
 Download to C:\\Kallithea (or whatever you want)
 (the file is located at
 https://raw.github.com/pypa/virtualenv/master/virtualenv.py)
 
 Create a virtual Python environment in C:\\Kallithea\\Env (or similar). To
 do so, open a CMD (Python Path should be included in Step3), navigate
 where you downloaded "virtualenv.py", and write::
 
  python virtualenv.py C:\Kallithea\Env
 
 (--no-site-packages is now the default behaviour of virtualenv, no need
 to include it)
 
 
 Step7 - Install Kallithea
 -------------------------
 
 Finally, install Kallithea
 
 Close previously opened command prompt/s, and open a Visual Studio 2008
 Command Prompt (**IMPORTANT!!**). To do so, go to Start Menu, and then open
 "Microsoft Visual C++ 2008 Express Edition" -> "Visual Studio Tools" ->
 "Visual Studio 2008 Command Prompt"
 
 .. note::
 
    64bit: For 64bit you need to modify the shortcut that is used to start the
    Visual Studio 2008 Command Prompt. Use right-mouse click to open properties.
 
 Change commandline from::
 
 %comspec% /k ""C:\Program Files (x86)\Microsoft Visual Studio 9.0\VC\vcvarsall.bat"" x86
 
 to::
 
 %comspec% /k ""C:\Program Files (x86)\Microsoft Visual Studio 9.0\VC\vcvarsall.bat"" amd64
 
 
 In that CMD (loaded with VS2008 PATHs) type::
 
   cd C:\Kallithea\Env\Scripts (or similar)
   activate
 
 The prompt will change into "(Env) C:\\Kallithea\\Env\\Scripts" or similar
 (depending of your folder structure). Then type::
 
  pip install kallithea
 
 (long step, please wait until fully complete)
 
 Some warnings will appear, don't worry as they are normal.
 
 
 Step8 - Configuring Kallithea
 -----------------------------
 
 
 steps taken from http://packages.python.org/Kallithea/setup.html
 
 You have to use the same Visual Studio 2008 command prompt as Step7, so
 if you closed it reopen it following the same commands (including the
 "activate" one). When ready, just type::
 
   cd C:\Kallithea\Bin
   paster make-config Kallithea production.ini
 
 Then, you must edit production.ini to fit your needs (ip address, ip
 port, mail settings, database, whatever). I recommend using NotePad++
 (free) or similar text editor, as it handles well the EndOfLine
 character differences between Unix and Windows
 (http://notepad-plus-plus.org/)
 
 For the sake of simplicity lets run it with the default settings. After
 your edits (if any), in the previous Command Prompt, type::
 
  paster setup-db production.ini
 
 (this time a NEW database will be installed, you must follow a different
 step to later UPGRADE to a newer Kallithea version)
 
 The script will ask you for confirmation about creating a NEW database,
 answer yes (y)
 The script will ask you for repository path, answer C:\\Kallithea\\Repos
 (or similar)
 The script will ask you for admin username and password, answer "admin"
 + "123456" (or whatever you want)
 The script will ask you for admin mail, answer "[e-mail]" (or
 whatever you want)
 
 If you make some mistake and the script does not end, don't worry, start
 it again.
 
 
 Step9 - Running Kallithea
 -------------------------
 
 
 In the previous command prompt, being in the C:\\Kallithea\\Bin folder,
 just type::
 
  paster serve production.ini
 
 Open yout web server, and go to http://127.0.0.1:5000
 
 It works!! :-)
 
 Remark:
 If it does not work first time, just Ctrl-C the CMD process and start it
 again. Don't forget the "http://" in Internet Explorer
 
 
 
 What this Guide does not cover:
 
 - Installing Celery
 - Running Kallithea as Windows Service. You can investigate here:
 
   - http://pypi.python.org/pypi/wsgisvc
   - http://ryrobes.com/python/running-python-scripts-as-a-windows-service/
   - http://wiki.pylonshq.com/display/pylonscookbook/How+to+run+Pylons+as+a+Windows+service
 
 - Using Apache. You can investigate here:
 
   - https://groups.google.com/group/rhodecode/msg/c433074e813ffdc4
 
 
 Upgrading
-=========
+:::::::::
 
 Stop running Kallithea
 Open a CommandPrompt like in Step7 (VS2008 path + activate) and type::
 
  easy_install -U kallithea
  cd \Kallithea\Bin
 
 { backup your production.ini file now} ::
 
  paster make-config Kallithea production.ini
 
 (check changes and update your production.ini accordingly) ::
 
  paster upgrade-db production.ini (update database)
 
 Full steps in http://packages.python.org/Kallithea/upgrade.html