Contents
Sample app setup w/ Catapult integration
Here we describe the steps necessary to get a sample app up and running, which integrates with ECRS Catapult.
Please also see the Rattail Tutorial which contains more generic instructions.
Assumptions
There are many variables affecting how setup should be done. For the sake of example we will assume the following for our setup:
- app will run on Linux machine
- your "personal" machine may not be Linux
- therefore we will use Vagrant/Virtualbox to make a Linux VM
- the app is then installed to the VM
- the app can then run, and you can play around with it to prove concepts etc.
Prerequisites
As stated above, we will be using a Linux VM to run the app. So first of all you will need to install, on your personal machine:
You also must install, on your personal machine:
Restricted Access Credentials
Because ECRS likes to protect their intellectual property, some of the code required by the app is not publicly available. I consider it "open source" in spirit, but in practice the code requires user credentials to be obtained. Therefore to actually make all this work, you will need user credentials, which I can provide. Please reach out if you would like some, although I'll need some sort of confirmation that you have a valid Catapult install/license so I wouldn't be violating their NDA.
Generating a new Project
Everyone gets their own project here. You can visit the Rattail Demo to generate a new project.
See How to Name Your Project for misc. tips on naming. You are encouraged to play around with the tool, using the default "Okay-Then" naming, until you understand how it all works and are ready to generate a "final" project with your desired naming.
Or, if you are just wanting to test the final result without bothering with a custom name, the defaults will work fine. The rest of this document will assume you are using the defaults.
Aside from naming, all other options can be left with default values, except you must be sure to check the "Integrates w/ Catapult" option.
(I have bigger plans for this tool, to generate support for integrating with other POS systems etc., but one thing at a time...)
When you click the "Generate Project" button you should be given a ZIP file to download. We will assume you unzip this to your "source" folder, e.g.:
mkdir -p ~/src unzip ~/Downloads/okay-then.zip -d ~/src/
At that point you would have a ~/src/okay-then folder containing the new project's source code. Once you're happy with it, you can move on to the rest of the setup.
Establish Virtual Environment
Before you can use the new project, you must establish a Python "virtual environment" on your personal machine. You should already have Python itself installed. You can put this virtual environment anywhere you like; these examples will assume /srv/envs is the parent folder (owned by myuser):
sudo mkdir -p /srv/envs sudo chown myuser:myuser /srv/envs python3 -m venv /srv/envs/okay-then
Be sure to "activate" your virtual environment. Then before we do anything else, let's upgrade pip itself:
source /srv/envs/okay-then/bin/activate pip install -U pip
Create a file at /srv/envs/okay-then/pip.conf with these contents, but using your credentials:
[global]
extra-index-url =
https://pypi.rattailproject.org/simple/
https://myuser:mypass@pypi-restricted.rattailproject.org/catapult/
log-file = /srv/envs/okay-then/pip.log
exists-action = iNow with your virtual environment still active, declare the config file:
export PIP_CONFIG_FILE=/srv/envs/okay-then/pip.conf
Then you can install the generated app (and its dependencies) to your virtual environment:
pip install -e ~/src/okay-then
Note that we will *not* be running the app from this virtual environment, which lives on your personal machine. Rather, we will *also* install the app to a Linux VM (next), and that's where we'll run the app.
The main point of the virtual environment, is to allow us to deploy the true app to the Linux VM. To do that, we must also "build a release" for the app, and make it available to the VM:
cd ~/src/okay-then invoke release cp dist/*.gz machines/server/
Establish the `fabenv.py` file
Your project source code contains everything necessary for running the app, as well as deploying it to a Linux machine, with one exception: config secrets.
It is bad practice of course, to commit passwords and the like to a source repo. But in order to fully deploy a Linux machine, you will need the passwords, so what we must do here is maintain a fabenv.py file for each machine you deploy.
The machine "bundle" comes with a sample file for this, so create the effective file via:
cd ~/src/okay-then/machines/server cp fabenv.py.dist fabenv.py chmod 0600 fabenv.py
Then be sure to edit your fabenv.py file, setting passwords and the like as needed.
Most of these are "one and done" meaning they won't really change much, so they're easy to maintain. The "volatile" section at the top is a bit different though. The machine_is_live flag is meant to be turned on only when deploying to a truly live machine, and turned off when just testing with a VM etc. In our example, we are "testing with a VM" and so we'll leave that off.
Establish Linux VM
So far so good, let's create the actual Linux VM to which we'll install the "true" app. Note that this will be a "headless" VM, so command line only in other words, no GUI.
Vagrant should already be installed, so just need to:
cd ~/src/okay-then/machines/server vagrant up
Once that is complete, you can confirm with:
vagrant status
You can SSH into this VM with:
vagrant ssh
Suspend the VM with:
vagrant halt
Reboot the VM (and reload Vagrantfile) with:
vagrant reload
Destroy the VM outright with:
vagrant destroy -f
Deploy App to VM
Now for some fun. First you should run vagrant ssh-config to confirm the details:
(okay-then) lance@viking:~/src/okay-then/machines/server$ vagrant ssh-config Host default HostName 127.0.0.1 User vagrant Port 2222 UserKnownHostsFile /dev/null StrictHostKeyChecking no PasswordAuthentication no IdentityFile /home/lance/src/okay-then/machines/server/.vagrant/machines/default/virtualbox/private_key IdentitiesOnly yes LogLevel FATAL
Based on the above, this would be the command to deploy everything to the VM:
fab2 -e -H vagrant@localhost:2222 -i .vagrant/machines/default/virtualbox/private_key bootstrap-all
That will likely take several minutes to complete. And when it finishes, it just sort of stops running commands, but what is displayed may not make it obvious whether things finished "okay" vs. an error happened. Try running echo $? immediately after it completes; if that returns '0' then all is well, otherwise there was an error and you should look closer at the command output.
Once it has completed okay, a web app should be running which you can access at: http://localhost:9761
Using the Web App
At this point your web app is running, but you cannot login. To create a user account, you first must SSH into the VM itself:
vagrant ssh
From now on all commands shown here must be ran on the VM, as opposed to your personal machine!
Okay now we're on the VM, let's create your admin user account (replace myuser with whatever name you prefer):
cd /srv/envs/okay-then sudo -u rattail bin/rattail -c app/quiet.conf make-user --admin myuser
You now should be able to login to the web app with that account. Please choose "Become Root" from the menu in order to gain full access to the app.
Before we continue, please browse to Admin -> Users via the app menu, and create a new user named 'catapult' with no password. This "user" will be identified as the "author" of data changes which come in from Catapult over time.
And drum roll please... If you browse to anything under the "Catapult" menu within the web app, you will be looking directly at data which lives in the Catapult DB.
Importing data from Catapult
Again these commands must be ran within your VM.
Note that the app has "data versioning" enabled by default. The short version of what this means is, each primary table has a secondary "versions" table, which lets us track each record over time. Why that matters here is, for optimization reasons, we must "disable" versioning while we import the initial data from Catapult, and then in a second step, we will update the version tables.
So let's import that data:
cd /srv/envs/okay-then sudo -u rattail bin/rattail -c app/quiet.conf -P import-catapult --no-versioning -W
That may take several minutes to complete, depending on how much data is in your Catapult DB. When it's done, an email will be sent to the default recipients (which came from your fabenv.py file). The email is sent only when the -W (or --warnings) flag is used.
And now let's update our version tables. Note the --runas catapult which references the user account which you already should have created, above.
sudo -u rattail bin/rattail -c app/quiet.conf -P --runas catapult import-versions -m "initial data from Catapult" -W
And finally, you should be able to browse tables under the People and Products menus within the web app, in order to see the data which now lives in your app's DB but which originally came from Catapult.