From 02de0077a2464fe51e775a46376a639c4f03d8d4 Mon Sep 17 00:00:00 2001 From: Lance Edgar Date: Mon, 27 Dec 2021 16:14:27 -0600 Subject: [PATCH] Add basic docs for demo, installation, development --- dev/nodb.conf | 14 +++ dev/tasks.py | 13 ++- docs/conf.py | 5 + docs/demo.rst | 15 +++ docs/develop.rst | 23 +++++ docs/features.rst | 2 + docs/index.rst | 5 +- docs/install/fabric.rst | 7 ++ docs/install/index.rst | 14 +++ docs/install/integration.rst | 130 ++++++++++++++++++++++++++ docs/install/manual.rst | 176 +++++++++++++++++++++++++++++++++++ docs/quickstart.rst | 4 +- 12 files changed, 401 insertions(+), 7 deletions(-) create mode 100644 dev/nodb.conf create mode 100644 docs/demo.rst create mode 100644 docs/develop.rst create mode 100644 docs/install/fabric.rst create mode 100644 docs/install/index.rst create mode 100644 docs/install/integration.rst create mode 100644 docs/install/manual.rst diff --git a/dev/nodb.conf b/dev/nodb.conf new file mode 100644 index 0000000..9a0212a --- /dev/null +++ b/dev/nodb.conf @@ -0,0 +1,14 @@ + +############################################################ +# +# avoid db config (use files only) +# +############################################################ + + +############################## +# rattail +############################## + +[rattail.config] +usedb = false diff --git a/dev/tasks.py b/dev/tasks.py index 2ef8c11..3b31a80 100644 --- a/dev/tasks.py +++ b/dev/tasks.py @@ -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( - os.path.join(envdir, 'Scripts', 'rattail'), - os.path.join(appdir, 'quiet.conf'))) + c.run('{} -c {} -c {} --no-versioning checkdb'.format( + os.path.join(envdir, 'Scripts', 'rattail'), + 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)) diff --git a/docs/conf.py b/docs/conf.py index 14d5234..8e3f7d6 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -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'] diff --git a/docs/demo.rst b/docs/demo.rst new file mode 100644 index 0000000..fe55bc8 --- /dev/null +++ b/docs/demo.rst @@ -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/ diff --git a/docs/develop.rst b/docs/develop.rst new file mode 100644 index 0000000..25e8f82 --- /dev/null +++ b/docs/develop.rst @@ -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. diff --git a/docs/features.rst b/docs/features.rst index 6e1bcfb..2dfed0a 100644 --- a/docs/features.rst +++ b/docs/features.rst @@ -56,6 +56,8 @@ nothing more will happen to it. They are of course kept intact for reporting etc. +.. _pos-integration: + POS Integration --------------- diff --git a/docs/index.rst b/docs/index.rst index b0f1eb1..530e911 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -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 diff --git a/docs/install/fabric.rst b/docs/install/fabric.rst new file mode 100644 index 0000000..0854641 --- /dev/null +++ b/docs/install/fabric.rst @@ -0,0 +1,7 @@ + +Installing with Fabric +====================== + +TODO + +For now please see https://rattailproject.org/moin/Theo/ServerSetup diff --git a/docs/install/index.rst b/docs/install/index.rst new file mode 100644 index 0000000..e41d783 --- /dev/null +++ b/docs/install/index.rst @@ -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 diff --git a/docs/install/integration.rst b/docs/install/integration.rst new file mode 100644 index 0000000..bedcb28 --- /dev/null +++ b/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. diff --git a/docs/install/manual.rst b/docs/install/manual.rst new file mode 100644 index 0000000..d13698a --- /dev/null +++ b/docs/install/manual.rst @@ -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 `_ +* `web.conf `_ + +Put each copy in your Theo "app" folder and edit as needed, in +particular replacing ```` and similar strings (e.g. ```` +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. diff --git a/docs/quickstart.rst b/docs/quickstart.rst index fb0f5f2..0183e3e 100644 --- a/docs/quickstart.rst +++ b/docs/quickstart.rst @@ -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