diff --git a/docs/02-docker.md b/docs/02-docker.md index 6003a1f0..84facba4 100644 --- a/docs/02-docker.md +++ b/docs/02-docker.md @@ -29,9 +29,9 @@ docker run \ ## General notes -⚠ By default, configuration and scanned images are stored within the container -and will be lost if you recreate it. If you want to map your scanned images then -see mapping section below +:warning: By default, configuration and scanned images are stored within the +container and will be lost if you recreate it. If you want to map your scanned +images then see mapping section below ✅ The docker image supports arm as well as amd64. @@ -40,8 +40,95 @@ see mapping section below Docker is great for certain tasks. But it's less ideal for situations where the container needs to access the host hardware. The simple solution is to run with `--privileged` but that gives your container full root access to the host which -means you're putting a lot of trust in the container. It's better not to do -this, but it can be painful to avoid. The best solution in my view is to use [SANE over Network](./03-sane.md#defining-network-scanners). +means you're putting a lot of trust in the container and it's often still not +sufficient for a working system. It's better not to do this, but it can be +painful to avoid. The cleanest solution is to use +[SANE over Network](./03-sane.md#defining-network-scanners). + +## Using SANE over Network + +The best overall implementation with Docker if you can manage it is to +[share the scanner over the network](./03-sane.md#configuring-the-server) on the +host (where the scanner is connected) and then update `net.conf` in the +container; either using a volume map or setting the `SANED_NET_HOSTS` +[environment variable](#environment-variables) on the docker container. + +[This](https://github.com/sbs20/scanservjs/issues/129#issuecomment-800226184) +user uses docker compose instead. See examples below. + +## Configuring SANE + +Sometimes you will need to configure SANE within the container. The best way to +achieve this is just volume mapping. + +Example to [configure `airscan.conf`](https://github.com/sbs20/scanservjs/issues/628): + +```sh +# Create your airscan config +cat > ./airscan.host.conf << EOF +[devices] +HP = http://192.168.1.150/eSCL, eSCL + +[options] +discovery = disable +EOF + +# Now map it +docker run -d \ + --publish 8080:8080 \ + --volume ./airscan.host.conf:/etc/sane.d/airscan.conf \ + --restart unless-stopped \ + --name scanservjs-container \ + --privileged \ + sbs20/scanservjs:latest +``` + +Example to [configure `pixma.conf`](https://github.com/sbs20/scanservjs/issues/594): + +```sh +# Create your pixma config +echo "bjnp://192.168.1.5" > ./pixma.host.conf + +# Now map it +docker run -d \ + --publish 8080:8080 \ + --volume ./pixma.host.conf:/etc/sane.d/pixma.conf \ + --restart unless-stopped \ + --name scanservjs-container \ + --privileged \ + sbs20/scanservjs:latest +``` + +## Environment variables + +There are some shortcuts available to volume mapping above by using environment +variables: + +* `SANED_NET_HOSTS`: If you want to use a + [SaneOverNetwork](https://wiki.debian.org/SaneOverNetwork#Server_Configuration) + scanner then to perform the equivalent of adding hosts to + `/etc/sane.d/net.conf` specify a list of ip addresses separated by semicolons + in the `SANED_NET_HOSTS` environment variable. +* `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). +* `PIXMA_HOSTS`: If you want to use a PIXMA scanner which uses the bjnp protocol + then to perform the equivalent of adding hosts to `/etc/sane.d/pixma.conf` + specify a list of ip addresses separated by semicolons in the `PIXMA_HOSTS` + environment variable. +* `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` + +## Mapping volumes + +To access data from outside the docker container, there are two volumes you may +wish to map: + +* The scanned images: use + `--volume /local/path/scans:/var/lib/scanservjs/output` +* Configuration overrides: use `--volume /local/path/cfg:/etc/scanservjs` ## Host attached scanner @@ -201,25 +288,6 @@ RUN apt install -yq "$APP_DIR/brscan4-0.4.10-1.amd64.deb" \ Note: The addition of more backends to the docker container is not planned since it would mostly add cruft for most users who don't need it. -## Using SANE over Network - -The best overall implementation with Docker if you can manage it is to -[share the host scanner over the network](./03-sane.md#configuring-the-server) -on the host (where the scanner is connected) and then set the `SANED_NET_HOSTS` -[environment variable](#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 - -To access data from outside the docker container, there are two volumes you may -wish to map: - -* The scanned images: use - `--volume /local/path/scans:/var/lib/scanservjs/output` -* Configuration overrides: use `--volume /local/path/cfg:/etc/scanservjs` - ## User and group mapping When mapping volumes, special attention must be paid to users and file systems @@ -246,70 +314,6 @@ Your alternatives are: 3. as a last resort, changing the host volume permissions e.g. `chmod 777 local-volume` -## Configuring SANE - -Sometimes you will need to configure SANE within the container. The best way to -achieve this is just volume mapping. - -Example to [configure `airscan.conf`](https://github.com/sbs20/scanservjs/issues/628): - -```sh -# Create your airscan config -cat > ./airscan.host.conf << EOF -[devices] -HP = http://192.168.1.150/eSCL, eSCL - -[options] -discovery = disable -EOF - -# Now map it -docker run -d \ - --publish 8080:8080 \ - --volume ./airscan.host.conf:/etc/sane.d/airscan.conf \ - --restart unless-stopped \ - --name scanservjs-container \ - --privileged sbs20/scanservjs:latest -``` - -Example to [configure `pixma.conf`](https://github.com/sbs20/scanservjs/issues/594): - -```sh -# Create your pixma config -cat > ./pixma.host.conf << EOF -bjnp://192.168.1.5 -EOF - -# Now map it -docker run -d \ - --publish 8080:8080 \ - --volume ./pixma.host.conf:/etc/sane.d/pixma.conf \ - --restart unless-stopped \ - --name scanservjs-container \ - --privileged sbs20/scanservjs:latest -``` - -## Environment variables - -There are some shortcuts available to volume mapping above by using environment variables: - -* `SANED_NET_HOSTS`: If you want to use a - [SaneOverNetwork](https://wiki.debian.org/SaneOverNetwork#Server_Configuration) - scanner then to perform the equivalent of adding hosts to - `/etc/sane.d/net.conf` specify a list of ip addresses separated by semicolons - in the `SANED_NET_HOSTS` environment variable. -* `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). -* `PIXMA_HOSTS`: If you want to use a PIXMA scanner which uses the bjnp protocol - then to perform the equivalent of adding hosts to `/etc/sane.d/pixma.conf` - specify a list of ip addresses separated by semicolons in the `PIXMA_HOSTS` - environment variable. -* `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) diff --git a/docs/03-sane.md b/docs/03-sane.md index 7aac6201..41151033 100644 --- a/docs/03-sane.md +++ b/docs/03-sane.md @@ -49,7 +49,7 @@ All you need is to define the subnets to which you want to grant access in about subnets and CIDR notation. `/etc/sane.d/saned.conf` -```ini +```sh # This is equivalent to 192.168.0.0/255.255.255.0 192.168.0.0/24 @@ -64,9 +64,9 @@ Make your changes to the file and restart the saned socket. ```sh ## Local network -echo "192.168.0.0/24" >> /etc/sane.d/saned.conf +sudo 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 echo "172.17.0.0/16" >> /etc/sane.d/saned.conf sudo systemctl enable saned.socket sudo systemctl start saned.socket @@ -77,7 +77,7 @@ sudo systemctl start saned.socket Add the server host (let's assume it is `192.168.0.10`) to the client. ```sh -echo "192.168.0.10" >> /etc/sane.d/net.conf +sudo echo "192.168.0.10" >> /etc/sane.d/net.conf ``` Now if you run `scanimage -L` on the client you should see the scanner on the @@ -119,7 +119,7 @@ supporting newer eSCL and WSD devices. Once installed you should just find that it works with a simple `scanimage -L`. You can also specify a specific name for the device in `/etc/sane.d/airscan.conf` -```console +```ini [devices] "My scanner" = "http://10.0.111.4/eSCL" ``` @@ -144,6 +144,6 @@ subnet, the autodiscovery won't work. You have two options: You may also need to add the full device name to the devices list in the config e.g. ```javascript - //config.devices.push('net:${bridge}:${device}); - config.devices.push('net:10.0.100.171:airscan:e0:Canon TR8500 series-5); + //config.devices.push('net:${bridge}:${device}'); + config.devices.push('net:10.0.100.171:airscan:e0:Canon TR8500 series-5'); ``` diff --git a/docs/50-development.md b/docs/50-development.md index e7da6b54..2da6aef1 100644 --- a/docs/50-development.md +++ b/docs/50-development.md @@ -3,8 +3,12 @@ ## Summary * Development requires at least Node 16 in order to support the UI build. -* All code in `app-server` must run under Node 10 -* Any commit must pass `npm run lint && npm run test && npm run build` +* All code in `app-server` must be able to run under Node 10; no modern + features. +* Any commit must pass the following; + ```sh + npm run lint && npm run test && npm run build && ./makedeb.sh + ``` ## Getting started @@ -25,7 +29,9 @@ cd scanservjs && npm install . npm run dev ``` -`npm run dev` will simultanesouly run the server (see [package.json](../package.json) and [vite.config.js](../app-ui/vite.config.js)). +`npm run dev` will simultanesouly run the server (see +[package.json](../package.json) and +[vite.config.js](../app-ui/vite.config.js)). If you run into the following error, then you may need to increase your inotify limit: @@ -61,6 +67,32 @@ npm run lint && npm run test && npm run build && ./makedeb.sh npm run util:missing-translations ``` +## Packaging + +The installation is achieved with a debian binary package. The package is +created by `makedeb.sh`; doing so with a source package seemed too big a step. + +The installation structure is: + +``` +/etc/scanservjs/ -> config directory +/usr/lib/scanservjs/ -> code +/var/lib/scanservjs/ -> runtime data directory +``` + +The `makdeb.sh` packager: + +* Creates the directory structure +* Moves all build assets into the correct place +* Runs `npm clean-install` +* Creates symlinks so that the app can access config and runtime data +* Dynamically creates things like `control`, `preinst`, `postint`, `prerm`, + `postrm` and the systemd service file. + +The Docker build creates its own deb package which somewhat unifies the +installation process (and testing). Note that Docker containers do not typically +support systemd. + ## Docker Install docker