Install and operate

The install is one server process: the JSON API, the components, the admin page and these pages. Its state (layouts, waves, reservations, scans) lives in a store: Redis for production, or memory for a trial.

Install#

The executable#

The download has one archive per platform (Linux x64 and arm64, macOS, Windows), each with a single executable that needs no Node.js or other runtime. Unpack it and start it:

tar -xzf slotting-1.0.0-linux-x64.tar.gz
cd slotting-1.0.0-linux-x64
REDIS_URL=redis://redis.internal:6379 ./slotting

It listens on http://127.0.0.1:10083 (set HOST and PORT to change that) and logs to standard output. Open http://127.0.0.1:10083/ for the admin page and /docs/ for these pages. Run it under your service manager (systemd, Windows service wrapper, launchd) so it restarts after a failure or a reboot. It writes nothing to disk.

On Linux the executable needs glibc 2.28 or later, libstdc++ and libatomic, which minimal installs and slim images often lack (the program then exits at once with "error while loading shared libraries: libatomic.so.1"). Install it first: sudo apt-get install -y libatomic1 on Debian and Ubuntu, sudo dnf install -y libatomic on RHEL and Amazon Linux. The archive's Dockerfile installs it.

Docker#

The Linux archives contain a Dockerfile that builds an image from the executable:

cd slotting-1.0.0-linux-x64
docker build -t slotting:1.0.0 .
docker run -d --name slotting -p 127.0.0.1:10083:10083 \
    -e REDIS_URL=redis://redis.internal:6379 \
    -e LICENSE_FILE=/run/secrets/slotting-license -v /etc/slotting/license.txt:/run/secrets/slotting-license:ro \
    -e SLOTTING_INSTANCE_ID=slotting-1 \
    slotting:1.0.0

In the image the server listens on 0.0.0.0:10083. Publish the port only on a private interface or network (above: 127.0.0.1 of the host), never on a public one. The container is stateless and works with --read-only. Set SLOTTING_INSTANCE_ID, because a container's hostname changes every time it is recreated (License).

Check the install#

curl -s http://127.0.0.1:10083/healthz     # {"status":"ok","store":"redis","storeOk":true}
curl -s http://127.0.0.1:10083/v1/info     # version, license, photo import

/healthz answers 503 with "status": "degraded" and "storeOk": false while Redis can't be reached; use it for your load balancer's and monitoring's health check. The Status page shows the same in a browser.

Configuration#

Everything is configured with environment variables. All are optional: without any, the install runs on 127.0.0.1:10083 with the memory store and the evaluation license.

Settings that can't work (an unknown SLOTTING_STORE, a malformed Redis URL, two Redis modes at once, an unreadable REDIS_TLS_CA_FILE or SLOTTING_LIGHTS_MQTT_CA_FILE, a webhook URL without a secret) stop the install at startup with a message. Passwords and keys never appear in the log or in any response.

Showcase and demo limits#

For a public demo or a shared evaluation install, a few settings cap what visitors can create. They are all off unless set, and a production install doesn't need them. A request beyond a cap answers 409 limit_reached, with the setting in details.limit and its value in details.max. A value that can't work stops the install at startup.

The caps are checked before the change is written, so two requests at the same moment can both pass a cap; they are meant for a demo, not as quotas. Use them with the memory store, which a restart resets, and with an evaluation license.

The store#

Memory (trial only)#

Without Redis settings the install keeps everything in memory and logs a warning at startup. Layouts, waves and scans are lost on every restart, and the state is not shared with other instances. Use it to evaluate, never in production.

Redis#

Set REDIS_URL (or REDIS_CLUSTER_NODES, or REDIS_SENTINELS with REDIS_SENTINEL_NAME). Any Redis 6.2 or newer works, including managed services (Amazon ElastiCache or MemoryDB, Azure Cache for Redis, Google Memorystore) and Redis-compatible servers such as Valkey. Use rediss:// URLs when the server has TLS; with a private CA, add REDIS_TLS_CA_FILE.

• Cluster mode works: all keys of one layout share a hash tag, so they live on one slot and every change to a layout is one atomic transaction.
• If Redis goes down, the API answers 503 store_unavailable with a Retry-After header, /healthz reports degraded, and the install reconnects by itself. Scan stations show "retry"; nothing is lost that was already confirmed.
• One install per prefix. Separate installs (test and production, two sites) can share one Redis with different REDIS_KEY_PREFIX values. Instances of the same install use the same prefix (next section).

Persistence and backups#

The plans and the scan state are operational data: if Redis loses them, the wall's contents are no longer known to the system. Configure Redis so it keeps them:

• Enable AOF persistence: appendonly yes with appendfsync everysec (at most about one second of scans can be lost on a crash). With webhooks this matters twice: the events not yet delivered (the outbox) live in Redis too, so a Redis that restarts without persistence also forgets the webhooks it still owed. On managed services, choose the option with persistence or durability (for example MemoryDB, or a Redis persistence setting on your cache), and replication with automatic failover.
• Never evict: set maxmemory-policy noeviction. An eviction policy (allkeys-lru and similar) would silently delete waves under memory pressure. Size the memory for your layouts and the waves kept for SLOTTING_WAVE_RETENTION_HOURS (check INFO memory after a few days of normal work).
• Backups: keep RDB snapshots (save settings, or BGSAVE from a scheduled job) and copy them off the server, as for any database. A restore brings back the layouts and the waves as they were at the snapshot; units put since then are not in it, so after a restore, close the waves that were running and start them again.
• Don't share the database with applications that call FLUSHDB, and don't edit the slotting: keys by hand. The webhook keys are slotting:outbox (layouts with undelivered events), slotting:{<layout>}:outbox (the events, in order), slotting:{<layout>}:outbox:lease and slotting:deadletters (the last 1000 events given up). Without SLOTTING_WEBHOOK_URLS no events are kept. With webhooks, a deleted layout's outbox stays until its events are delivered, and each layout keeps at most SLOTTING_OUTBOX_MAX_PER_LAYOUT (default 100 000) waiting events: over it the oldest are dropped with an error in the log and one dead letter (Outbox limit). Size Redis for that worst case if a receiver can be down for long, or lower the limit.

Running several instances#

For availability or load, run two or more instances against the same Redis with the same REDIS_KEY_PREFIX, behind your (private) load balancer. They share every layout and wave safely: each change to a layout takes a short lock in Redis and is written in one transaction, and each instance reloads a layout when another instance changed it. No sticky sessions are needed, and any instance can answer any scan.

• Give each instance its own SLOTTING_INSTANCE_ID (slotting-1, slotting-2), and stay within the number of installations in your license.
• Changes to one layout are serialized; scans on different layouts run in parallel. If many stations scan into the same layout at once and requests answer 503 store_busy, raise REDIS_LOCK_WAIT_MS a little; the scan clients retry a 503 anyway.
• Use the memory store with one instance only.

Network and security#

The API has no authentication, by design: anyone who can reach the port can create and delete layouts, close waves and scan. Run the install on a private network only:

• Let only your backend, the scan stations' devices and the people who manage the walls reach it (security groups, firewall rules, a private subnet or VPN). Never give it a public IP address or a public load balancer.
• If your network needs authentication or TLS, put a reverse proxy or API gateway in front of it (it speaks plain HTTP). The components send their requests to api-base, so point that at the proxy.
• Keep Redis private too, with a password (or ACL user) and TLS where your network requires it.

Because the API has no login, the install also protects itself against web pages that a warehouse PC happens to open:

• Cross-origin changes are refused. A POST, PUT, PATCH or DELETE under /api/ that carries an Origin header (browsers send one) answers 403 origin_not_allowed unless the origin is the install itself or is listed in SLOTTING_CORS_ORIGINS. Requests without Origin (your backend, curl, scripts) are not affected. Set SLOTTING_CORS_ORIGINS only for the origins that serve your station pages.
• JSON only. Request bodies must be Content-Type: application/json; anything else (including text/plain, which a page could send without asking) answers 415 unsupported_media_type.
• Host allowlist. With SLOTTING_ALLOWED_HOSTS set, the install answers only to those host names (421 host_not_allowed otherwise), so a hostile DNS name pointed at its address (DNS rebinding) gets nowhere. Set it in production.
• Behind a reverse proxy, forward the original Host header (nginx: proxy_set_header Host $host;) or set X-Forwarded-Host, so the install recognises requests from its own pages; list the proxy's public host name in SLOTTING_ALLOWED_HOSTS.

Logs#

The install logs JSON lines to standard output: one line at startup with the store and the license, one when the license status changes, warnings (memory store, Redis connection lost and restored, a light gateway or MQTT broker that can't be reached, a webhook delivery that failed and will be retried) and errors (a webhook event given up as a dead letter). It never logs license keys, Redis passwords, AI keys, the webhook secret, light tokens or MQTT passwords, or photos.