// SOLACE //

                    ~ a multilingual support system ~


    ~ INTRODUCTION ~

        Solace is a multilingual support system developed at Plurk
        for end user support.  The application design is heavily
        influenced by bulletin boards like phpBB and the new
        stackoverflow programming community site.

    ~ INSTALLING ~

        For a four-step quickstart have a look at the end of the
        file.  It explains how to quickly test Solace on your
        local box.

        Solace is developed in Python as a standard conforming WSGI
        application with the help of the following libraries:

            -   Werkzeug
            -   Jinja2
            -   SQLAlchemy
            -   Babel
            -   creoleparser
            -   simplejson

        If you want to hack on Solace on your own the best way to get
        started is using the all-mygthy `setup.py` script in a virtual
        Python environment.

        If you're not familiar with virtualenv, be sure to have it
        installed and run it like this in the solace folder:

            $ virtualenv env

        Aferwards you can activate it.  On linux or OS X you can use
        the following command:

            $ source env/bin/activate

        If you're working on a Windows box, use the activate batch
        file instead:

            $ env\Scripts\activate.bat

        After you have activated the environment you can use the
        `develop` command from the setup script to start working on
        Solace:

            $ python setup.py develop

        If you have pip, you can also use the editable install
        switch to accomplish the same:

            $ pip install --editable .

        If you want to install it into a virtual environment (or
        system wide, which we however do not recommend) you can use
        the `install` command

            $ python setup.py install

        Or again also pip is possible:

            $ pip install .

        Both `develop` and `install` will take care of dependencies
        for you.

    ~ THE CONFIGURATION ~

        Where does Solace get the settings from?  It comes with some
        default settings that unless overridden will be the ones it
        uses.  The defaults are intended for development purposes only
        have *have to be changed* if you want to use Solace in
        production.

        When Solace initializes it checks for a `SOLACE_SETTINGS_FILE`
        operating system environment variable.  If it finds one, it will
        execute the that file as a Python script and overrides the
        assigned variables of the Solace enviroment script config
        (`solace/settings.py`).

        Example configuration:

            DATABASE_URI = 'mysql://root@localhost/my_database'
            SECRET_KEY = 'a-super-secret-and-random-key'

    ~ SERVER SETUP ~

        As mentioned before Solace is a WSGI application.  The WSGI
        application object is know as `solace.application.application`.
        For example if you want to use `mod_wsgi` all you have to do
        is to create a `solace.wsgi` file with the following contents:

            from solace.application import application

        This however would require that the `SOLACE_SETTINGS_FILE`
        variable is set in the server config.  If you don't want to
        do that, you can also set it in the `.wsgi` file or tell
        the settings system to load the config from a file:

            from solace import settings
            settings.configure_from_file('/var/www/solace/solace.cfg')
            from solace.application import application

        Be sure to use absolute paths for the configuration!

    ~ LOCAL TEST SERVER ~

        If you want to test Solace locally or hack on it, you can use
        the `runserver` command of the setup script:

            $ python setup.py runserver

        This will start a development server on `localhost:3000`.

    ~ DATABASE INITIALIZATION ~

        Solace uses a database for testing.  Currently the following
        database systems are supported:

        - sqlite3
        - MySQL
        - Postgres

        We recommend sqlite3 for testing (which incidentally is the
        default) and Postgres for production.

        To initialize the database make sure to have the database
        URI set in a config, the `SOLACE_SETTINGS_FILE` environment
        variable exported and then run the following command:

            $ python setup.py initdb

        This will create the database tables for you.

        If you also want a administrator user to be created you
        can sue the `reset` command instead:

            $ python setup.py reset

        This is especially handy during development.

    ~ TESTING ~

        Solace is using standard Python unittests which you can run
        from the `setup.py` script

            $ python setup.py test

        If you want to fill the database with data for testing you can
        use the setup script as well:

            $ python setup.py make_testdata

	Warning on tests: For tests make sure to have a newer version
	than 0.5.1 in your venv (at the time of this writing this means
	installing a development version) due to a bug in the redirect
	support and path quoting of the test client in 0.5.1.

    ~ QUICKSTART ~

        - make sure to have virtualenv installed
        - run "virtualenv env" in the folder that contains this file.
        - depending on your operating system run:
          Windows: "env\Scripts\activate.bat"
          Linux / OS X: "source env/bin/activate"
        - run "python setup.py develop"
        - run "python setup.py reset"
        - run "python setup.py runserver"

        The server will then run on `localhost:3000`.  The database
        is stored in a temporary folder unless you provide a config.
        This is fine for development and testing.