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.


There are many variables affecting how setup should be done. For the sake of example we will assume the following for our setup:


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/ -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:

extra-index-url =
log-file = /srv/envs/okay-then/pip.log
exists-action = i

Now 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 `` 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 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
chmod 0600

Then be sure to edit your 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
  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 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.

LilSnippets/CatapultPoserSetup (last edited 2020-09-08 23:59:36 by LanceEdgar)