Skip to content

Commit

Permalink
Documentation update
Browse files Browse the repository at this point in the history 
Updates:

* Docker; prioritises SANE over Network and volume mapping for config
* Development: packaging notes
* SANE verious typos
  • Loading branch information
@sbs20
sbs20 committed Nov 20, 2023
1 parent fd0da29 commit 5d52f4f
Show file tree
Hide file tree
Showing 3 changed files with 134 additions and 98 deletions.
180 changes: 92 additions & 88 deletions docs/02-docker.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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.

Expand All @@ -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

Expand Down Expand Up @@ -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
Expand All @@ -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)
Expand Down
14 changes: 7 additions & 7 deletions docs/03-sane.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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

Expand All @@ -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
Expand All @@ -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
Expand Down Expand Up @@ -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"
```
Expand All @@ -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');
```
38 changes: 35 additions & 3 deletions docs/50-development.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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

Expand All @@ -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:
Expand Down Expand Up @@ -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
Expand Down

0 comments on commit 5d52f4f

Please sign in to comment.