Improve documentation #202

docs/docker.md

@@ -1,5 +1,9 @@
 # Running scanservjs under docker
 
+If you're already running Debian, Ubuntu or similar, and haven't used docker
+before then it's probably easier just to install directly. For what it's worth,
+that is my preferred installation method.
+
 ## Quickstart
 
 Get the image
@@ -38,8 +42,9 @@ you're putting a lot of trust in the container. In short, best not.
 
 Depending on your setup you have a number of options.
 
-* If your scanner is connected by USB to the host then you can map the device.
-  The best way to do this is to map the actual USB ports.
+* If your scanner is connected by USB to the host, and there are standard SANE
+  drivers, then you can map the device. The best way to do this is to map the
+  actual USB ports.
   * Run `sudo sane-find-scanner -q` and you will get a result like
     `found USB scanner (vendor=0x04a9 [Canon], product=0x220d [CanoScan], chip=LM9832/3) at libusb:001:003`.
   * Or run `lsusb` which gives you
@@ -69,10 +74,14 @@ Depending on your setup you have a number of options.
   network. Adding more backends to the docker container feels wrong and will add
   cruft for many users who don't need it.
 
-* The best fallback position for many cases is simply to
-  [share the host scanner over the network](https://github.com/sbs20/scanservjs/issues/129#issuecomment-800226184)
-  and referencing that within the guest. This means that the docker container is
-  just running the app.
+* The best fallback position for most cases is simply to
+  [share the host scanner over the network](https://github.com/sbs20/scanservjs/blob/master/docs/sane.md#configuring-the-server)
+  on the host (where the scanner is connected) and then set the
+  `SANED_NET_HOSTS`
+  [environment variable](https://github.com/sbs20/scanservjs/blob/master/docs/docker.md#environment-variables)
+  on the docker container.
+  [This](https://github.com/sbs20/scanservjs/issues/129#issuecomment-800226184)
+  user uses docker compose instead. See examples below.
 
 ## Mapping volumes
 
@@ -108,22 +117,28 @@ The solution in most cases is either to
 * `AIRSCAN_DEVICES`: If you want to specifically add `sane-airscan` devices to
   your `/etc/sane.d/airscan.conf` then use the `AIRSCAN_DEVICES` environment
   variable (semicolon delimited).
-* `DELIMITER`: if you need to inlcude semi-colons (`;`) in your environment
+* `DELIMITER`: if you need to include semi-colons (`;`) in your environment
   variables, this allows you to choose an alternative delimiter.
 * `DEVICES`: Force add devices use `DEVICES` (semicolon delimited)
 * `SCANIMAGE_LIST_IGNORE`: To force ignore `scanimage -L`
 
 ## Examples
 
+### Connect to the scanner over the network (recommended)
+```sh
+docker run -d -p 8080:8080 \
+  -e SANED_NET_HOSTS="10.0.100.30" \
+  --name scanservjs-container sbs20/scanservjs:latest
+```
+
 ### Mapped USB device with mapped volumes
 
 ```sh
-docker run -d \
-  -p 8080:8080 \
+docker run -d -p 8080:8080 \
   -v $HOME/scan-data:/app/data/output \
   -v $HOME/scan-cfg:/app/config \
   --device /dev/bus/usb/001/003:/dev/bus/usb/001/003 \
-  --name scanservjs-container scanservjs-image
+  --name scanservjs-container sbs20/scanservjs:latest
 ```
 
 ### Use airscan and a locally detected scanner
@@ -133,7 +148,7 @@ This should support most use cases
 ```sh
 docker run -d -p 8080:8080 \
   -v /var/run/dbus:/var/run/dbus \
-  --name scanservjs-container scanservjs-image
+  --name scanservjs-container sbs20/scanservjs:latest
 ```
 
 ### A bit of everything
@@ -150,7 +165,7 @@ docker run -d -p 8080:8080 \
   -e DEVICES="net:10.0.100.30:plustek:libusb:001:003;net:10.0.100.31:plustek:libusb:001:003;airscan:e0:Canon TR8500 series;airscan:e1:EPSON Cool Series" \
   -e OCR_LANG="fra" \
   -v /var/run/dbus:/var/run/dbus \
-  --name scanservjs-container --privileged scanservjs-image
+  --name scanservjs-container --privileged sbs20/scanservjs:latest
 ```
 
 ## Staging builds

docs/sane.md

@@ -11,13 +11,14 @@ Just use your package manager.
 
 Either try:
 
-```
+```sh
 $ scanimage -L
 device `net:localhost:plustek:libusb:001:004' is a Canon CanoScan N1240U/LiDE30 flatbed scanner
 ```
 
 or
-```
+
+```sh
 $ sane-find-scanner -q
 found USB scanner (vendor=0x04a9 [Canon], product=0x220d [CanoScan]) at libusb:003:005
 ```
@@ -37,41 +38,47 @@ underlying problem is. In order of likelihood:
 
 ## Defining network scanners
 
-From the scanimage manpage:
+### Configuring the server
 
-> The -L or --list-devices option requests a (partial) list of devices that are
-> available. The list is not complete since some devices may be available, but
-> are not listed in any of the configuration files (which are typically stored
-> in directory /etc/sane.d). This is particularly the case when accessing
-> scanners through the network. If a device is not listed in a configuration
-> file, the only way to access it is by its full device name. You may need to
-> consult your system administrator to find out the names of such devices.
+Assume the host (the device the scanner is connected to) has an IP of
+`192.168.0.10`
 
-Find the name of the scanner on the remote server by running `scanimage -L` (on
-the remote server) e.g:
-
-```
-device `airscan:e0:Canon TR8500 series' is a eSCL Canon TR8500 series eSCL network scanner
+```sh
+# Allow access from the following networks
+## Local network
+echo "192.168.0.0/24" >> /etc/sane.d/saned.conf
+## Default docker network
+echo "172.17.0.0/16" >> /etc/sane.d/saned.conf
+sudo systemctl enable saned.socket
+sudo systemctl start saned.socket
 ```
 
-Then on the client, prefix it with `net:<ip-address>:` The result is the device
-to use with scanimage. Using the value above we get:
+### Configuring the client
 
+Add the host (`192.168.0.10`) to the client.
+
+```sh
+echo "192.168.0.10" >> /etc/sane.d/net.conf
 ```
-net:192.168.0.10:airscan:e0:Canon TR8500 series
-```
+
+Now if you run `scanimage -L` on the client you should see the scanner on the
+host (prefixed with `net:192.168.0.10:`)
 
 For more information on configuring the server and client see
 [SaneOverNetwork](https://wiki.debian.org/SaneOverNetwork#Server_Configuration).
 
-### TL;DR; configuring server:
+It's worth noting that network scanners do not always show up on the client. In
+such cases you will need to get the device name from the host, prefix it with
+`net:$ip:` and use the `-d` switch. From the scanimage manpage:
+
+> The -L or --list-devices option requests a (partial) list of devices that are
+> available. The list is not complete since some devices may be available, but
+> are not listed in any of the configuration files (which are typically stored
+> in directory /etc/sane.d). This is particularly the case when accessing
+> scanners through the network. If a device is not listed in a configuration
+> file, the only way to access it is by its full device name. You may need to
+> consult your system administrator to find out the names of such devices.
 
-```console
-# Allow access from network
-echo "192.168.0.1/24" >> /etc/sane.d/saned.conf
-sudo systemctl enable saned.socket
-sudo systemctl start saned.socket
-```
 
 ## SANE Airscan