Theo Server Setup

This describes the setup for a Theo server. See Theo/Overview for info about Theo itself.

Prerequisites

Your personal (e.g. laptop) machine must be setup for Fabric Deployment. It also must have Git installed.

You must have a "fresh" Linux machine, to be used as Deployment Target.

If you will be integrating with a proprietary POS system, you may need to contact me (Lance) to be given some user credentials, necessary to access the integration software. This is because such software may be deemed "trade secrets" and I'd rather play it safe there. See fabenv.py (described below) for more info.

Fetch Theo Source

You must decide where to place "source code" on your personal machine. If you have no preference, may we suggest:

~/src on Linux
C:\src on Windows

Then fetch Theo source code with:

cd ~/src
git clone https://kallithea.rattailproject.org/rattail-project/theo

Edit `fabenv.py`

The fabenv.py file is special in that it contains "secrets" (passwords etc.) and is never committed to any repo. Theo comes with a sample file which you can use as your starting point:

cd ~/src/theo/machines/theo-server
cp fabenv.py.dist fabenv.py

Once you have a fabenv.py file in place, you must edit to ensure all values are correct within it, according to your specific environment etc.

In particular note the env.machine_is_live setting, which you may need to toggle on/off depending on what sort of machine you're deploying to at any given time. (I.e. leave off while testing deployment, then turn on for the final production deployment.)

More Config Tweaks

These may not be strictly necessary, but may be helpful.

Let's say your new Theo/target machine is at 192.168.1.42 but there is no DNS etc. to indicate that. Add an entry to /etc/hosts so we can refer to it by name:

192.168.1.42    theo-server

Things get even easier if you add an entry to ~/.ssh/config with the SSH connection details for the new machine:

Host theo-server
    HostName theo-server
    User lance
    IdentityFile ~/.ssh/lance.id_rsa

Deploy Theo to Target Machine

Yay, the fun part.

Assuming you did the SSH config tweak, we can reference "theo-server" in our command line to deploy (bootstrap) everything. Note that your virtual environment should (still) be active here:

cd ~/src/theo/machines/theo-server
fab2 -e -H theo-server bootstrap-all

That may take a while, depending on various factors.

Viewing the Web App

When deployment completes you should be able to see Theo's web app(s), e.g.:

http://theo-server:7010/ (stage)
http://theo-server:7000/ (production)

(Note that production is not installed by default. You may enable that in fabenv.py but you are encouraged to postpone that until you're happy with the stage install.)

Populate the POS DB Mirror

This step only applies if you enabled the mirror option in fabenv.py. Please note this feature is only supported for ECRS Catapult at this time.

For a normal setup without a mirror, there is only one ("default") POS DB connection defined in config, which points to your true production DB.

But in a mirror setup, a couple of connections are defined: "default" in this case will refer to the mirror, and "production" will refer to your true POS DB.

One implication of this is, if you want to import data from POS into Theo proper, you must first populate the mirror DB, since that is what Theo will read from (i.e. it always reads from the "default" POS DB).

Before populating the mirror, you should decide which tables to populate. Browse to Admin -> App Settings in the web app menu and review the list which is defined by default. Make any changes necessary and save.

Note also that you should already be able to see the (lack of) data within your mirror. Any of the POS views in the web app can show data from either the mirror or your production DB. At this point the mirror should be empty but of course you should see data in the production DB.

Okay now let's populate that mirror. This must be done via command line on your Theo server. The examples below are for the Theo stage environment; use cd /srv/envs/theo instead for production. (And please note that Theo production and stage environments each have their own mirror DB, which must be populated separately!)

ECRS Catapult:

ssh theo-server
cd /srv/envs/theo-stage
sudo -u rattail app/mirror-catapult-first.sh

Import Initial Data from POS

If you're integrating with a POS then you'll want to run the initial data import. Note that these must be ran from the target machine itself, meaning you first must:

ssh theo-server

Then you can run the initial import task depending on which POS you have. Note also that there are two Theo virtual environments installed ('theo' and 'theo-stage'), and each has its own set of software as well as its own database. The commands shown below will update the stage Theo environment but not production; use cd /srv/envs/theo for the latter.

CORE-POS:

cd /srv/envs/theo-stage
sudo -u rattail app/import-corepos-first.sh

ECRS Catapult:

cd /srv/envs/theo-stage
sudo -u rattail app/import-catapult-first.sh

LOC SMS:

cd /srv/envs/theo-stage
sudo -u rattail app/import-locsms-first.sh