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

webdepcompress

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:

$ envScriptsactivate.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 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

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).

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:

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
defualt) 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.