<> = 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 [[Deployment/Setup|Fabric Deployment]]. It also must have [[https://git-scm.com/|Git]] installed. You must have a "fresh" Linux machine, to be used as [[Deployment/ServerMachinePrep|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.) Login, then "become root" to see the entire app. == 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. {{{#!wiki note 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 }}}