Add basic docs for demo, installation, development
This commit is contained in:
Lance Edgar
parent
cfc0e3a25d
commit
02de0077a2
12 changed files with 401 additions and 7 deletions
7
docs/install/fabric.rst
Normal file
7
docs/install/fabric.rst
Normal 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
14
docs/install/index.rst
Normal 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
|
||||
130
docs/install/integration.rst
Normal file
130
docs/install/integration.rst
Normal 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
176
docs/install/manual.rst
Normal 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.
|
||||
Loading…
Add table
Add a link
Reference in a new issue