-
Notifications
You must be signed in to change notification settings - Fork 8
Installation on Ubuntu 20.04
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.
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
- Run the "legacy" server installer (
ubuntu-20.04.1-legacy-server-amd64.iso) - Install the server system ("Install Ubuntu Server" at the GRUB menu)
- First user account should not be the till account; suggest the person who will be administering the till. (Will have full
sudoaccess.) - Suggest you choose "Guided — use entire disk" in the partitioner
- "Install security updates automatically" is probably a good idea
- Choose "PostgreSQL database" and "OpenSSH server" in the software selection popup. If a label printer will be connected locally, choose "Print server" as well.
- Boot the new system; you should get a login prompt very quickly. Log in using the user account you created during installation.
- You may want to set a root password using
sudo passwd, for logging in as root directly / viasu - If upgrating, import ssh host keys from
/etc/ssh_host_*from the old system - Update packages using
apt-get update,apt-get dist-upgradeandapt-get --purge autoremoveas root - Reboot
- 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 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
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!
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.
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
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"
As root:
adduser till
[answer prompts]
adduser till lp
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.
As root:
su - postgres
createuser -d -e till
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.confto setlisten_addressesto*(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.confto create appropriate username maps - Edit
pg_hba.confto 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
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
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
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
If you want to use the Xero integration, create file /etc/quicktill/default-imports and add the line quicktill.xero.
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!
(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.
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.
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.
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.
Consider disabling systemd units related to sleep and suspend:
systemctl mask sleep.target suspend.target hibernate.target hybrid-sleep.target