From a7099d1a1a0d67a7d083d80095ffe457fb8fde5d Mon Sep 17 00:00:00 2001 From: tioan Date: Sun, 15 Nov 2026 09:28:44 +0100 Subject: [PATCH] Document links in QR codes and SCAN_BASE_URL --- docs/openinvento/barcodes-and-labels.mdx | 27 ++++++++++++++++-- docs/setup-installation/configuration.mdx | 34 +++++++++++++++++++++++ 2 files changed, 59 insertions(+), 2 deletions(-) diff --git a/docs/openinvento/barcodes-and-labels.mdx b/docs/openinvento/barcodes-and-labels.mdx index 4b1ce68..dcc6d52 100644 --- a/docs/openinvento/barcodes-and-labels.mdx +++ b/docs/openinvento/barcodes-and-labels.mdx @@ -10,7 +10,7 @@ Physical inventory is only as good as your ability to identify and locate items ## Unique System Identifiers -Every component in OpenInvento—including **Areas**, **Shelves**, **Boxes**, and **Articles**—is automatically assigned a unique alphanumeric **identifier** (e.g. `X7k9P2mQ1a`). +Every component in OpenInvento—including **Areas**, **Shelves**, **Boxes**, and **Articles**—is automatically assigned a unique alphanumeric **identifier** (e.g. `7GQ2MX4`). New identifiers use uppercase letters and digits only, without the easily confused `I`, `L`, `O` and `U`; entries created with older versions may still have mixed-case identifiers. These identifiers are: - Compact and optimized for fast barcode rendering and camera scanning. @@ -33,6 +33,9 @@ OpenInvento allows you to export ready-to-print PDF label sheets tailored for st - **Sheet Layout**: - `Vertical`: 4 columns × 2 rows (8 labels per page). - `Horizontal`: 2 columns × 4 rows (8 labels per page). + - **Error Correction** (QR codes only): + - `Medium` (recommended): still readable when part of the code is scratched or dirty. + - `Low`: a smaller code, but less tolerant of damage. 4. Click **Generate PDF** to download the label sheet. ### Printed Label @@ -40,7 +43,25 @@ OpenInvento allows you to export ready-to-print PDF label sheets tailored for st Each printed cell includes: 1. **Item Title**: Bold item name (up to 32 characters). 2. **Code**: Centered high-resolution vector QR code or Code128 barcode. -3. **Reference Footer**: Object type and identifier (e.g., `article: X7k9P2mQ1a` or `box: K4b1L9vA0e`). +3. **Reference Footer**: Object type and identifier (e.g., `article: 7GQ2MX4` or `box: K4B1L9V`). + +### What a QR Code Contains + +A QR code contains a link to its entry, so any phone camera app can open it, not only the scanner in OpenInvento: + +```text +https://inventory.example.com/i/{inventory identifier}/{identifier} +``` + +- **Smaller codes:** if both identifiers only use uppercase letters and digits, the whole link is written in uppercase, like `HTTPS://INVENTORY.EXAMPLE.COM/I/K7M2Q/7GQ2MX4`. QR codes store uppercase text much more compactly, so the code gets smaller or more robust. Entries with older mixed-case identifiers get the same link in lowercase. +- **Opening a link:** OpenInvento asks for a login first if needed, then opens the entry and switches to its inventory. A code that doesn't exist, or belongs to an inventory you're not a member of, shows "Code not found". +- **Only an identifier:** without `APP_URL`, the QR code holds just the identifier, as Code128 barcodes always do. Identifiers `.` and `..` also stay without a link, because such a link can't reach the entry. +- **Turning links off:** administrators can switch this off under **Settings** → **Admin settings (instance)** → **URLs in QR codes**. QR codes then hold only the identifier. +- **Before printing:** while links are on, the label options show which address the QR codes point to. + +:::caution Moving your instance +Printed links point to the address they were printed with. If your instance moves to another address, those labels stop opening their entries. To keep labels valid across moves, point QR codes at a short address of your own with [`SCAN_BASE_URL`](../setup-installation/configuration#links-in-qr-codes-scan_base_url), which redirects to your instance. +::: --- @@ -52,6 +73,8 @@ When you need to find an item or verify what is stored inside a box: 2. Scan the code using your mobile device's camera or a connected barcode scanner. 3. OpenInvento queries the `/api/codes/lookup/` endpoint and immediately opens the detailed view of the matched article, box, shelf, or area. +The scanner reads both the links in QR codes and plain identifiers, in uppercase as well as lowercase links. You can also scan a QR code with your phone's camera app outside OpenInvento: it opens the entry in the browser. + --- ## Custom Barcode Fields diff --git a/docs/setup-installation/configuration.mdx b/docs/setup-installation/configuration.mdx index 6f6b60a..1d960bf 100644 --- a/docs/setup-installation/configuration.mdx +++ b/docs/setup-installation/configuration.mdx @@ -16,6 +16,7 @@ Below is the complete reference table of all environment variables supported by | :--- | :---: | :---: | :--- | | `APP_URL` | **Recommended** | `None` | Primary public URL of your OpenInvento instance. Supports `https://domain.com`, `http://localhost:8080`, or bare hosts like `example.com:8080`. Bare hosts default to `http://`. | | `APP_URLS` | No | `None` | Comma-separated list of additional URLs or hostnames where the application can be accessed (same format as `APP_URL`). | +| `SCAN_BASE_URL` | No | `None` | Origin for the links in printed QR codes, for example a short domain that redirects to your instance. Falls back to `APP_URL`. Origin only: a path is an error at startup. See [Links in QR codes](#links-in-qr-codes-scan_base_url). Available after v1.5.0. | | `SECRET_KEY` | **Recommended** | Unsafe fallback | Secret key used for cryptographic signing, session verification, and CSRF tokens. Set a long, secure random value in production. | | `DATA_DIRECTORY` | No | `/data` | Path to the directory where the SQLite database, uploaded media files, and attachments are persisted. | | `INIT_ADMIN_USERNAME` | Required if admin auto-created | `None` | Username for the initial administrator user account. | @@ -56,6 +57,39 @@ OpenInvento uses `APP_URL` and `APP_URLS` to automatically configure two critica --- +## Links in QR codes (`SCAN_BASE_URL`) + +Printed QR codes contain a link to their entry, so any phone camera can open it (see [Barcodes & QR Labels](../openinvento/barcodes-and-labels#what-a-qr-code-contains)). By default the link starts with `APP_URL`. Labels outlive instances, though: if the instance later moves to another address, every printed label stops working. + +`SCAN_BASE_URL` puts another origin into the QR codes, for example a short domain of your own: + +```bash +APP_URL=https://inventory.example.com +SCAN_BASE_URL=https://short.example +``` + +A QR code then holds `https://short.example/i/…`, and only the server behind `short.example` needs to know where the instance is. It has to redirect every request to `APP_URL` **with the path unchanged**, for example with nginx: + +```nginx +server { + listen 443 ssl; + server_name short.example; + ssl_certificate /path/to/short.example.crt; + ssl_certificate_key /path/to/short.example.key; + return 302 https://inventory.example.com$request_uri; +} +``` + +The short domain needs its own TLS certificate, because the QR codes contain an `https://` link. + +If the instance moves, you only change this redirect instead of reprinting labels. A short domain also makes the QR codes smaller. + +- **Origin only:** like `APP_URL`, with or without `https://`, but a path, query or fragment is an error at startup, because it would end up on every label. +- **Not a login address:** OpenInvento is never opened under `SCAN_BASE_URL`, so it is not added to `ALLOWED_HOSTS` or the CSRF origins. Users always end up on `APP_URL`. +- **Optional:** without it, QR codes use `APP_URL` as before. + +--- + ## Security & Secrets (`SECRET_KEY`) The `SECRET_KEY` is used for cryptographic signing. If left unset, OpenInvento will fall back to an unsafe default, which is unsuitable for production environments.