Installation on Ubuntu 20.04 - sde1000/quicktill GitHub Wiki

Instructions for setting up quicktill to run locally on Ubuntu 20.04.

Hardware requirements:

  • Tested with an ACR-122U or ACR-1252U NFC reader; should also work with others although the instructions for turning off the "beep" may be different.
  • Assumes you have a touchscreen connected, although could also work with a matrix keyboard or a keyboard/mouse combo.
  • Assumes an Epson TM-T20, Epson TM-U220 or Aures ODP-333 receipt printer. Other receipt printers may also work.
  • If you want to print stock labels, instructions for configuring a DYMO LabelWriter-450 are included. Other label printers should also work; set them up in CUPS and enter the label dimensions in the till config file.

Before starting

Recommendations:

  • Find the MAC address of the new system and set up DNS, DHCP etc. so that it will have a name and static IP address

Install Ubuntu

  1. Run the "legacy" server installer (ubuntu-20.04.1-legacy-server-amd64.iso)
  2. Install the server system ("Install Ubuntu Server" at the GRUB menu)
  3. First user account should not be the till account; suggest the person who will be administering the till. (Will have full sudo access.)
  4. Suggest you choose "Guided — use entire disk" in the partitioner
  5. "Install security updates automatically" is probably a good idea
  6. Choose "PostgreSQL database" and "OpenSSH server" in the software selection popup. If a label printer will be connected locally, choose "Print server" as well.
  7. Boot the new system; you should get a login prompt very quickly. Log in using the user account you created during installation.
  8. You may want to set a root password using sudo passwd, for logging in as root directly / via su
  9. If upgrating, import ssh host keys from /etc/ssh_host_* from the old system
  10. Update packages using apt-get update, apt-get dist-upgrade and apt-get --purge autoremove as root
  11. Reboot
  12. I recommend the rest of the installation be done over ssh from another system, for the convenience of cut-and-paste from your web browser!

Add the quicktill repository

Add the key; as root:

apt-key add <<EOF
-----BEGIN PGP PUBLIC KEY BLOCK-----

mQGNBF+1RAABDADf1ShTPOBMZCocpniMNTgBkEoktMrQTp6m6cTx+jyfl8Tt7/k3
PE1mOeFF5a6Cfkz5xIbE/05x8V9+ix2qOj3Z/g6WpHBhCWEkB6Sfx2s8G5rSGJin
ip2MO3ieYpwbrRVT5BkL12zb4+mZ45UqywrRBoJGii60jcFQu/cG0qAC6pRsxgXg
IPSo1wqgl6RAr6Q/6j4wDv/B0EOPkxexjLP08SHbGBIbaqkMyGinC9ztWt2HnLu6
pTJDfSXX1zxv88rABEp9n2P99oo7h476AbG6TGmkSqCDRzcFV0ELpUvZ7eV1SNRH
eSW74QcKuJXx+SWnbb7gVKWlnhxvWOhCoE0U1/iCUnbDimS/wmyBPmMRq/tlfuW4
ANeHaneo02QFpSlSN4LctHOnh0pur/v0TUnfzyyybUSw0+j/E8tIcINOJAd4Q5Ca
zoIFtwuNUbsaGarkPoifL+IZfymDVwCMdoU1y+VZ/OdJ8tXNv+K4749M4TAQh4Nz
gtLFXclvdTnh9G0AEQEAAbQ4UXVpY2t0aWxsIHJlcG9zaXRvcnkgc2lnbmluZyBr
ZXkgPHN0ZXZlQGFzc29ydGVkLm9yZy51az6JAdQEEwEKAD4WIQTKFvDXC5y5b3+W
R502+MldnVZUvgUCX7VEAAIbAwUJEswDAAULCQgHAwUVCgkICwUWAwIBAAIeAQIX
gAAKCRA2+MldnVZUvgbfC/wN/Y2+6dvFxIGSbjJka3/jkXdckGjvmYabZMNeSD2a
C5lV5MLfDj5QsGVTznNNR7YuwZJswRK2LJEUsEzs9v7lFRxyVbYRb8nZviv3SqAV
adyimApnmJXFxM8CbvMYHTvnJXWiLts3Xiktg0zi48AN9ZQb4EfCclqNbJzt6HNJ
hBsyr1UzJfzZMob6T35v/eS6GczdoyTlg4ff4QQtoaHmsdG/pO4W9bYbpLKfieLv
vEzeKo8f2bqgFgA6TJo0yPC+CgLoBpTDyoclhagTwWu0Jseb3cehTuUIkRh0qNl2
dy63W4nfwjuubfgs58s/zsLu79Dw3bU29lF9bv6CUHuC1khRHEbTenoSKVCANrWu
eR8RUEopAqrAel9TlPVpOc2ZqVlliNg3WgNbHusRJP/lodJn5a6E/wDg75OCaFUN
4PXIn5t1xUFyRMUxtPcGioS3nA+Xa5nEJZKztjIhG+4USKh15qhEn+PvrJD4iOPu
s7K9z0AlSZTF80D8a7HE5k4=
=WsZn
-----END PGP PUBLIC KEY BLOCK-----
EOF

Append the following to /etc/apt/sources.list:

cat >>/etc/apt/sources.list <<EOF
deb http://quicktill.assorted.org.uk/software tills main
EOF

Install packages

As root:

apt-get update
apt-get install quicktill20 quicktill-nfc-bridge quicktill-serial-barcode-bridge userv python3-gi-cairo gir1.2-gtk-3.0 xinit ttf-ubuntu-font-family xterm x11-xserver-utils
apt-get install --no-install-recommends mutter

Also install your favourite editor!

Turn off the NFC reader beep

If you are annoyed by your NFC reader going "beep" every time you wave a card or tag near it, do the following.

Edit /etc/libccid_Info.plist and change ifdDriverOptions to 0x0001

This change will only take effect after a reboot.

Install userv shutdown/reboot services

These allow unprivileged user accounts to shut down or reboot the till, using userv root reboot and userv root poweroff.

As root:

cat >/etc/userv/services.d/reboot <<EOF
if ( glob service-user root
   )
        reset
        no-set-environment
        suppress-args
        no-disconnect-hup
        execute reboot
EOF
cat >/etc/userv/services.d/poweroff <<EOF
if ( glob service-user root
   )
        reset
        no-set-environment
        suppress-args
        no-disconnect-hup
        execute poweroff
EOF

Set stable name for receipt printer

Copy the following to /etc/udev/rules.d/60-receipt-printers.rules:

# Epson receipt printers
SUBSYSTEM=="usbmisc", ATTRS{idVendor}=="04b8", ATTRS{idProduct}=="0e03", SYMLINK+="epson-tm-t20"
SUBSYSTEM=="usbmisc", ATTRS{idVendor}=="04b8", ATTRS{idProduct}=="0e15", SYMLINK+="epson-tm-t20ii"
SUBSYSTEM=="usbmisc", ATTRS{idVendor}=="04b8", ATTRS{idProduct}=="0202", SYMLINK+="epson-tm-u220"

# Aures receipt printer
SUBSYSTEM=="usbmisc", ATTRS{idVendor}=="0525", ATTRS{idProduct}=="a700", SYMLINK+="aures-odp-333"

Set up the till user

As root:

adduser till
[answer prompts]
adduser till lp

Decide on a database name

Till data will be kept in a postgresql database. Decide what you are going to call it; usually something derived from the name of the site ("haymakers", "chesham", etc.) will be best. You'll need this name later.

Set up postgresql

As root:

su - postgres
createuser -d -e till

Set up remote access to postgresql

If you are going to be using more than one till terminal, or running the till admin web interface on a different machine, you must arrange for these machines to be able to connect to postgresql. This is done in files in /etc/postgresql/12/main/.

Briefly:

  • Edit postgresql.conf to set listen_addresses to * (or some other appropriate list of addresses)
  • If you are going to be using "ident" authentication and the usernames on remote systems don't match the usernames on the till, edit pg_ident.conf to create appropriate username maps
  • Edit pg_hba.conf to allow access to the till database from all necessary hosts.

An example pg_hba.conf:

# Tills and stock control terminals
host    pembury till    172.30.53.129/32  trust  # any remote username will allow access as 'till'
host    pembury till    172.30.52.136/32  ident  # remote username 'till' will allow access as 'till'
host    pembury till    172.30.52.137/32  ident
host    pembury till    172.30.52.154/32  ident

Changes to these files don't take effect until postgresql is restarted:

systemctl restart postgresql.service

Fix postgresql startup sequence

If you edited postgresql.conf and set listen_addresses to anything other than * or localhost, you will probably find that postgresql tries to start at the wrong point in the boot sequence before those interfaces are configured, and ends up failing. To fix this, create the following as /etc/systemd/system/[email protected]/override.conf:

[Unit]
Wants=network-online.target
After=network-online.target

Create the till configuration file

Log in as "till" and create a directory configweb for the configuration. Create the till configuration file in this directory, for example cp /usr/share/doc/quicktill20/examples/emfcamp.py ~/configweb/mysite.py

Add till config pointer file

To set the location of the configuration file you just created, so that you don't have to pass it as an option on the runtill command every time, create the directory /etc/quicktill/ as root and add a file configurl pointing to your configuration file:

mkdir /etc/quicktill/
echo file:///home/till/configweb/mysite.py >/etc/quicktill/configurl

Enable Xero integration

If you want to use the Xero integration, create file /etc/quicktill/default-imports and add the line quicktill.xero.

Edit the till configuration file as required

You can check the config file for errors by running a till command like runtill dbsetup; if it fails to crash (and outputs default database contents) then the config file is at least syntactically correct!

Create the till database

(If upgrading an existing till, create the database and import the database dump from the old installation instead.)

createdb mysite
runtill syncdb

Run runtill dbsetup >database-setup.yaml to get a default database setup file, edit it to suit, and then run runtill dbsetup database-setup.yaml to load it into the database.

Create the first till user

The first till user will be a "superuser" with all permissions that will be used for the rest of the setup, interactively on the till and through the web interface.

Run the following command, substituting the names as appropriate:

runtill adduser --webuser web-username "Full Name" "Short Name" $(runtill show-usertoken)

The command will appear to hang. Touch your token to the reader to continue; you'll use this to log in to the till interactively.

Create startup script

Copy /usr/share/doc/quicktill20/examples/login-scripts/startup-with-matchbox.sh to the till user's home directory.

Test using startx ./startup-with-matchbox.sh while logged in as till on the console.

Edit startup-with-matchbox.sh to set font sizes, etc. as required. Colours and fonts for on-screen buttons can be set using the gtk:custom_css config option.

Setup auto-login of till user

Append /usr/share/doc/quicktill20/examples/login-scripts/bash-profile-fragment to .profile:

cat /usr/share/doc/quicktill20/examples/login-scripts/bash-profile-fragment >>.profile

Copy /usr/share/doc/quicktill20/examples/login-scripts/login-till to /usr/local/bin/, and /usr/share/doc/quicktill20/examples/login-scripts/override.conf to /etc/systemd/system/[email protected]. As root:

cp /usr/share/doc/quicktill20/examples/login-scripts/login-till /usr/local/bin/
mkdir -p /etc/systemd/system/[email protected]
cp /usr/share/doc/quicktill20/examples/login-scripts/override.conf /etc/systemd/system/[email protected]/
systemctl daemon-reload

When you next log out on tty1, the till software should be started automatically.

Disable sleep

Consider disabling systemd units related to sleep and suspend:

systemctl mask sleep.target suspend.target hibernate.target hybrid-sleep.target