Create an application
=====================

This document describes how to create an application using the Nagare framework.

In the following chapters, we will create the application named *my_app*.

1. Create the application skeleton
----------------------------------
    
In a directory of your choice, create the application skeleton:

  .. code-block:: sh

    <NAGARE_HOME>/bin/nagare-admin create-app my_app

This command creates a *my_app* directory with the structure:

  - `setup.py` -- setuptools configuration file
  - `conf` -- directory with all the configuration files of the application
  - `data` -- data directory, contains all the read/write data (database files for example) used by the application
  - `static` -- static directory, contains all the read only data (images, css, js...) used by the application
  - `my_app` -- source directory, contains the application source files 

2. Configure your application
-----------------------------

2.1. File setup.py
~~~~~~~~~~~~~~~~~~

In your application directory, edit the `setup.py` file:
    
  .. code-block:: python

    VERSION = '0.0.1'
    
    from setuptools import setup, find_packages
    
    setup(
          name = 'my_app',
          version = VERSION,
          author = '',
          author_email = '',
          description = '',
          license = '',
          keywords = '',
          url = '',
          packages = find_packages(),
          include_package_data = True,
          package_data = {'' : ['*.cfg']},
          zip_safe = False,
          install_requires = ('nagare',),
          entry_points = """
          [nagare.applications]
          my_app = my_app.app:app
          """
         )

Change the keywords of the ``setup()`` call (ie: author = 'John Doe', description = 
'This is my first application'...) to correctly describe your application.

Note that the ``install_requires`` keyword initially list the ``nagare`` package.
Such that, if someone wants to install you application in a system where
Nagare is not currently installed, it will be automatically downloaded and
installed.

The available keywords are described into the
`Distutils documentation <http://docs.python.org/dist/module-distutils.core.html>`_
and the `Setuptools documentation <http://peak.telecommunity.com/DevCenter/setuptools#new-and-changed-setup-keywords>`_.

2.2. Application configuration file
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Edit the *conf/my_app.cfg* file:
    
  .. code-block:: ini
    
    [application]
    path = app my_app
    name = my_app
    debug = off
    
    [database]
    activated = off
    uri = sqlite:///$here/../data/my_app.db
    metadata = my_app.models:__metadata__
    debug = off

.. note::

  The structure and informations in this file are described with details in
  :wiki:`ApplicationConfiguration`.

Briefly, the **[application]** section contains:

  - `path` -- factory component reference, used by the framework to create the root component of the application
  - `name` -- the url of the application (i.e http://localhost:8080/my_app)
  - `debug` -- debug mode to (de)activate the web error page

and the **[database]** section contains:

  - `activated` -- indicate if the application uses a database
  - `uri` -- database URI for SQLAlchemy
  - `metadata` -- reference to the SQLAlchemy metadata object
  - `debug` -- debug mode to (de)activate the display of the SQL requests

3. Register your application to the Nagare framework
----------------------------------------------------

As the default generated ``setup.py`` declares a ``nagare.applications`` entry point,
once installed, the application is automatically registered to Nagare.

So to register your application, go into the ``my_apps`` directory and simply
enter the command:

  .. code-block:: sh
    
    <NAGARE_HOME>/bin/python setup.py develop  

.. note::

  The entry points you can declare in the `setup.py` file are described
  in :wiki:`EntryPoints`.

You can check your application is correctly registered by launching the command:

  .. code-block:: sh
  
    <NAGARE_HOME>/bin/nagare-admin serve
    
which list all the applications known by the framework.

4. Create the database
----------------------

.. note::

  The document :wiki:`DatabaseTier` describes how to set and use a relational
  database with the framework.
  
If your application uses a database you will need to create the database tables
prior to launch the application:

  .. code-block:: sh
  
    <NAGARE_HOME>/bin/nagare-admin create-db my_app

The options available with the ``create-db`` administrative command are:

  -d, --debug     force the display of the SQL requests 
  --drop          drop the tables if they exist, prior to re-create them
  --no-populate   don't call the populate function after the tables creation

The database tables can be removed with the command:

  .. code-block:: sh
  
    <NAGARE_HOME>/bin/nagare-admin drop-db my_app

5. Launch your application
--------------------------

The following command launches the application:

  .. code-block:: sh
  
    <NAGARE_HOME>/bin/nagare-admin serve my_app

which becomes available at http://localhost:8080/my_app

These options are interesting when you are in development mode:

  -d, --debug    display a specialized web error page when an exception occur
  --reload       automatically reload the application when one of its source file is changed 

.. note::

  The :wiki:`NagareAdmin` guide lists the several administrative
  commands with all their options

6. Distribute your application
------------------------------

When your application is ready to be released, you can create a source
distribution (tarball on Unix, ZIP file on Windows) with the command (into the
``my_apps`` directory):

  .. code-block:: sh
  
    <NAGARE_HOME>/bin/python setup.py sdist
    
The source distribution is created into the *dist* directory.

If you want to globally distribute your application, you can
`register <http://docs.python.org/dist/package-index.html>`_ on the central
`PyPI <http://wiki.python.org/moin/CheeseShopTutorial>`_ repository and
`uploaded <http://docs.python.org/dist/package-upload.html>`_ it there.

You can also create a binary distribution (ie. an *egg*) or a Windows
installer for example, as explain in `setuptools <http://peak.telecommunity.com/DevCenter/setuptools>`_

.. wikiname: ApplicationCreation
