Add docs for app structure, and creating new project

docs/newproject.rst

@@ -0,0 +1,154 @@
+
+Creating a New Project
+======================
+
+.. contents:: :local:
+
+.. highlight:: bash
+
+This describes the process of creating a new app project based on
+Rattail/Tailbone.  It assumes you are working from a supported :doc:`devenv`.
+
+Per convention, this doc uses "Poser" (and ``poser``) to represent the custom
+app.  Please adjust commands etc. accordingly.  See also :doc:`structure`.
+
+
+Create the Virtual Environment
+------------------------------
+
+First step is simple enough::
+
+   mkvirtualenv poser
+
+Then with your new environment activated, install the Tailbone package::
+
+   pip install Tailbone
+
+
+Create the Project
+------------------
+
+Now with your environment still activated, ``cd`` to wherever you like
+(e.g. ``~/src``) and create a new project skeleton like so::
+
+   mkdir -p ~/src
+   cd ~/src
+   pcreate -s rattail poser
+
+This will have created a new project at ``~/src/poser`` which you can then edit
+as you wish.  At some point you will need to "install" this project to the
+environment like so (again with environment active)::
+
+   cd ~/src/poser
+   pip install -e .
+
+
+Setup the App Environment
+-------------------------
+
+Any project based on Rattail will effectively be its own "app" (usually), but
+Rattail itself provides some app functionality as well.  However all such apps
+require config files, usually.  If running a web app then you may also need to
+have configured a folder for session storage, etc.  To hopefully simplify all
+this, there are a few commands you should now run, with your virtual
+environment still active::
+
+   rattail make-appdir
+   cdvirtualenv app
+   rattail make-config -T rattail
+   rattail make-config -T quiet
+   rattail make-config -T web
+
+This will have created a new 'app' folder in your environment (e.g. at
+``/srv/envs/poser/app``) and then created ``rattail.conf`` and ``web.conf``
+files within that app dir.  Note that there will be other folders inside the
+app dir as well; these are referenced by the config files.
+
+But you're not done yet...  You should likely edit the config files, at the
+very least edit ``rattail.conf`` and change the ``default.url`` value (under
+``[rattail.db]`` section) which defines the Rattail database connection.
+
+
+Create the Database
+-------------------
+
+If applicable, it's time for that.  First you must literally create the user
+and database on your PostgreSQL server, e.g.::
+
+   sudo -u postgres createuser --no-createdb --no-createrole --no-superuser poser
+   sudo -u postgres psql -c "alter user poser password 'mypassword'"
+   sudo -u postgres createdb --owner poser poser
+
+Then you can install the schema; with your virtual environment activated::
+
+   cdvirtualenv
+   alembic -c app/rattail.conf upgrade heads
+
+At this point your 'poser' database should have some empty tables.  To confirm,
+on your PG server do::
+
+   sudo -u postgres psql -c '\d' poser
+
+
+Create Admin User
+-----------------
+
+If your intention is to have a web app, or at least to test one, you'll
+probably want to create the initial admin user.  With your env active::
+
+   cdvirtualenv
+   rattail -c app/quiet.conf make-user --admin myusername
+
+This should prompt you for a password, then create a single user and assign it
+to the Administrator role.
+
+
+Install Sample Data
+-------------------
+
+If desired, you can install a bit of sample data to your fresh Rattail
+database.  With your env active do::
+
+   cdvirtualenv
+   rattail -c app/quiet.conf -P import-sample
+
+
+Run Dev Web Server
+------------------
+
+With all the above in place, you may now run the web server in dev mode::
+
+   cdvirtualenv
+   pserve --reload app/web.conf
+
+And finally..you may browse your new project dev site at http://localhost:9080/
+(unless you changed the port etc.)
+
+
+Schema Migrations
+-----------------
+
+Often a new project will require custom schema additions to track/manage data
+unique to the project.  Rattail uses `Alembic`_ for handling schema migrations.
+General usage of that is documented elsewhere, but a little should be said here
+regarding new projects.
+
+.. _Alembic: https://pypi.python.org/pypi/alembic
+
+The new project template includes most of an Alembic "repo" for schema
+migrations.  However there is one step required to really bootstrap it, i.e. to
+the point where normal Alembic usage will work: you must create the initial
+version script.  Before you do this, you should be reasonably happy with any
+ORM classes you've defined, as the initial version script will be used to
+create that schema.  Once you're ready for the script, this command should do
+it::
+
+   cdvirtualenv
+   bin/alembic -c app/rattail.conf revision --autogenerate --version-path ~/src/poser/poser/db/alembic/versions/ -m 'initial Poser tables'
+
+You should of course look over and edit the generated script as needed.  One
+change in particular you should make is to add a branch label, e.g.:
+
+.. code-block:: python
+
+   branch_labels = ('poser',)