README.md 4.04 KB
Newer Older
Benjamin Rokseth's avatar
Benjamin Rokseth committed
1
2
3
4
5
6
7
Kohaprinter
==

A Cups Backend and printer delegator for use in Koha Intra and other services attached.
Purpose is to generate a simple connection between browser and thermal printers connected
in local network, so that you can print any HTML slip or label to a printer in the network.

8
9
10
Requirements: Docker

Setup and Testing
Benjamin Rokseth's avatar
Benjamin Rokseth committed
11
12
==

13
You'd be best off with docker and docker-compose:
Benjamin Rokseth's avatar
Benjamin Rokseth committed
14

15
16
Configuration files should be placed in `config` and will be mounted in from host, so they can be edited
and migrated easily outside Docker.
Benjamin Rokseth's avatar
Benjamin Rokseth committed
17

18
19
20
21
22
23
24
25
26
27
28
29
    config/printers.conf : the printers and queues setup
    config/ppd/*.ppd     : the individual printer ppd containing printer settings
    config/kohaprinter_mapping.json  : the koha printer mapping to the network attached printers, client ip mapped against label and receipt printer

migrating to another environment is as easy as copying these over

Building and starting:

    docker-compose up -d


Adding a new printer
Benjamin Rokseth's avatar
Benjamin Rokseth committed
30
==
Benjamin Rokseth's avatar
Benjamin Rokseth committed
31

32
33
The Cups admin service is exposed on port :631 on localhost, so you can add/remove printers and manage queue there

34
35
36
From cli, to add a receipt printer:

    ./tools/add-kvitt-printer <printqueue> <ip> <location>
37
38
39
40
41
42
43

The components
==

## Athena document conversion service

A document conversion service that can take many inputs and convert on the fly. We use it for HTML -> PDF
Benjamin Rokseth's avatar
Benjamin Rokseth committed
44
45
46
47

```
docker run -p 8089:8080 --rm -d arachnysdocker/athenapdf-service
```
Benjamin Rokseth's avatar
Benjamin Rokseth committed
48
49
50
51
52
53
54
55

## 1. In Cups, a Raw Print Queue must be set up to point to backend.

Make sure the Device URI corresponds with the backend, (kohaprinter), as this is picked up automagically by Cups

e.g.

```
Benjamin Rokseth's avatar
Benjamin Rokseth committed
56
lpadmin -p KohaKvittPrinter -v kohaprinter:/ -m raw -E
Benjamin Rokseth's avatar
Benjamin Rokseth committed
57
58
59
```

This means any job sent to this Queue on this Cups server will be passed along to the `kohaprinter` backend
Benjamin Rokseth's avatar
Benjamin Rokseth committed
60
with the kohaprinter:/ Device URI. (in short, looking for the executable file /usr/lib/cups/backend/kohaprinter)
Benjamin Rokseth's avatar
Benjamin Rokseth committed
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79

If the Cups server was running on host, say, `cupsserver`, the queue would now be accessible as normal by Cups, e.g.

```
ipps://cupsserver/printers/KohaKvittPrinter
```

## 2. The Client Printer must be mapped to correct network printer


On cups server: (See the example mapping file for examples)


/usr/lib/cups/backend/kohaprinter_mapping.json:

```
{
 "cupsclient": {
    "name": "a koha staff client",
Benjamin Rokseth's avatar
Benjamin Rokseth committed
80
81
    "receipt": "lab-receipt-4",
    "label": "lab-label-5"
Benjamin Rokseth's avatar
Benjamin Rokseth committed
82
83
84
85
  }
}
```

Benjamin Rokseth's avatar
Benjamin Rokseth committed
86
87
88
89
90
91
## 3. Config

The Client Must either:

  * be configured with a local Raw printer with remote as Device URI
  * OR print directly to remote ipp uri
Benjamin Rokseth's avatar
Benjamin Rokseth committed
92
93
94
95
96
97

Setup a Raw Printer to the Queue created in #1

Eg. in linux:

```
Benjamin Rokseth's avatar
Benjamin Rokseth committed
98
lpadmin -p IppKohaKvitt -v ipp://cupsserver/printers/KohaKvittPrinter -m raw -E
Benjamin Rokseth's avatar
Benjamin Rokseth committed
99
100
101
102
103
```

Now you should be able to print any html to the receipt printer. Eg. in linux:

```
Benjamin Rokseth's avatar
Benjamin Rokseth committed
104
105
106
107
108
109
110
lp -d IppKohaKvitt -o document-format=text/html -o koha-printer-type=receipt -o koha-origin-ip=cupsclient test.html
```

or print directly to remote queue:

```
lp -d ipp://cupsserver/printers/KohaKvittPrinter -o document-format=text/html -o koha-printer-type=receipt -o koha-origin-ip=cupsclient test.html
Benjamin Rokseth's avatar
Benjamin Rokseth committed
111
112
113
114
115
```

Behind the scenes
==

116
117
118
119
120
121
122
123
124
125
Info on kohaprinter backend: golang

* compiled backend (kohaprinter) must be placed in /usr/lib/cups/backend/ on the cups server
* a json mapping file (see example) must be placed in same directory as backend and named kohaprinter_mapping.json
* a running athena pdf service must be found at localhost:8089
* print job needs two extra options passed for mapping to function: koha-printer-type and koha-origin-ip
* Cups is strict on permissions, so make sure backend is owned by root and chmod 0755
* also beware that backend is run by user `lp` so main log turns up in /tmp/kohaprinter.log and
  spool logs and output in /var/spool/cups/

Benjamin Rokseth's avatar
Benjamin Rokseth committed
126
127
128
129
130
What happens is that :

* html document is sent raw to the Remote Print Queue KohaKvittPrinter
* it is delegated to the kohaprinter backend which :
  * fetches originating IP and DeviceURI from request
Benjamin Rokseth's avatar
Benjamin Rokseth committed
131
  * POSTS the html document as file in multipart form to running HTML->PDF service athenapdf at localhost:8089
Benjamin Rokseth's avatar
Benjamin Rokseth committed
132
  * forwards generated PDF to Print Queue of Thermal Printer or Label Printer found in json mapping