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
`Packaging and Distributing Projects <https://packaging.python.org/tutorials/distributing-packages/#setup-args>`_
documentation.

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
  :doc:`configuration_file`.

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 :doc:`entry_points`.

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 :doc:`database` 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     to display of the generated 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 :doc:`nagare-admin` 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 on the central `PyPI <https://pypi.python.org>`_ repository and
`uploaded <https://packaging.python.org/tutorials/distributing-packages/#upload-your-distributions>`_ it there.

You can also create a binary distribution (ie. a *wheel*) or a Windows
installer for example, as explain in `Packaging your Project <https://packaging.python.org/tutorials/distributing-packages/#packaging-your-project>`_

