Setup Development Environment

These are the main requirements for a development environment, as pertains to Rattail:

  • Linux (Debian-ish)

  • Git

  • Python (3.x)

  • virtualenvwrapper

  • PostgreSQL

Technically it’s possible for you to work around some of these, but not all. However this tutorial will assume that all these requirements are met.

Now we’ll go through these requirements in more detail, and how to satisfy each one.


So, the operating system upon which production Rattail software runs, is generally assumed to be Linux. To the author’s knowledge, this holds true across all existing production installs.

There is technically one exception to this: the Rattail “File Monitor service” (which is the Windows equivalent of the Rattail “File Monitor daemon” on Linux) of course does run (only) on Windows, and has been used heavily in production. But one of its primary tasks is usually just to move files (e.g. which emanate from POS system) over to the “real” Rattail server on Linux somewhere.

It is possible that you could run a full Rattail stack on Windows (or MacOS for that matter?), e.g. with PostgreSQL database and web app, possibly even datasync etc. However there is no effort put toward supporting that currently, so again Linux is assumed here.

Now that we’ve established Linux, we go a bit further and specify “Debian-ish” - in practice the only two distros used so far, are Debian and Ubuntu. You are encouraged to use a “stable” version here, regardless of which distro you prefer. It’s likely other distros would work also, as far as just running the app(s); however some of Rattail’s “configuration management” utilities (use of which is of course optional) are built with Debian/Ubuntu in mind.

The “where” question is worth mentioning here too. In practice a production Rattail server can be either a bare-metal machine running on your local network, or indeed a “virtual” machine running either locally or in the cloud. Whether you run locally or in the cloud usually will depend on other factors, e.g. if the app must integrate directly with a POS system then it probably must run on the local network. (And of course you can always run in “both” places, with datasync keeping everything flowing smoothly between them.)

Setting It Up

In this tutorial we will be using Vagrant to spin up a local Debian Linux virtual machine (VM) with VirtualBox as the “provider”. This is primarily so we can show an example which you could reproduce on your end, but also one which could stay “isolated” and not interfere with any other stuff you may have going on.

First thing then, will be to install VirtualBox and Vagrant if you do not already have them. You must install these to your “bare-metal development” machine, i.e. your laptop.

Once those are in place, you can use the Vagrantfile which comes with this (rattail-tutorial) project, to create a new VM. Note that this VM does not come with any special behavior, it’s as “vanilla” as possible.

Here is the contents of this Vagrantfile in case you need to create your own, outside of the rattail-tutorial project:

# -*- mode: ruby; -*-

Vagrant.configure("2") do |config|

  # target machine runs Debian 10 "buster" = "debian/buster64"

  # rattail-tutorial web app "forwarded_port", guest: 9080, host: 9080


Change to the directory which contains your Vagrantfile and then run vagrant up, e.g.:

cd ~/src/rattail-tutorial
vagrant up

Those commands assume your “host” machine (i.e. your laptop) runs Linux too, though of course that may not be so. Please adjust accordingly.

Confirming It Works

There are really two things you should check, to confirm “all is well” regarding your new Linux machine, regardless of whether it’s a Vagrant VM, or some bare-metal machine.

Check #1 - Can you open a console terminal for the machine? If it’s bare-metal then this probably just means making sure the keyboard and/or mouse are working, and you can login. If it’s virtual then this probably means making sure you can ssh into it. (You may want to use ssh even if it’s bare-metal, depending on its role etc.)

Check #2 - Are you able to use sudo for elevated privileges? If the Check #1 passed then you should be able to run e.g. sudo whoami on the terminal. It’s okay to be prompted for a password as long as you know what that is. ;) Otherwise this check fails.

Note that if you’re using Vagrant, you should be able to do vagrant ssh in order to connect, and from there sudo should be no problem.


This one’s pretty obvious and you may already have it, but we’ll cover it anyway to be thorough.

Setting It Up

Install with:

sudo apt install -y git

But we’ll also want to define your Git user identity, e.g.:

git config --global "John Doe"
git config --global ""

Confirming It Works

This should work as expected:

git --version

Also these should output the same values as you defined above:

git config --global
git config --global


Since we’re assuming Linux here (e.g. on the Vagrant VM), you probably already have Python installed. However we do want to make sure you have Python 3.x - since Python 2 is EOL quite soon as of this writing.

Setting It Up

To make sure you have Python 3.x, run the following command:

sudo apt install -y python3 python3-dev

Confirming It Works

You should now be able to confirm a Python 3.x binary with this command:

python3 --version

You probably also should find out where exactly this binary lives:

which python3

The output from that most likely points to /usr/bin/python3 but please make a note of your location if it’s different.

Misc. Other Dependencies

These don’t really fit any other category, and aren’t necessarily required, depending on your project etc. But they’re often necessary and we might as well install them just in case:

sudo apt install -y build-essential


The virtualenvwrapper package is, in this author’s opinion, quite useful for both Rattail development, as well as production installs. For this reason, this tutorial will assume its presence, even though technically Rattail does not require it.

Setting It Up

Before actually installing virtualenvwrapper, let’s prep our “workon home” directory. This tutorial assumes, as do all Rattail docs, that the workon home resides at /srv/envs - again you’re free to use another location, but all docs will assume that one. These commands should prep the workon home folder (adjust path and/or username as needed):

sudo mkdir /srv/envs
sudo chown you:you /srv/envs

Note that for development it’s often convenient to make this folder owned by “you” whereas in production installs the author recommends making this folder owned by a special “rattail” system user.

Now for virtualenvwrapper itself. There are technically a few ways to go about this, but for the sake of the tutorial we’ll just do this:

sudo apt install -y virtualenvwrapper

Next you must add the following to your ~/.bashrc file:

export WORKON_HOME=/srv/envs
source /usr/share/virtualenvwrapper/

And finally you must “re-run” your .bashrc so these things actually take effect for your current session:

source ~/.bashrc

Confirming It Works

First of all just to be 100% sure, you ideally should reboot your new machine, or perhaps at least logout and then login again.

But really the check here, is to make sure the following command runs okay:

workon --help


Rattail uses PostgreSQL exclusively, for its “primary” database backend. So whereas Rattail can interact with many other types of SQL databases, it uses Postgres for its “own” database(s).

Technically the database is optional, depending on how you need to use Rattail, although it is required for the web app.

Setting It Up

There are really two aspects of this setup, a) Postgres proper, and b) Python support for Postgres.

We’ll tackle the first aspect, well, first:

sudo apt install -y postgresql

Next we’ll tackle the second aspect:

sudo apt install -y libpq-dev

Confirming It Works

As with the setup for Postgres, there are really two things to check here.

First, is the PostgreSQL service running and available? You should be able to confirm that with (should output list of databases):

sudo -u postgres psql -l

Second, is Python support for Postgres installed correctly?


what else should we say about the second aspect here? other than, TBD (aka. “when you need it you’ll know”)