.. % %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% .. % 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.