From 1aeebfcd63756af023c870a1d35d7d450317374f Mon Sep 17 00:00:00 2001
From: Lance Edgar <lance@edbob.org>
Date: Mon, 2 Jan 2023 10:10:59 -0600
Subject: [PATCH] Overhaul the quickstart guide, per `rattail make-project`

much better IMHO..
---
 docs/index.rst      |  5 ----
 docs/quickstart.rst | 63 ++++++++++++++++++++++++++++-----------------
 2 files changed, 40 insertions(+), 28 deletions(-)

diff --git a/docs/index.rst b/docs/index.rst
index 2f1de20..fe28833 100644
--- a/docs/index.rst
+++ b/docs/index.rst
@@ -7,11 +7,6 @@ administrators.  It assumes the reader is involved with the creation or
 maintenance of a Poser/Rattail app.  It tries to explain the concepts involved
 and hopefully tie them all together.
 
-If you prefer step-by-step instructions for creating your own app then see also
-the `Rattail Tutorial`_.
-
-.. _Rattail Tutorial: https://rattailproject.org/docs/rattail-tutorial/
-
 This manual is primarily organized around the possible "layers" of a
 Poser/Rattail app:
 
diff --git a/docs/quickstart.rst b/docs/quickstart.rst
index c871472..b6ebc9e 100644
--- a/docs/quickstart.rst
+++ b/docs/quickstart.rst
@@ -4,37 +4,54 @@
 Quick Start
 ===========
 
-This should get you up and running with a custom Rattail app within minutes.
-(For a more thorough treatment see the `Rattail Tutorial`_.)
+This guide will create a new app/project.  It assumes you already
+have, and are somewhat familiar with, Python and PostgreSQL (or
+MySQL).
 
-.. _Rattail Tutorial: https://rattailproject.org/docs/rattail-tutorial/
+NB. the name "poser" is a stand-in, use whatever name you like for
+your app/project.
 
-Go to the `Rattail Demo`_ and generate a new "rattail" type project.  You must
-login to get access; use "chuck" / "admin" for credentials.
+First make and activate a virtual environment::
 
-.. _Rattail Demo: https://demo.rattailproject.org/generate-project
+   python3 -m venv /path/to/envs/poser
+   source /path/to/envs/poser/bin/activate
 
-Name your project whatever you like.  The default is "Okay-Then" so we'll
-assume that here.  You should download a zip file, e.g. ``okay-then.zip`` which
-contains the project files.  Extract it somewhere convenient; we'll use
-``~/src/okay-then``::
+You may need to upgrade pip and friends, depending on the age of your
+python::
 
-   mkdir -p ~/src
-   unzip ~/Downloads/okay-then.zip -d ~/src
+   python -m pip install -U pip setuptools wheel
 
-Your local PostgreSQL service should be available, and user (named ``rattail``)
-and DB (named ``okay-then``) created::
+Install the core Rattail package, with 'db' extra::
 
-   sudo apt install postgresql
-   sudo -u postgres createuser -P rattail
-   sudo -u postgres createdb -O rattail okay-then
+   pip install rattail[db]
 
-Make and activate a virtual environment; e.g. ``/srv/envs/okay-then``::
+Create the PostgreSQL user and DB::
 
-   mkdir -p /srv/envs
-   python -m venv /srv/envs/okay-then
-   source /srv/envs/okay-then/bin/activate
+   sudo -u postgres createuser -P poser
+   sudo -u postgres createdb -O poser poser
 
-With the virtual environment active, run the development bootstrap script::
+Or if using MySQL instead::
 
-   python ~/src/okay-then/dev/bootstrap.py
+   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.