.. highlight:: sh

Quick Start
===========

This guide will create a new app/project.  It assumes you already
have, and are somewhat familiar with, Python and PostgreSQL (or
MySQL).

NB. the name "poser" is a stand-in, use whatever name you like for
your app/project.

First make and activate a virtual environment::

   python3 -m venv /path/to/envs/poser
   source /path/to/envs/poser/bin/activate

You may need to upgrade pip and friends, depending on the age of your
python::

   python -m pip install -U pip setuptools wheel

Install the core Rattail package, with 'db' extra::

   pip install rattail[db]

Create the PostgreSQL user and DB::

   sudo -u postgres createuser -P poser
   sudo -u postgres createdb -O poser poser

Or if using MySQL instead::

   sudo mysql -e "create user poser@localhost"
   sudo mysql -e "alter user poser@localhost identified by 'THEPASSWORD'"
   sudo mysqladmin create poser
   sudo mysql -e "grant all on poser.* to poser@localhost"

Make your app project::

   rattail -n make-project /path/to/src/poser

Your project comes with its own command, to install and configure a
new app instance::

   cd /path/to/envs/poser
   bin/poser -n install

You should now be able to run the web app::

   cd /path/to/envs/poser
   bin/pserve --reload file+ini:app/web.conf

By default you can browse it at http://localhost:9080

Don't forget to ``git commit`` the project etc.