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:7000/ (production)
http://theo-server:7010/ (stage)

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 production environment but not stage; use cd /srv/envs/theo-stage for the latter.

CORE-POS:

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

ECRS Catapult:

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

Theo/ServerSetup