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.

Requirements: Docker

Setup and Testing
==

You'd be best off with docker and docker-compose:

Configuration files should be placed in `config` and will be mounted in from host, so they can be edited
and migrated easily outside Docker.

    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
==

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

From cli, to add a receipt printer:

    ./tools/add-kvitt-printer <printqueue> <ip> <location>

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

```
docker run -p 8089:8080 --rm -d arachnysdocker/athenapdf-service
```

## 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.

```
lpadmin -p KohaKvittPrinter -v kohaprinter:/ -m raw -E
```

This means any job sent to this Queue on this Cups server will be passed along to the `kohaprinter` backend
with the kohaprinter:/ Device URI. (in short, looking for the executable file /usr/lib/cups/backend/kohaprinter)

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",
    "receipt": "lab-receipt-4",
    "label": "lab-label-5"
  }
}
```

## 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

Setup a Raw Printer to the Queue created in #1

Eg. in linux:

```
lpadmin -p IppKohaKvitt -v ipp://cupsserver/printers/KohaKvittPrinter -m raw -E
```

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

```
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
```

Behind the scenes
==

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/

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
  * POSTS the html document as file in multipart form to running HTML->PDF service athenapdf at localhost:8089
  * forwards generated PDF to Print Queue of Thermal Printer or Label Printer found in json mapping