Add basic docs for demo, installation, development

This commit is contained in:
Lance Edgar 2021-12-27 16:14:27 -06:00
parent cfc0e3a25d
commit 02de0077a2
12 changed files with 401 additions and 7 deletions

14
dev/nodb.conf Normal file
View file

@ -0,0 +1,14 @@
############################################################
#
# avoid db config (use files only)
#
############################################################
##############################
# rattail
##############################
[rattail.config]
usedb = false

View file

@ -162,6 +162,10 @@ def make_configs(c, envdir, appdir, info):
c.run('{}/bin/rattail make-config -T quiet -O {}'.format(
envdir, appdir))
# nodb.conf
if not os.path.exists(os.path.join(appdir, 'nodb.conf')):
shutil.copyfile('nodb.conf', os.path.join(appdir, 'nodb.conf'))
# web.conf
if not os.path.exists(os.path.join(appdir, 'web.conf')):
with open('web.conf') as f:
@ -177,11 +181,12 @@ def check_db(c, envdir, appdir):
Do basic sanity checks for Theo database
"""
if sys.platform == 'win32':
c.run('{} -c {} --no-versioning checkdb'.format(
c.run('{} -c {} -c {} --no-versioning checkdb'.format(
os.path.join(envdir, 'Scripts', 'rattail'),
os.path.join(appdir, 'quiet.conf')))
os.path.join(appdir, 'quiet.conf'),
os.path.join(appdir, 'nodb.conf')))
else:
c.run('{}/bin/rattail -c {}/quiet.conf --no-versioning checkdb'.format(
c.run('{0}/bin/rattail -c {1}/quiet.conf -c {1}/nodb.conf --no-versioning checkdb'.format(
envdir, appdir))

View file

@ -36,8 +36,13 @@ release = '0.1.x'
# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
# ones.
extensions = [
'sphinx.ext.intersphinx',
]
intersphinx_mapping = {
'rattail-manual': ('https://rattailproject.org/docs/rattail-manual/', None),
}
# Add any paths that contain templates here, relative to this directory.
templates_path = ['_templates']

15
docs/demo.rst Normal file
View file

@ -0,0 +1,15 @@
Online Demo
===========
There is an online demo for Theo at https://demo-theo.rattailproject.org/
You can login with credentials:
* username: chuck
* passowrd: admin
This demo integrates with CORE-POS (also a demo) which contains some
sample data. The data isn't great but should prove the concepts.
The CORE Office demo may be viewed at https://demo-fannie.rattailproject.org/

23
docs/develop.rst Normal file
View file

@ -0,0 +1,23 @@
Development
===========
Theo by nature is just a "wrapper" project, and as such does not
change terribly often. The underlying packages contain all the "good
stuff" and they change more frequently.
Rattail and Tailbone are the 2 main packages, responsible for the
"core" data layer, and web layer, respectively.
Usually there are also some POS integration packages involved; see
:ref:`pos-integration` for links to those.
Source code for *all* packages is hosted on the rattailproject.org
server, specifically under https://kallithea.rattailproject.org/
You can request an account there, and then "fork" anything as you
like. Or skip the account and just clone whatever.
Note that certain POS integration packages are "restricted" and not
available as part of the public project. If you need access then
please send a request.

View file

@ -56,6 +56,8 @@ nothing more will happen to it. They are of course kept intact for
reporting etc.
.. _pos-integration:
POS Integration
---------------

View file

@ -23,11 +23,14 @@ Please see `https://rattailproject.org/docs/theo/
document.
.. toctree::
:maxdepth: 2
:maxdepth: 3
:caption: Contents:
quickstart
features
demo
install/index
develop
Indices and tables

7
docs/install/fabric.rst Normal file
View file

@ -0,0 +1,7 @@
Installing with Fabric
======================
TODO
For now please see https://rattailproject.org/moin/Theo/ServerSetup

14
docs/install/index.rst Normal file
View file

@ -0,0 +1,14 @@
Installation
============
There are a few ways to go about installing Theo, which we'll describe
here.
.. toctree::
:maxdepth: 2
:caption: Contents:
manual
fabric
integration

View file

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

176
docs/install/manual.rst Normal file
View file

@ -0,0 +1,176 @@
.. highlight:: sh
Installing Manually
===================
See also :doc:`/quickstart`, as it automates many of the steps below.
More general details and background may be found in the Rattail
Manual; see :doc:`rattail-manual:base/index` for that. Here of course
we will focus on Theo, so will be less generic.
The initial setup below will *not* include any POS integration, but
that may optionally be added, and is described in another section.
Prerequisites
-------------
* Python 3.6+
* PostgreSQL
Note that PostgreSQL need not run on the same machine as the Theo app,
it just needs to be accessible over the network by Theo.
These docs assume Linux for the Theo machine, but it is believed that
with minimal tweaks this should work on Windows as well. However it
should be noted that Windows does pose some issues, and this all
likely will work "better" on Linux at this point. Windows "support"
should be considered experimental.
(In any case PostgreSQL can run on a Windows machine if you prefer
that.)
Virtual Environment
-------------------
These docs will assume ``/srv/envs`` for the "home folder" of your
virtual environments.
Create a virtual environment for Theo::
mkdir -p /srv/envs
python3 -m venv /srv/envs/theo
Now activate it with::
source /srv/envs/theo/bin/activate
Remember you can deactivate the virtual environment with::
deactivate
But your environment should be *active* for all commands below.
Install Packages
----------------
In a production environment you probably would want to install
"official" released packages for Theo etc. That can be done for
instance like::
pip install tailbone-theo[app]
That is just an example and would not install any POS integration
packages, only Theo proper.
However in practice you may want to clone the source packages and
install those in "editable" mode instead. In a true development
environment we would suggest keeping the source code *outside* of the
virtual environment, so that is what we'll describe here.
First make and/or move to the parent folder for your source code,
e.g.::
mkdir -p ~/src
cd ~/src
Then clone any packages you don't yet have, e.g.::
git clone https://kallithea.rattailproject.org/rattail-project/rattail
git clone https://kallithea.rattailproject.org/rattail-project/tailbone
git clone https://kallithea.rattailproject.org/rattail-project/theo
Finally install all packages to your virtual environment, e.g.::
pip install -e ~/src/rattail
pip install -e ~/src/tailbone
pip install -e ~/src/theo
But just to be sure no dependencies are missed, you still should run
the same command as would be used in production, e.g.::
pip install tailbone-theo[app]
Note that this command should always be ran *last* after you have
installed all your source packages.
Make Config Files
-----------------
The ``dev/bootstrap.py`` script referenced by :doc:`/quickstart` will
install four different config files, but we'll only install three
here.
First create the "app" folder (will be at ``/srv/envs/theo/app``)::
cd /srv/envs/theo
bin/rattail make-appdir
One of the config files is quite simple and can be copied "as-is" from
elsewhere, but two of them will require some modification depending on
your setup etc. Starting point examples are available for the latter
two, but cannot be used "as-is" due to their nature.
Note that all config files will go directly in the "app" folder we
just made above.
We'll do the more complicated ones first. You can grab copies of them
from Theo source code:
* `rattail.conf <https://kallithea.rattailproject.org/rattail-project/theo/rawfile/master/dev/rattail.conf>`_
* `web.conf <https://kallithea.rattailproject.org/rattail-project/theo/rawfile/master/dev/web.conf>`_
Put each copy in your Theo "app" folder and edit as needed, in
particular replacing ``<ENVDIR>`` and similar strings (e.g. ``<SEP>``
should be either ``/`` on Linux or ``\`` on Windows).
And now for the easy one, you can do this::
cd /srv/envs/theo
bin/rattail -c app/rattail.conf make-config -T quiet -O app
Initialize Database
-------------------
On your PostgreSQL server, if you haven't already, create the user
with which Theo should connect. We suggest "rattail" for the
username::
sudo -u postgres createuser -P rattail
Also create the database for Theo::
sudo -u postgres createdb -O rattail theo
Now back on the Theo server (if different), install the schema to the
database (NB. this assumes your ``rattail.conf`` file correctly points
to the PostgreSQL DB)::
cd /srv/envs/theo
bin/alembic -c app/rattail.conf upgrade heads
You also should create your admin user in Theo, named whatever you
like::
bin/rattail -c app/quiet.conf make-user myusername --admin --full-name "My Actual Name"
Run Web App
-----------
With all the above in place you can run the web app::
cd /srv/envs/theo
bin/pserve --reload file+ini:app/web.conf
And then browse the app at http://localhost:9080/
Note that this is a basic setup and does not cause the web app to run
in the background or after reboot etc. This type of setup is most
useful for development.

View file

@ -23,9 +23,9 @@ and DB (named ``theo``) created::
Make and activate a virtual environment, e.g. ``/srv/envs/theo``::
mkdir -p /srv/envs
python -m venv /srv/envs/theo
python3 -m venv /srv/envs/theo
source /srv/envs/theo/bin/activate
With the virtual environment active, run the development bootstrap script::
python ~/src/theo/dev/bootstrap.py
python3 ~/src/theo/dev/bootstrap.py