Development

Summary

• Development requires at least Node 22 in order to support the build.
• All code in app-server must be able to run under Node 12; no modern features.
• Any commit must pass the following;

  # Run lint, test, build and deb
  npm run check
  

Getting started

# Install dependencies
sudo apt-get install curl imagemagick sane-utils tesseract-ocr

# Install nvm
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.5/install.sh | bash

# IMPORTANT: Restart your terminal or run:
# export NVM_DIR="$HOME/.nvm"
# [ -s "$NVM_DIR/nvm.sh" ] && \. "$NVM_DIR/nvm.sh"

# Enable PDF (required for execution and unit tests)
sudo sed -i 's/policy domain="coder" rights="none" pattern="PDF"/policy domain="coder" rights="read | write" pattern="PDF"'/ /etc/ImageMagick-7/policy.xml

# Clone the repo
git clone https://github.com/sbs20/scanservjs.git && cd scanservjs

# Clean install all packages
nvm install && npm clean-install . && npm run bootstrap

# Run (from the scanservjs directory)
npm run dev

npm run dev will simultanesouly run the server (see package.json and vite.config.js).

If you run into the following error, then you may need to increase your inotify limit:

[nodemon] Internal watch failed: ENOSPC: System limit for number of file watchers reached, watch '/.../scanservjs/packages/server/src'

To incease it temporarily:

sudo sysctl fs.inotify.max_user_watches=131072

To update it permanently will depend on your distribution - but this will work with Debian:

echo fs.inotify.max_user_watches=131072 | sudo tee -a /etc/sysctl.d/50-default.conf; sudo sysctl -p

Updating dependencies

If you find yourself needing to recreate dependencies then remove the package-lock(s) and run npm run util:install

Build

Before committing please verify and build

npm run check

Find missing translations

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

sudo apt install docker.io
sudo systemctl unmask docker
sudo systemctl start docker

# Hack to make docker accessible.
sudo chmod 666 /var/run/docker.sock

Useful commands

# Build
docker build --tag scanservjs-image .

# Build the core image
docker build --target scanservjs-core --tag scanservjs-image .

# Remove any existing containers
docker rm --force scanservjs-container 2> /dev/null

# Different run options
docker run --detach --publish 8080:8080 --name scanservjs-container --privileged scanservjs-image

Mount map configuration files

docker run --detach \
  --publish 8080:8080 \
  --volume `pwd`/var/:/app/config/ \
  --name scanservjs-container \
  --privileged \
  scanservjs-image

Using docker to build

You may wish to attempt building with a different version of node. There are various ways to achieve this but Docker works well.

# build.Dockerfile
FROM node:24-trixie-slim AS scanservjs-build
ENV APP_DIR=/app
WORKDIR "$APP_DIR"

COPY package*.json build.js "$APP_DIR/"
COPY app-server/package*.json "$APP_DIR/app-server/"
COPY app-ui/package*.json "$APP_DIR/app-ui/"

RUN npm clean-install . && npm run bootstrap

COPY --exclude="**/node_modules" app-server/ "$APP_DIR/app-server/"
COPY --exclude="**/node_modules" app-ui/ "$APP_DIR/app-ui/"

RUN npm run build

COPY makedeb.sh "$APP_DIR/"
RUN ./makedeb.sh

Run the dockerfile:

docker build --target release-node18 --file build.Dockerfile --tag scanservjs-release-node18 .

If you want, you can copy the files out again:

id=$(docker create scanservjs-release-node18)
docker cp $id:/app/debian ./
docker rm -v $id

Pages

# Install and setup
sudo apt-get install -y ruby-full
gem install bundler --user-install

# Run
bundle config set --local path ~/.gem
bundle install
bundle exec jekyll serve --incremental