Introducing a caching layer

docs/index.rst

@@ -13,9 +13,9 @@ Features
     providers (database, OpenID, LDAP, OAuth & REMOTE_USER through
     Flask AppBuilder)
 - A simple semantic layer, allowing users to control how data sources are
-  displayed in the UI by defining which fields should show up in which
-  drop-down and which aggregation and function metrics are made available
-  to the user
+    displayed in the UI by defining which fields should show up in which
+    drop-down and which aggregation and function metrics are made available
+    to the user
 - Integration with most RDBMS through SqlAlchemy
 - Deep integration with Druid.io
 
@@ -25,10 +25,10 @@ Contents
 .. toctree::
     :maxdepth: 2
 
+    installation
     user_guide
 
 
-
 Indices and tables
 ------------------
 

docs/installation.rst

@@ -0,0 +1,103 @@
+Installation & Configuration
+============================
+
+Getting Started
+---------------
+
+Panoramix is currently only tested using Python 2.7.*. Python 3 support is
+on the roadmap, Python 2.6 won't be supported.
+
+Follow these few simple steps to install Panoramix.::
+
+    # Install panoramix
+    pip install panoramix
+
+    # Create an admin user
+    fabmanager create-admin --app panoramix
+
+    # Initialize the database
+    panoramix db upgrade
+
+    # Create default roles and permissions
+    panoramix init
+
+    # Load some data to play with
+    panoramix load_examples
+
+    # Start the development web server
+    panoramix runserver -d
+
+
+After installation, you should be able to point your browser to the right
+hostname:port [http://localhost:8088](http://localhost:8088), login using
+the credential you entered while creating the admin account, and navigate to
+`Menu -> Admin -> Refresh Metadata`. This action should bring in all of
+your datasources for Panoramix to be aware of, and they should show up in
+`Menu -> Datasources`, from where you can start playing with your data!
+
+
+Configuration
+-------------
+
+To configure your application, you need to create a file (module)
+``panoramix_config.py`` and make sure it is in your PYTHONPATH. Here are some
+of the parameters you can copy / paste in that configuration module: ::
+
+    #---------------------------------------------------------
+    # Panoramix specifix config
+    #---------------------------------------------------------
+    ROW_LIMIT = 5000
+    WEBSERVER_THREADS = 8
+
+    PANORAMIX_WEBSERVER_PORT = 8088
+    #---------------------------------------------------------
+
+    #---------------------------------------------------------
+    # Flask App Builder configuration
+    #---------------------------------------------------------
+    # Your App secret key
+    SECRET_KEY = '\2\1thisismyscretkey\1\2\e\y\y\h'
+
+    # The SQLAlchemy connection string.
+    SQLALCHEMY_DATABASE_URI = 'sqlite:////tmp/panoramix.db'
+
+    # Flask-WTF flag for CSRF
+    CSRF_ENABLED = True
+
+    # Whether to run the web server in debug mode or not
+    DEBUG = True
+
+This file also allows you to define configuration parameters used by
+Flask App Builder, the web framework used by Panoramix. Please consult
+the `Flask App Builder Documentation
+<http://flask-appbuilder.readthedocs.org/en/latest/config.html>`_
+for more information on how to configure Panoramix.
+
+
+Caching
+-------
+
+Panoramix uses `Flask-Cache <https://pythonhosted.org/Flask-Cache/>`_ for
+caching purpose. Configuring your caching backend is as easy as providing
+a ``CACHE_CONFIG``, constant in your ``panoramix_config.py`` that
+complies with the Flask-Cache specifications.
+
+Flask-Cache supports multiple caching backends (Redis, Memcache,
+SimpleCache (in-memory), or the local filesystem).
+
+For setting your timeouts, this is done in the Panoramix metadata and goes
+up the "timeout searchpath", from your slice configuration, to your
+data source's configuration, to your database's and ultimately falls back
+into your global default defined in ``CACHE_CONFIG``.
+
+
+Druid
+-----
+
+* From the UI, enter the information about your clusters in the
+    ``Admin->Clusters`` menu by hitting the + sign.
+
+* Once the Druid cluster connection information is entered, hit the
+    ``Admin->Refresh Metadata`` menu item to populate
+
+* Navigate to your datasources