-
Notifications
You must be signed in to change notification settings - Fork 9
Server installation
Instructions for setting up a quicktill server.
This configuration has the database running on a server, which provides network boot services to till terminals over a private network. Although quicktill is installed on the server and can be started in terminal mode from the command line for testing, the server doesn't act as a till itself.
These instructions are based on Debian bookworm (or the corresponding release of Raspberry Pi OS Lite) but should be possible to adapt for other operating systems if required.
Server hardware requirements:
- Any computer or VM, ideally with at least 4Gb RAM
- One or two real or virtual Ethernet interfaces
- Reliable storage (don't use a SD card with a Raspberry! Use SSD or NVMe)
Client hardware requirements:
- amd64 PC or arm64 Raspberry
- Tested with an ACR-122U or ACR-1252U NFC reader; should also work with other CCID-compatible readers 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.
Network requirements:
- If the server has a single Ethernet port, a VLAN for the clients tagged on the server port of the switch and native on the client ports
- If the server has multiple Ethernet ports, just a network switch for the clients connected to one of the ports
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
Outside the scope of these instructions!
After the installation you should end up with a user account and also
root access either through su or sudo. We'll be creating an
additional user account for the till, so don't call the initial
account "till"!
Some editing of configuration files will be required, so install your
editor of choice. (apt-get --no-install-recommends install emacs-nox
for me.)
We will be using systemd-networkd for network configuration, and nftables for firewalling and NAT. If this isn't the default on your OS (which is likely — on plain Debian it's ifupdown and on Raspberry Pi OS or Ubuntu it's NetworkManager) then put the systemd-networkd configuration files in place, enable and start systemd-networkd and nftables, uninstall the default network configuration package and reboot.
You need some private RFC1918 address space for the till client network. I've arbitrarily picked 172.31.172.0/24 for these instructions; you could pick another range but you would have to make this change in all the configuration files that mention it. As long as it doesn't conflict with any other RFC1918 address space your site uses, you should be fine. This space is configured in the till client booting section below.
If you have two network interfaces, you only need to create one configuration file for systemd-networkd at the moment. If you only have one network interface and will be using a VLAN for the till clients, you need an additional configuration file to set up the VLAN interface.
These files go in /etc/systemd/network.
The local network configuration file is very simple. Substitute your
network interface name for enp1s0 as required. We call this file
10-local.network:
[Match]
Name=enp1s0
[Link]
RequiredForOnline=yes
[Network]
Description=Pub local network
DHCP=yes
(If your network interface is called eth0 or similar [eg. on
Raspberry] then systemd-networkd will whinge that it is a potentially
unpredictable interface name. That's ok, as long as it is the only
ethernet interface. If it isn't, you can give it a stable name;
see the systemd-networkd manual for
details.)
If you have a single ethernet port and are using a tagged VLAN for the
till client network, you need another configuration file to set up the
VLAN interface. This is 10-tills.netdev; substitute the VLAN ID you
have chosen in the VLAN section:
[NetDev]
Name=tills
Kind=vlan
[VLAN]
Id=7
You will also need to add a line to the Network section of
10-local.network to attach the VLAN:
[Network]
...
VLAN=tills
The systemd-networkd configuration file for the till client network will be generated automatically when you set up the till client booting configuration, later in these instructions.
If the system you are using has systemd-256 or later (eg. Debian 13)
then the forwarding configuration in the generated systemd-networkd
configuration file will not work. If you need the server to foward
connections from the till clients to the outside world, edit
/etc/systemd/networkd.conf and add the line IPv4Forwarding=yes to
the [Network] section. To pick up this configuration change, you
must restart systemd-networkd with systemctl restart systemd-networkd — reloading with networkctl reload is not
sufficient.
The nftables configuration file /etc/nftables.conf will be generated
automatically when you set up the till client booting configuration,
later in these instructions. The default configuration file from the
nftables package is an empty placeholder.
After creating all these files, enable systemd-network and nftables, uninstall or deactivate the default network configuration package, and reboot:
root@till:~# systemctl enable systemd-networkd
[lots of output]
root@till:~# systemctl enable nftables
[a bit of output]
root@till:~# systemctl start systemd-networkd
root@till:~# apt-get --purge remove network-manager modemmanager ifupdown
root@till:~# reboot
When you log in again, you can check everything is ok by running
networkctl. For example, on a Raspberry with a VLAN configuration:
sde@till:~ $ networkctl
IDX LINK TYPE OPERATIONAL SETUP
1 lo loopback carrier unmanaged
2 eth0 ether routable configured
3 tills vlan carrier unmanaged
4 wlan0 wlan off unmanaged
4 links listed.
Put the following in /etc/apt/trusted.gpg.d/quicktill-repo.asc:
-----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-----
Put the following in /etc/apt/sources.list.d/quicktill.list:
deb http://quicktill.assorted.org.uk/software tills main
Check that apt-get update doesn't complain about keys, etc.
This user will own the postgresql database and its home directory will be the location of the till configuration file.
root@till:~# adduser till
Adding user `till' ...
Adding new group `till' (1001) ...
Adding new user `till' (1001) with group `till (1001)' ...
Creating home directory `/home/till' ...
Copying files from `/etc/skel' ...
New password:
Retype new password:
passwd: password updated successfully
Changing the user information for till
Enter the new value, or press ENTER for the default
Full Name []: Till user
Room Number []:
Work Phone []:
Home Phone []:
Other []:
Is the information correct? [Y/n]
Adding new user `till' to supplemental / extra groups `users' ...
Adding user `till' to group `users' ...
If the till home directory /home/till/ doesn't have global read
permissions, add them using chmod 755 /home/till. This is needed for
the web server that we install later to be able to serve the till
configuration from /home/till/configweb/ to the clients.
As the till user, create /home/till/.local/bin/ which we will use later.
Run apt-get --purge install ntpsec. If systemd-timesyncd was
installed, it will be removed.
The default configuration of ntpsec should work fine — it will keep local system time synchronised with the network, and will also provide time service to the till clients.
To check it is working, run ntpq -c sysinfo and check the output
looks sensible.
Run apt-get install postgresql.
The default postgresql installation doesn't wait for the network to be
fully configured before starting postgresql. If you are going to
specify a particular network interface for postgresql to listen on in
its configuration file (instead of *), you must add the following to
/etc/systemd/system/postgresql@.service.d/override.conf (which you
can do with systemctl edit postgresql@.service if you find that
easier):
[Unit]
Wants=network-online.target
After=network-online.target
Edit /etc/postgresql/15/main/postgresql.conf (or possibily a
different number, depending on the version of postgresql
installed). Change the listen_addresses setting to * if you are
going to access the database over the network (eg. if the till web
interface is hosted on a different system), or to
localhost,172.31.172.1 (or whichever client network you picked
earlier) otherwise. Make sure the listen_addresses configuration
line isn't commented out!
Edit /etc/postgresql/15/main/pg_hba.conf and add a line similar to
the following at the end; substitute the database name you will be
using in your installation for "dbname":
host dbname all 172.31.172.0/24 trust
If you will be accessing the database over the network, add suitable
pg_hba.conf lines to permit that access as well.
Now restart postgresql using systemctl restart postgresql.service.
As root, run the following:
root@till:~# su - postgres
postgres@till:~$ createuser -d -e till
When logged in as till you should now be able to create and drop
databases.
The till software package is currently quicktill24; by the time you
read this there may be a later version. Install it.
You should probably also install apgdiff, which is required for the
"checkdb" till command.
Decide on a name for your till database and configuration
(eg. haymakers or emf).
Create ~/.config/ if it does not already exist, and put the
following in ~/.config/quicktill.toml, substituting your name for
mysite:
# quicktill configuration file
# This file is read from $XDG_CONFIG_DIRS/quicktill.toml (See
# https://specifications.freedesktop.org/basedir-spec/latest/ for how
# to interpret this location on your system; in practice, for most
# installations this will be $HOME/.config/quicktill.toml)
# This file is read at startup, before the command-line arguments are
# parsed. Some entries in this file are used as defaults for these
# arguments.
## Every module in this list will be imported
imports = [
# "quicktill.xero",
]
## Defaults for command-line arguments in client mode
[client-defaults]
## URL of site configuration file
configurl = "file:///home/till/configweb/mysite.py"
## Name of logging configuration file - OR - name of logging output file
## (You can't specify both)
# logconfig = "logconfig.toml"
# logfile = "till.log"
## Till type to use from site configuration file
configname = "default"
## Terminal name to store for transaction lines and payments created by
## this till instance
terminalname = "default"
## User ID to use when no other user information is available
# user = 1
## Named database connection details. These can be referred to from
## the site configuration file (as the "database" setting) or from the
## command-line "--database" or "-d" argument (command-line default
## set as "database" in the client and server configuration sections)
## You can supply a sqlalchemy engine URL as sqlalchemy_url, or
## specify keys dbname, user, password, host, port
[database]
[database.mysite]
dbname = "mysite"
If you will be using the Xero integration
then uncomment quicktill.xero from the imports list in the
configuration file you just created.
Create /home/till/configweb/.
Create the site configuration file in /home/till/configweb/mysite.py
(substituting name as appropriate), either from one of the examples in
/usr/share/doc/quicktill24/examples/ or from an existing
installation. Ensure the database setting in this configuration file
is simply the name of the database section you created in the local
till configuration file.
Create the till database by running createdb mysite. Populate it
with runtill syncdb, or restore a dump from a previous installation.
Check that the till is working locally and can access the database by
running runtill listusers.
aptly is used to manage a local repository of packages for the till
clients: the till boot images don't include the till software, so they
download it from the server on boot and then again at regular
intervals to pick up any updates. Install it with apt-get install aptly, and configure it while logged in as the till user.
Import the key for the quicktill repository (the same one shown above)
using the command gpg --no-default-keyring --keyring trustedkeys.gpg --import with the key as stdin.
Create the aptly mirror:
aptly mirror create \
-filter='!Name (~ till-boot-.*)' \
upstream-tills http://quicktill.assorted.org.uk/software tills main
Create a local repository to hold the packages being loaded by the till clients:
aptly repo create tills
Publish the repository:
aptly publish repo \
-distribution=tills \
-architectures=amd64,arm64 \
-skip-signing \
tills
Create an executable file /home/till/.local/bin/update-netboot.sh
with the following contents (edit the quicktill package version as
required):
#!/bin/bash
aptly mirror update upstream-tills
aptly repo import upstream-tills tills quicktill24
aptly publish update --skip-signing tills
Now whenever you run this script, the local repository will be updated with the latest versions of the packages you specified.
aptly doesn't delete package files by default when they are
superceded. You can do this using aptly db cleanup.
Install nginx with apt-get install nginx.
Create /etc/nginx/sites-available/tillweb with the following contents:
# Nginx configuration file for tillweb
# Put in /etc/nginx/sites-available and make a symlink to it in
# /etc/nginx/sites-enabled.
# This assumes that the till configuration files to be served up are
# in /home/till/configweb
# No local Django service is installed
server {
listen 80 default_server;
listen [::]:80 default_server;
server_name localhost;
location /till-boot {
alias /var/lib/tftpboot;
}
location /software {
alias /home/till/.aptly/public;
}
location / {
root /home/till/configweb;
}
}
Delete the symlink /etc/nginx/sites-enabled/default and create a
symlink from /etc/nginx/sites-enabled/tillweb to
/etc/nginx/sites-available/tillweb.
Reload the nginx configuration using systemctl reload nginx
Install using apt-get install bind9.
Edit /etc/bind/named.conf.options; add two acl entries at the top,
and then in the options section add an allow-recursion line:
acl tills { 172.31.172.0/24; };
acl local { 127.0.0.1; ::1; };
[...]
options {
[...]
allow-recursion { tills; local; };
};
Load the new configuration using rndc reload.
Install till-boot using apt-get install till-boot-pc-amd64 till-boot-rpi-arm64 — this should install the
current boot images and all the additional packages needed to serve
them.
Edit /etc/exports and add the following line to serve the till boot
images:
/usr/share/till-boot *(ro,no_subtree_check,all_squash)
Run exportfs -a to activate this configuration.
Create a directory /var/lib/tftpboot/ and edit
/etc/default/tftpd-hpa to set TFTP_DIRECTORY=/var/lib/tftpboot.
Create /etc/kea/ if it does not already exist.
Create /etc/till-boot/config.toml from the example in
/usr/share/doc/till-boot-config/. Edit as required, following the
comments in the file. The example configuration includes a network
section using 172.31.172.0/24 for the till client network; if you
picked a different RFC1918 address space then change this in the
configuration before continuing.
Run till-boot-config; this will create files in /var/lib/tftpboot/
to support all your configured till clients. It will also create
/etc/systemd/network/10-tills.network, /etc/nftables.conf and
/etc/kea/kea-dhcp4.conf.
If the kea-dhcp4-server package is not installed, install it
now. Choose not to use the /etc/kea/kea-dhcp4.conf file from the
package and keep the file we just generated installed.
Run networkctl reload to pick up changes to 10-tills.network,
systemctl reload nftables to pick up changes to
/etc/nftables.conf, and systemctl restart kea-dhcp4-server to pick
up changes to /etc/kea/kea-dhcp4.conf.
It should now be possible to boot the till clients over the network.