// 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:
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).
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:
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.
~ QUICKSTART ~
- make sure to have virtualenv installed
- run "virtualenv env" in the folder that contains this file.
- depending on your operating system run: Windows: "envScriptsactivate.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.