.. % %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
.. % Copyright 2011 by Object Craft P/L, Melbourne, Australia.
.. % LICENCE - see LICENCE file distributed with this software for details.
.. % %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%


.. _quickstart:

*****************
Quick Start Guide
*****************

Albatross includes a tool that quickly creates the bare-bones of an Albatross
application:

.. code-block:: none

    albtross create myapp

This will create a directory called ``myapp`` in the current directory. If
you change into this directory, you can easily start this application
using the stand-alone development web server:

.. code-block:: none

    cd myapp
    albatross serve

If you point your web browser at http://localhost:8000/, you should
see the skeleton application in action. To stop the development server,
press ``Ctrl-C`` or ``Ctrl-Break``.

The application directory contains the elements of a basic application:

* ``app.py`` is the main script that creates the application object,
* ``app.ini`` contains configuration settings such as the name of the initial
  page, and the name of the application
* ``app.log`` contains details of any exceptions that occur while the
  application is running. Your application can also call :meth:`ctx.log`
  to save debugging information to the log.
* ``pages`` contains the application pages (``.py`` extension) and associated
  HTML templates (``.html`` extension).
* ``static`` contains the elements of the application which are not
  dynamically generated, such as the style sheet and any graphical assets.
* ``session`` contains the user session data when the session-file based
  context model is used.

The skeleton application implements several pages for demonstration
purposes.  You can (and should) replace or remove these to suit your
purposes. Each page has a ``.py`` file containing code, and usually an
``.html`` file containing the associated HTML template. The demonstration
pages are:

* ``environment`` - this displays the current system environment variables.
  You should not leave this page in place on a production server, as this
  information might help attackers.
* ``main`` - this is the initial application page. If you want another page
  to display when users first access your application, you should edit the
  ``app.ini`` file and change the ``start_page`` variable
* ``new_session`` - this page just deletes the user's current session. If you
  implement a user login scheme, you could implement something similar to log
  the user out.
* ``raise_exception`` - this page contains a deliberate error to demonstrate
  exception handling. 

As well as these application pages, the ``pages`` directory contains several
other template files:

* ``macros.html`` contains page header and footer macros used by all the page
  modules to give a consistent look to the application.
* ``page_not_found.html`` is shown if a user requests a page that doesn't
  exist in the current application.
* ``session_expired.html`` is shown if a user's session has expired due to
  inactivity.
* ``uncaught_exception.html`` is shown by the Albatross framework when an
  unexpected exception occurs in the framework or in your application. The
  demonstration template shows HTML and Python tracebacks.

If you decide at this point that you'd like a new page called ``cool``, run:

.. code-block:: none

    albatross add-page cool

You will now have a ``cool.py`` and ``cool.html`` in the ``pages`` directory.
