paster: add install-iis command to automate IIS handler generation

A new paster command, install-iis, is added that automates generating
the ISAPI-WSGI file that allows IIS to serve up Kallithea's WSGI application
using IIS' ISAPI filters.

The paster command's output also describes the final steps necessary to complete
IIS installation.

kallithea/lib/paster_commands/install_iis.py

@@ -0,0 +1,85 b''
+import os
+import sys
+from paste.script.appinstall import AbstractInstallCommand
+from paste.script.command import BadCommand
+
+# Add location of top level folder to sys.path
+from os.path import dirname as dn
+rc_path = dn(dn(dn(os.path.realpath(__file__))))
+sys.path.append(rc_path)
+
+class Command(AbstractInstallCommand):
+    default_verbosity = 1
+    max_args = 1
+    min_args = 1
+    summary = 'Setup IIS given a config file'
+    usage = 'CONFIG_FILE'
+
+    description = '''
+    Script for installing into IIS using isapi-wsgi.
+    '''
+    parser = AbstractInstallCommand.standard_parser(
+        simulate=True, quiet=True, interactive=True)
+    parser.add_option('--virtualdir',
+                      action='store',
+                      dest='virtualdir',
+                      default='/',
+                      help='The virtual folder to install into on IIS')
+
+    def command(self):
+        config_spec = self.args[0]
+        if not config_spec.startswith('config:'):
+            config_spec = 'config:' + config_spec
+        config_file = config_spec[len('config:'):].split('#', 1)[0]
+        config_file = os.path.join(os.getcwd(), config_file)
+        try:
+            import isapi_wsgi
+        except ImportError:
+            raise BadCommand('missing requirement: isapi-wsgi not installed')
+
+        file = '''import sys
+
+if hasattr(sys, "isapidllhandle"):
+    import win32traceutil
+
+import isapi_wsgi
+import os
+
+def __ExtensionFactory__():
+    from paste.deploy import loadapp
+    from paste.script.util.logging_config import fileConfig
+    fileConfig('%(inifile)s')
+    application = loadapp('config:%(inifile)s')
+
+    def app(environ, start_response):
+        user = environ.get('REMOTE_USER', None)
+        if user is not None:
+            os.environ['REMOTE_USER'] = user
+        return application(environ, start_response)
+
+    return isapi_wsgi.ISAPIThreadPoolHandler(app)
+
+if __name__=='__main__':
+    from isapi.install import *
+    params = ISAPIParameters()
+    sm = [ScriptMapParams(Extension="*", Flags=0)]
+    vd = VirtualDirParameters(Name="%(virtualdir)s",
+                              Description = "Kallithea",
+                              ScriptMaps = sm,
+                              ScriptMapUpdate = "replace")
+    params.VirtualDirs = [vd]
+    HandleCommandLine(params)
+'''
+
+        outdata = file % {
+                'inifile': config_file.replace('\\', '\\\\'),
+                'virtualdir': self.options.virtualdir
+                }
+
+        dispatchfile = os.path.join(os.getcwd(), 'dispatch.py')
+        self.ensure_file(dispatchfile, outdata, False)
+        print 'generating', dispatchfile
+
+        print ('run \'python "%s" install\' with administrative privileges '
+            'to generate the _dispatch.dll file and install it into the '
+            'default web site') % (dispatchfile,)

docs/installation_iis.rst

@@ -1,133 +1,107 b''
 .. _installation_iis:
 
 Installing Kallithea on Microsoft Internet Information Services (IIS)
 =====================================================================
 
 The following is documented using IIS 7/8 terminology. There should be nothing
 preventing you from applying this on IIS 6 well.
 
 .. note::
 
     For the best security, it is strongly recommended to only host the site over
     a secure connection, e.g. using TLS.
 
 Prerequisites
 -------------
 
 Apart from the normal requirements for Kallithea, it is also necessary to get an
 ISAPI-WSGI bridge module, e.g. isapi-wsgi.
 
 Installation
 ------------
 
 The following will assume that your Kallithea is at ``c:\inetpub\kallithea`` and
 will be served from the root of its own website. The changes to serve it in its
 own virtual folder will be noted where appropriate.
 
 Application Pool
 ................
 
 Make sure that there is a unique application pool for the Kallithea application
 with an identity that has read access to the Kallithea distribution.
 
 The application pool does not need to be able to run any managed code. If you
 are using a 32-bit Python installation, then you must enable 32 bit program in
 the advanced settings for the application pool otherwise Python will not be able
 to run on the website and consequently, Kallithea will not be able to run.
 
 .. note::
 
     The application pool can be the same as an existing application pool as long
     as the requirements to Kallithea are enabled by the existing application
     pool.
 
 ISAPI Handler
 .............
 
-The ISAPI handler needs to be generated from a custom file. Imagining that the
-Kallithea installation is in ``c:\inetpub\kallithea``, we would have a file in
-the same directory called, e.g. ``dispatch.py`` with the following contents::
-
-    import sys
+The ISAPI handler can be generated using::
 
-    if hasattr(sys, "isapidllhandle"):
-        import win32traceutil
-
-    import isapi_wsgi
-
-    def __ExtensionFactory__():
-        from paste.deploy import loadapp
-        from paste.script.util.logging_config import fileConfig
-        fileConfig('c:\\inetpub\\kallithea\\production.ini')
-        application = loadapp('config:c:\\inetpub\\kallithea\\production.ini')
+    paster install-iis my.ini --root=/
 
-        def app(environ, start_response):
-            user = environ.get('REMOTE_USER', None)
-            if user is not None:
-                os.environ['REMOTE_USER'] = user
-            return application(environ, start_response)
-
-        return isapi_wsgi.ISAPIThreadPoolHandler(app)
+This will generate a ``dispatch.py`` file in the current directory that contains
+the necessary components to finalize an installation into IIS. Once this file
+has been generated, it is necessary to run the following command due to the way
+that ISAPI-WSGI is made::
 
-    if __name__=='__main__':
-        from isapi.install import *
-        params = ISAPIParameters()
-        sm = [ScriptMapParams(Extension="*", Flags=0)]
-        vd = VirtualDirParameters(Name="/",
-                                  Description = "ISAPI-WSGI Echo Test",
-                                  ScriptMaps = sm,
-                                  ScriptMapUpdate = "replace")
-        params.VirtualDirs = [vd]
-        HandleCommandLine(params)
+    python dispatch.py install
 
-This script has two parts: First, when run directly using Python, it will
-install a script map ISAPI handler into the root application of the default
-website, and secondly it will be called from the ISAPI handler when invoked
-from the website.
+This accomplishes two things: generating an ISAPI compliant DLL file,
+``_dispatch.dll``, and installing a script map handler into IIS for the
+``--root`` specified above pointing to ``_dispatch.dll``.
 
 The ISAPI handler is registered to all file extensions, so it will automatically
-be the one handling all requests to the website. When the website starts the
-ISAPI handler, it will start a thread pool managed wrapper around the paster
+be the one handling all requests to the specified root. When the website starts
+the ISAPI handler, it will start a thread pool managed wrapper around the paster
 middleware WSGI handler that Kallithea runs within and each HTTP request to the
 site will be processed through this logic henceforth.
 
 Authentication with Kallithea using IIS authentication modules
 ..............................................................
 
 The recommended way to handle authentication with Kallithea using IIS is to let
 IIS handle all the authentication and just pass it to Kallithea.
 
 To move responsibility into IIS from Kallithea, we need to configure Kallithea
 to let external systems handle authentication and then let Kallithea create the
 user automatically. To do this, access the administration's authentication page
 and enable the ``kallithea.lib.auth_modules.auth_container`` plugin. Once it is
 added, enable it with the ``REMOTE_USER`` header and check *Clean username*.
 Finally, save the changes on this page.
 
 Switch to the administration's permissions page and disable anonymous access,
 otherwise Kallithea will not attempt to use the authenticated user name. By
 default, Kallithea will populate the list of users lazily as they log in. Either
 disable external auth account activation and ensure that you pre-populate the
 user database with an external tool, or set it to *Automatic activation of
 external account*. Finally, save the changes.
 
 The last necessary step is to enable the relevant authentication in IIS, e.g.
 Windows authentication.
 
 Troubleshooting
 ---------------
 
 Typically, any issues in this setup will either be entirely in IIS or entirely
 in Kallithea (or Kallithea's WSGI/paster middleware). Consequently, two
 different options for finding issues exist: IIS' failed request tracking which
 is great at finding issues until they exist inside Kallithea, at which point the
 ISAPI-WSGI wrapper above uses ``win32traceutil``, which is part of ``pywin32``.
 
 In order to dump output from WSGI using ``win32traceutil`` it is sufficient to
 type the following in a console window::
 
     python -m win32traceutil
 
 and any exceptions occurring in the WSGI layer and below (i.e. in the Kallithea
 application itself) that are uncaught, will be printed here complete with stack
 traces, making it a lot easier to identify issues.

setup.py

@@ -1,184 +1,185 b''
 #!/usr/bin/env python2
 # -*- coding: utf-8 -*-
 import os
 import sys
 import platform
 
 if sys.version_info < (2, 6):
     raise Exception('Kallithea requires python 2.6 or 2.7')
 
 
 here = os.path.abspath(os.path.dirname(__file__))
 
 
 def _get_meta_var(name, data, callback_handler=None):
     import re
     matches = re.compile(r'(?:%s)\s*=\s*(.*)' % name).search(data)
     if matches:
         if not callable(callback_handler):
             callback_handler = lambda v: v
 
         return callback_handler(eval(matches.groups()[0]))
 
 _meta = open(os.path.join(here, 'kallithea', '__init__.py'), 'rb')
 _metadata = _meta.read()
 _meta.close()
 
 callback = lambda V: ('.'.join(map(str, V[:3])) + '.'.join(V[3:]))
 __version__ = _get_meta_var('VERSION', _metadata, callback)
 __license__ = _get_meta_var('__license__', _metadata)
 __author__ = _get_meta_var('__author__', _metadata)
 __url__ = _get_meta_var('__url__', _metadata)
 # defines current platform
 __platform__ = platform.system()
 
 is_windows = __platform__ in ['Windows']
 
 requirements = [
     "waitress==0.8.8",
     "webob==1.0.8",
     "webtest==1.4.3",
     "Pylons==1.0.0",
     "Beaker==1.6.4",
     "WebHelpers==1.3",
     "formencode>=1.2.4,<=1.2.6",
     "SQLAlchemy==0.7.10",
     "Mako>=0.9.0,<=1.0.0",
     "pygments>=1.5",
     "whoosh>=2.4.0,<=2.5.7",
     "celery>=2.2.5,<2.3",
     "babel>=0.9.6,<=1.3",
     "python-dateutil>=1.5.0,<2.0.0",
     "markdown==2.2.1",
     "docutils>=0.8.1,<=0.11",
     "simplejson==2.5.2",
     "mock",
     "pycrypto>=2.6.0,<=2.6.1",
     "URLObject==2.3.4",
     "Routes==1.13",
 ]
 
 if sys.version_info < (2, 7):
     requirements.append("importlib==1.0.1")
     requirements.append("unittest2")
     requirements.append("argparse")
 
 if is_windows:
     requirements.append("mercurial>=2.8.2,<3.2")
 else:
     requirements.append("py-bcrypt>=0.3.0,<=0.4")
     requirements.append("mercurial>=2.8.2,<3.2")
 
 if sys.version_info < (2, 7):
     # Dulwich 0.9.6 and later do not support Python2.6.
     requirements.append("dulwich>=0.9.3,<=0.9.5")
 else:
     requirements.append("dulwich>=0.9.3,<=0.9.7")
 
 dependency_links = [
 ]
 
 classifiers = [
     'Development Status :: 4 - Beta',
     'Environment :: Web Environment',
     'Framework :: Pylons',
     'Intended Audience :: Developers',
     'License :: OSI Approved :: GNU General Public License (GPL)',
     'Operating System :: OS Independent',
     'Programming Language :: Python',
     'Programming Language :: Python :: 2.6',
     'Programming Language :: Python :: 2.7',
     'Topic :: Software Development :: Version Control',
 ]
 
 
 # additional files from project that goes somewhere in the filesystem
 # relative to sys.prefix
 data_files = []
 
 # additional files that goes into package itself
 package_data = {'kallithea': ['i18n/*/LC_MESSAGES/*.mo', ], }
 
 description = ('Kallithea is a fast and powerful management tool '
                'for Mercurial and GIT with a built in push/pull server, '
                'full text search and code-review.')
 
 keywords = ' '.join([
     'kallithea', 'mercurial', 'git', 'code review',
     'repo groups', 'ldap', 'repository management', 'hgweb replacement',
     'hgwebdir', 'gitweb replacement', 'serving hgweb',
 ])
 
 # long description
 README_FILE = 'README.rst'
 CHANGELOG_FILE = 'docs/changelog.rst'
 try:
     long_description = open(README_FILE).read() + '\n\n' + \
         open(CHANGELOG_FILE).read()
 
 except IOError, err:
     sys.stderr.write(
         "[WARNING] Cannot find file specified as long_description (%s)\n or "
         "changelog (%s) skipping that file" % (README_FILE, CHANGELOG_FILE)
     )
     long_description = description
 
 try:
     from setuptools import setup, find_packages
 except ImportError:
     from ez_setup import use_setuptools
     use_setuptools()
     from setuptools import setup, find_packages
 # packages
 packages = find_packages(exclude=['ez_setup'])
 
 setup(
     name='Kallithea',
     version=__version__,
     description=description,
     long_description=long_description,
     keywords=keywords,
     license=__license__,
     author=__author__,
     author_email='[e-mail]',
     dependency_links=dependency_links,
     url=__url__,
     install_requires=requirements,
     classifiers=classifiers,
     setup_requires=["PasteScript>=1.6.3"],
     data_files=data_files,
     packages=packages,
     include_package_data=True,
     test_suite='nose.collector',
     package_data=package_data,
     message_extractors={'kallithea': [
             ('**.py', 'python', None),
             ('templates/**.mako', 'mako', {'input_encoding': 'utf-8'}),
             ('templates/**.html', 'mako', {'input_encoding': 'utf-8'}),
             ('public/**', 'ignore', None)]},
     zip_safe=False,
     paster_plugins=['PasteScript', 'Pylons'],
     entry_points="""
     [console_scripts]
     kallithea-api =    kallithea.bin.kallithea_api:main
     kallithea-gist =   kallithea.bin.kallithea_gist:main
     kallithea-config = kallithea.bin.kallithea_config:main
 
     [paste.app_factory]
     main = kallithea.config.middleware:make_app
 
     [paste.app_install]
     main = pylons.util:PylonsInstaller
 
     [paste.global_paster_command]
     setup-db=kallithea.lib.paster_commands.setup_db:Command
     update-repoinfo=kallithea.lib.paster_commands.update_repoinfo:Command
     make-rcext=kallithea.lib.paster_commands.make_rcextensions:Command
     repo-scan=kallithea.lib.paster_commands.repo_scan:Command
     cache-keys=kallithea.lib.paster_commands.cache_keys:Command
     ishell=kallithea.lib.paster_commands.ishell:Command
     make-index=kallithea.lib.paster_commands.make_index:Command
     upgrade-db=kallithea.lib.dbmigrate:UpgradeDb
     celeryd=kallithea.lib.celerypylons.commands:CeleryDaemonCommand
+    install-iis=kallithea.lib.paster_commands.install_iis:Command
     """,
 )