Add basic docs for demo, installation, development

docs/install/integration.rst

@@ -0,0 +1,130 @@
+
+.. highlight:: ini
+
+Integrating the POS
+===================
+
+The general process of integrating a POS is roughly the same (so far)
+regardless of which POS system is involved.  Here we describe the
+setup etc.
+
+We will use CORE-POS as our example, for a few reasons, not least of
+which is that it's also free (libre) software.  See
+:ref:`pos-integration` for links to others.
+
+
+Install Packages
+----------------
+
+Please remember to activate your virtual environment.
+
+The first thing is, you must install the POS integration packages.
+The packages for CORE-POS are publiclly available, in which case if
+you just want the latest releases:
+
+.. code-block:: sh
+
+   pip install tailbone-theo[app,corepos]
+
+Or if you want to run from source then you can clone/install these:
+
+* https://kallithea.rattailproject.org/rattail-project/pycorepos
+* https://kallithea.rattailproject.org/rattail-project/rattail-corepos
+* https://kallithea.rattailproject.org/rattail-project/tailbone-corepos
+
+But then just in case, do also run the above command as well, to
+ensure all dependencies are got.
+
+
+Modify Config
+-------------
+
+You must tell Alembic how to find all schema extensions for your POS
+integration package.  Modify ``/srv/envs/theo/app/rattail.conf`` per
+the following.
+
+The default contains::
+
+   [alembic]
+   version_locations = rattail.db:alembic/versions
+
+But you now instead need something like::
+
+   [alembic]
+   version_locations = rattail_corepos.db:alembic/versions rattail.db:alembic/versions
+
+Note that the POS integration path should come before the default path
+there.
+
+In the same config file, you should declare your integration to Theo::
+
+   [theo]
+   integrate_corepos = true
+
+
+Migrate Database
+----------------
+
+Most integrations will require some extra tables installed to your
+database.  But installing them is no different than any other
+migration, i.e. just run the normal commands:
+
+.. code-block::sh
+
+   cd /srv/envs/theo
+   bin/alembic -c app/rattail.conf upgrade heads
+
+
+Import POS Data
+---------------
+
+This process can vary a little but a couple of concepts will be useful
+regardless.
+
+First is that data "versioning" must be considered here.  Theo
+normally will use the versioning feature, i.e. whenever a record
+changes, a new "version" record is also created for it.  The logic
+behind this has some performance cost, which is by far most pronounced
+when there are a "lot" of changes within the same database session.
+
+Therefore a workaround is employed when the database is initially
+populated: the versioning feature is disabled for the main import, and
+then version records are created for the initial data in a separate
+step.  So the first import command always includes ``--no-versiong``:
+
+.. code-block:: sh
+
+   cd /srv/envs/theo
+   bin/rattail -c app/quiet.conf -P import-corepos-api --no-versioning
+
+Once all the data lives in Theo, then capture the initial version
+records for everything.
+
+.. code-block:: sh
+
+   bin/rattail -c app/quiet.conf -P --runas corepos import-versions -m "initial data from POS"
+
+Note the ``--runas`` arg above, which declares the Theo username
+responsible.  The user must already exist within Theo, but can be
+created via the Theo web app.
+
+
+Ongoing Sync
+------------
+
+There are a few ways to do the ongoing "sync" between the POS system
+and Theo.  For now we will only describe a very basic sync which
+happens once per night, although could also be used hourly etc.
+
+The idea here is basically just like the initial data import, although
+should not need the versioning workaround.  So one command, something
+like:
+
+.. code-block:: sh
+
+   cd /srv/envs/theo
+   bin/rattail -c app/quiet.conf --runas corepos import-corepos-api
+
+This is a very basic example, in particular does not handle
+"deletions" which may occur in CORE.  For now though we'll leave it at
+that, hopefully more to come later.