From 09ceedec05fd265858a3d6df801f131fa46c71e7 Mon Sep 17 00:00:00 2001 From: tioan Date: Sun, 1 Nov 2026 18:53:40 +0100 Subject: [PATCH 1/4] Fix setup, API and backup instructions found in the review of #11 Verified against v1.4.1 and main of openinvento: Python 3.12, pnpm, APP_URL for the Vite dev server, initial admin for local development, the translation file layout and language selector, field_values_input, the endpoints without API key support, a healthcheck without curl, UTC job times, the minimum_quantity field for low-stock alerts, placeholders for SECRET_KEY and the initial admin password, environment options when updating a manual installation, the Compose volume name, a consistent SQLite backup and keeping the SECRET_KEY with backups, and Homebox barcode scanning. --- docs/alternatives-comparison.mdx | 2 +- docs/contributing/code-contributions.mdx | 22 +++++++++++++++---- docs/contributing/translations.mdx | 11 +++++----- docs/openinvento/externalAPI.mdx | 16 +++++++++----- docs/openinvento/health-check.mdx | 3 ++- docs/openinvento/scheduled-notifications.mdx | 4 ++-- docs/openinvento/user-management.mdx | 5 +++-- docs/setup-installation/configuration.mdx | 4 ++-- docs/setup-installation/docker.mdx | 4 ++-- .../updating-and-backups.mdx | 22 ++++++++++++++----- 10 files changed, 63 insertions(+), 30 deletions(-) diff --git a/docs/alternatives-comparison.mdx b/docs/alternatives-comparison.mdx index efffab2..2e9a7f1 100644 --- a/docs/alternatives-comparison.mdx +++ b/docs/alternatives-comparison.mdx @@ -63,7 +63,7 @@ use the REST API for integrations, and create backups of your data. | Separate inventories / workspaces | Separate and shared inventories | Multiple inventories / collections | Multi-user stock system | | User management | ✅ | ✅ | ✅ | | QR code generation | ✅ | ✅ | Label and barcode workflows | -| QR / barcode scanning | ✅ | QR code lookup; No support for barcode scanning | Barcode scanning supported | +| QR / barcode scanning | ✅ | QR code lookup; product barcode scanning to fill in item details | Barcode scanning supported | | Support for external barcode scanners | ✅ | No | ✅ | | Item images | ✅ | ✅ | ✅ | | File attachments | ✅ | ✅ | Document and attachment capabilities vary by object/workflow | diff --git a/docs/contributing/code-contributions.mdx b/docs/contributing/code-contributions.mdx index 307c367..bf3bdaf 100644 --- a/docs/contributing/code-contributions.mdx +++ b/docs/contributing/code-contributions.mdx @@ -63,7 +63,16 @@ To ensure consistency and quality across the codebase, please adhere to these co ## Local Development Workflow ### Backend (Django & DRF) -The backend is located in `backend/` and requires Python 3.11+. +The backend is located in `backend/` and requires Python 3.12+. + +Create `backend/.env` for local development. `APP_URL` must be the origin of the Vite development server, because the frontend sends its requests from there; otherwise every request that changes data fails the CSRF origin check with `403`. The initial administrator lets you log in to the new database: + +```bash title="backend/.env" +APP_URL=http://localhost:5173 +SECRET_KEY= +INIT_ADMIN_USERNAME=admin +INIT_ADMIN_PASSWORD= +``` ```bash cd backend @@ -71,18 +80,23 @@ python -m venv .venv source .venv/bin/activate # On Windows: .venv\Scripts\Activate.ps1 pip install . python manage.py migrate +python manage.py create_initial_admin python manage.py runserver ``` +`create_initial_admin` only creates the administrator while the database has no users, as in the container. You are asked to set a new password at the first login. + ### Frontend (React & Vite) -The frontend is located in `frontend/`. +The frontend is located in `frontend/` and uses [pnpm](https://pnpm.io/) in the version pinned in `frontend/package.json` (`packageManager`). Recent npm versions refuse to run there, because `devEngines` requires pnpm. With Corepack, `corepack enable` installs the pinned version. ```bash cd frontend -npm install -npm run dev +pnpm install +pnpm dev ``` +The development server runs on `http://localhost:5173` and forwards `/api` and `/media` to the backend on `http://localhost:8000`. + --- ## Submitting a Pull Request diff --git a/docs/contributing/translations.mdx b/docs/contributing/translations.mdx index 7142728..8a18b8d 100644 --- a/docs/contributing/translations.mdx +++ b/docs/contributing/translations.mdx @@ -53,9 +53,10 @@ When adding or updating translations: To contribute a new language to OpenInvento: -1. Create a new locale folder under `frontend/src/locales//` (e.g. `de`, `fr`, `es`). -2. Copy the base English strings (`locales/en/`) into your new folder. -3. Translate the string values into your target language. -4. Register the new locale in the frontend i18n initialization file (`frontend/src/i18n.ts`). -5. Verify your translations locally by starting the frontend development server and selecting the new language from your profile settings. +1. Copy the English strings `frontend/src/locales/en.json` to `frontend/src/locales/.json` (e.g. `it.json`). +2. Translate the string values into your target language. Keep the keys and the `{{placeholders}}` unchanged. +3. Import the file and add it to `resources` in the frontend i18n initialization file (`frontend/src/i18n.ts`). +4. Add the language to the language selector in `frontend/src/components/settings/UserSettings.tsx`: a `SelectItem` with the language code, and its name in `languageName`. +5. Run `pnpm i18n:check` in `frontend/`. It checks every locale file against `en.json` for missing keys and placeholders. +6. Verify your translations locally by starting the frontend development server and selecting the new language from your profile settings. 6. Open a pull request on GitHub and remember to post the required CLA agreement comment! diff --git a/docs/openinvento/externalAPI.mdx b/docs/openinvento/externalAPI.mdx index 3fb7389..054405d 100644 --- a/docs/openinvento/externalAPI.mdx +++ b/docs/openinvento/externalAPI.mdx @@ -10,7 +10,7 @@ OpenInvento provides a comprehensive, RESTful API that enables you to automate i ## Authentication -All external API requests authenticate using an **API Key**. +External API requests authenticate using an **API Key**. API keys work for the endpoints on this page except the inventory CSV export and the PDF label sheet, which currently need a logged-in browser session. ### Generating an API Key @@ -85,6 +85,10 @@ GET /api/inventories/{inventory_uuid}/export/ ``` Returns a `ZIP` file containing CSV data for inventory entries. Separate area, shelf, box, and article exports are no longer provided. +:::note +This endpoint does not accept API keys yet; it needs a logged-in session. +::: + --- ### 2. Inventory Entries @@ -111,7 +115,9 @@ POST /api/entries/ "quantity": 3, "stock_tracking": true, "category": "8a7b6c5d-4e3f-2a1b-0c9d-8e7f6a5b4c3d", - "field_values": [] + "field_values_input": [ + {"field": "9d8c7b6a-5e4f-3a2b-1c0d-9e8f7a6b5c4d", "value": "RP5-8G-2026-X89"} + ] } ``` For a root area, use `"type": "area"` and omit `parent`. Allowed parent and child types are validated by the API. @@ -134,7 +140,7 @@ DELETE /api/entries/{entry_uuid}/ #### Article Field Values -Article responses include `field_values` and `category_fields`. +Article responses include `field_values` and `category_fields`. To set field values when creating or updating an article, send them as `field_values_input`; `field_values` is read-only and ignored in requests. `field_values` is returned as a list of objects: @@ -156,7 +162,7 @@ Article responses include `field_values` and `category_fields`. The `category_fields` response contains the field definitions applicable to the article: global fields (`category: null`) and, when the article has a category, fields assigned to that category. Supported `field_type` values are `text`, `number`, `boolean`, `date`, `barcode`, and `select`. `options` is a JSON list used for field options. -When submitting `field_values`, each item must include a string `field` UUID. Field IDs must belong to the same inventory and may not be duplicated in the submitted list. `notify_on_date` must be a boolean; only date fields may set it to `true`. The serializer updates submitted values but does not delete existing values omitted from the list. +When submitting `field_values_input` (a list of objects with `field`, `value` and optionally `notify_on_date`), each item must include a string `field` UUID. Field IDs must belong to the same inventory and may not be duplicated in the submitted list. `notify_on_date` must be a boolean; only date fields may set it to `true`. The serializer updates submitted values but does not delete existing values omitted from the list. #### Article Images and Attachments @@ -335,7 +341,7 @@ POST /api/codes/pdf/ "layout": "vertical" } ``` -*Returns `application/pdf` binary data.* +*Returns `application/pdf` binary data.* This endpoint does not accept API keys yet; it needs a logged-in session. --- diff --git a/docs/openinvento/health-check.mdx b/docs/openinvento/health-check.mdx index 6bc56fd..965b803 100644 --- a/docs/openinvento/health-check.mdx +++ b/docs/openinvento/health-check.mdx @@ -49,7 +49,8 @@ services: - .env # highlight-start healthcheck: - test: ["CMD-SHELL", "curl -f http://localhost/api/health || exit 1"] + # The image has no curl or wget; Python is always there. + test: ["CMD", "python", "-c", "import urllib.request; urllib.request.urlopen('http://localhost/api/health', timeout=5)"] interval: 30s timeout: 10s retries: 3 diff --git a/docs/openinvento/scheduled-notifications.mdx b/docs/openinvento/scheduled-notifications.mdx index 85d903e..d1e01df 100644 --- a/docs/openinvento/scheduled-notifications.mdx +++ b/docs/openinvento/scheduled-notifications.mdx @@ -4,11 +4,11 @@ sidebar_position: 9 # Scheduled Notifications -OpenInvento runs daily background jobs for date-field notifications, low-stock notifications, and update checks. Each job has its own configurable local time. All three jobs default to midnight (`00:00`). +OpenInvento runs daily background jobs for date-field notifications, low-stock notifications, and update checks. Each job has its own configurable time. All three jobs default to midnight UTC (`00:00`). ## Configure job times -Set the following environment variables using 24-hour `HH:MM` values: +Set the following environment variables using 24-hour `HH:MM` values in **UTC**. OpenInvento runs in UTC regardless of the host's or container's time zone, so convert your local time: for 08:00 in Berlin (UTC+1 in winter, UTC+2 in summer), set `07:00` or `06:00`. | Variable | Default | Job | | :--- | :---: | :--- | diff --git a/docs/openinvento/user-management.mdx b/docs/openinvento/user-management.mdx index fc75836..abccd04 100644 --- a/docs/openinvento/user-management.mdx +++ b/docs/openinvento/user-management.mdx @@ -53,8 +53,9 @@ When `ALLOW_INVENTORY_USER_INVITES` is enabled, registered users can view userna OpenInvento includes an in-app notification center that keeps you informed of critical events: ### Low-Stock Alerts -When an article has **Stock Tracking** enabled and its `quantity` drops to or below its `minimum_quantity` threshold: -- A low-stock notification is automatically generated for all members of the inventory. +When an article has **Stock Tracking** enabled, a value in its `minimum_quantity` field (a number field every inventory has by default), and its `quantity` is at or below that value: +- The daily low-stock job (see [Scheduled Notifications](./scheduled-notifications)) creates a notification for all members of the inventory and for instance administrators. Changing the quantity does not create the notification right away. +- Articles without a `minimum_quantity` value never get low-stock notifications. - Notifications display an alert badge in the navigation bar. - Once restocked, the notification can be dismissed or marked as read. diff --git a/docs/setup-installation/configuration.mdx b/docs/setup-installation/configuration.mdx index 564dac4..e2275e6 100644 --- a/docs/setup-installation/configuration.mdx +++ b/docs/setup-installation/configuration.mdx @@ -62,9 +62,9 @@ To generate a secure key: openssl rand -hex 32 ``` -Add the generated string to your `.env`: +Add the generated string to your `.env`, and never reuse a key from an example: ```bash -SECRET_KEY=b4a92f08c3d9a105f2e8790b435210984a92f08c3d9a105f2e8790b43521098 +SECRET_KEY= ``` --- diff --git a/docs/setup-installation/docker.mdx b/docs/setup-installation/docker.mdx index 9d0fba8..a554ba0 100644 --- a/docs/setup-installation/docker.mdx +++ b/docs/setup-installation/docker.mdx @@ -67,7 +67,7 @@ DATA_DIRECTORY=/data # Initial Administrator Credentials (used only on first startup) CREATE_INIT_ADMIN=true INIT_ADMIN_USERNAME=admin -INIT_ADMIN_PASSWORD=change-this-password +INIT_ADMIN_PASSWORD= # Feature Flags ENABLE_SIGNUP=false @@ -119,7 +119,7 @@ docker run -d \ -e DATA_DIRECTORY=/data \ -e APP_URL=http://localhost:8080 \ -e INIT_ADMIN_USERNAME=admin \ - -e INIT_ADMIN_PASSWORD=change-this-password \ + -e INIT_ADMIN_PASSWORD='' \ -e CREATE_INIT_ADMIN=true \ -e ENABLE_SIGNUP=false \ -e ENABLE_UPDATE_CHECKER=true \ diff --git a/docs/setup-installation/updating-and-backups.mdx b/docs/setup-installation/updating-and-backups.mdx index a00a485..9ff854c 100644 --- a/docs/setup-installation/updating-and-backups.mdx +++ b/docs/setup-installation/updating-and-backups.mdx @@ -50,7 +50,7 @@ When OpenInvento starts, it automatically applies any pending database migration docker pull ghcr.io/openinvento/openinvento:latest ``` -3. Re-run your `docker run` command with the same volume and environment options: +3. Run the container again with **the same** volume and environment options as before, for example the `-e` options from the [installation](./docker#method-2-manual-docker-run). Keep the same `SECRET_KEY`. If you keep the variables in a file, `--env-file .env` replaces the `-e` options: ```bash docker run -d \ --name openinvento \ @@ -85,17 +85,26 @@ The instance backup endpoint is restricted strictly to instance administrators b ### 2. Manual Volume Backup (Host-Level) -You can also back up the Docker volume directly from the host filesystem or via a temporary helper container: +You can also back up the Docker volume with a temporary helper container. Two things matter: + +- **The volume name.** Docker Compose prefixes volumes with the project name, which is the name of the directory with `docker-compose.yml`. With the [installation guide](./docker), the volume is called `openinvento_openinvento-data`; with the manual `docker run` installation, it is `openinvento-data`. Check with `docker volume ls`. A wrong name silently creates a new, empty volume, and the backup contains nothing. +- **Stop OpenInvento first.** The database is a SQLite file. Copying it while OpenInvento writes to it can produce a broken copy. ```bash +docker compose stop # or: docker stop openinvento docker run --rm \ - -v openinvento-data:/volume-data \ - -v $(pwd):/backup \ + -v openinvento_openinvento-data:/volume-data \ + -v "$(pwd)":/backup \ alpine tar -czvf /backup/openinvento-backup-$(date +%Y%m%d).tar.gz -C /volume-data . +docker compose start # or: docker start openinvento ``` This creates a timestamped compressed `.tar.gz` archive of your entire data volume in your current directory. +:::caution Keep the SECRET_KEY with your backups +The archive contains the data directory, but not your `.env`. Third-party provider API keys are encrypted with the `SECRET_KEY` (see [Secret Key](../security/secret-key)). Store your `.env` (or at least the `SECRET_KEY`) securely next to the backups, and use the same key when you restore, otherwise these API keys cannot be decrypted. +::: + --- ### 3. Inventory CSV Export @@ -122,10 +131,11 @@ To restore data from a previous volume backup archive: 2. Restore the files into the data volume: ```bash docker run --rm \ - -v openinvento-data:/volume-data \ - -v $(pwd):/backup \ + -v openinvento_openinvento-data:/volume-data \ + -v "$(pwd)":/backup \ alpine sh -c "rm -rf /volume-data/* && tar -xzvf /backup/openinvento-backup-YYYYMMDD.tar.gz -C /volume-data" ``` + Use the same volume name as for the backup (`openinvento-data` for the manual `docker run` installation). 3. Restart the container: ```bash From 7f0ac5e1424ca7656ac0caacb8887a95f12b67ad Mon Sep 17 00:00:00 2001 From: tioan Date: Sun, 1 Nov 2026 19:48:19 +0100 Subject: [PATCH 2/4] Address CodeRabbit review: Corepack, translation paths, API key scope, safer backup and restore --- docs/contributing/code-contributions.mdx | 3 +- docs/contributing/translations.mdx | 4 +-- docs/openinvento/externalAPI.mdx | 4 +-- docs/setup-installation/docker.mdx | 4 ++- .../updating-and-backups.mdx | 31 +++++++++++++------ 5 files changed, 31 insertions(+), 15 deletions(-) diff --git a/docs/contributing/code-contributions.mdx b/docs/contributing/code-contributions.mdx index bf3bdaf..4650b73 100644 --- a/docs/contributing/code-contributions.mdx +++ b/docs/contributing/code-contributions.mdx @@ -87,10 +87,11 @@ python manage.py runserver `create_initial_admin` only creates the administrator while the database has no users, as in the container. You are asked to set a new password at the first login. ### Frontend (React & Vite) -The frontend is located in `frontend/` and uses [pnpm](https://pnpm.io/) in the version pinned in `frontend/package.json` (`packageManager`). Recent npm versions refuse to run there, because `devEngines` requires pnpm. With Corepack, `corepack enable` installs the pinned version. +The frontend is located in `frontend/` and uses [pnpm](https://pnpm.io/) in the version pinned in `frontend/package.json` (`packageManager`). Recent npm versions refuse to run there, because `devEngines` requires pnpm. Corepack (shipped with Node.js) provides it: `corepack enable` installs the `pnpm` command, which then runs the pinned version. ```bash cd frontend +corepack enable pnpm install pnpm dev ``` diff --git a/docs/contributing/translations.mdx b/docs/contributing/translations.mdx index 8a18b8d..36d4b2c 100644 --- a/docs/contributing/translations.mdx +++ b/docs/contributing/translations.mdx @@ -32,7 +32,7 @@ With i18n Ally: When adding or updating translations: 1. **Use Nested JSON Keys**: Keep related strings grouped logically: - ```json title="locales/en/translation.json" + ```json title="frontend/src/locales/en.json" { "inventory": { "title": "Inventory Overview", @@ -59,4 +59,4 @@ To contribute a new language to OpenInvento: 4. Add the language to the language selector in `frontend/src/components/settings/UserSettings.tsx`: a `SelectItem` with the language code, and its name in `languageName`. 5. Run `pnpm i18n:check` in `frontend/`. It checks every locale file against `en.json` for missing keys and placeholders. 6. Verify your translations locally by starting the frontend development server and selecting the new language from your profile settings. -6. Open a pull request on GitHub and remember to post the required CLA agreement comment! +7. Open a pull request on GitHub and remember to post the required CLA agreement comment! diff --git a/docs/openinvento/externalAPI.mdx b/docs/openinvento/externalAPI.mdx index 054405d..868fc82 100644 --- a/docs/openinvento/externalAPI.mdx +++ b/docs/openinvento/externalAPI.mdx @@ -27,7 +27,7 @@ The full key is only displayed once upon creation. Store it securely in your sec ### Request Headers -Include the API key in the `Authorization` header of every HTTP request: +For the endpoints that accept API keys (all on this page except the CSV export and the PDF label sheet), include the key in the `Authorization` header of the request: ```http Authorization: Api-Key @@ -228,7 +228,7 @@ DELETE /api/article-categories/{category_uuid}/ ### 4. Category Fields -Category fields define custom fields that can be used by articles. Use the list endpoint to retrieve field UUIDs for the `field_values` property when creating or updating articles. +Category fields define custom fields that can be used by articles. Use the list endpoint to retrieve field UUIDs for the `field_values_input` property when creating or updating articles. #### List Category Fields ```http diff --git a/docs/setup-installation/docker.mdx b/docs/setup-installation/docker.mdx index a554ba0..105faf5 100644 --- a/docs/setup-installation/docker.mdx +++ b/docs/setup-installation/docker.mdx @@ -67,7 +67,9 @@ DATA_DIRECTORY=/data # Initial Administrator Credentials (used only on first startup) CREATE_INIT_ADMIN=true INIT_ADMIN_USERNAME=admin -INIT_ADMIN_PASSWORD= +# Keep the single quotes: Compose would otherwise replace $... in the password with variables. +# Choose a password without single quotes. +INIT_ADMIN_PASSWORD='' # Feature Flags ENABLE_SIGNUP=false diff --git a/docs/setup-installation/updating-and-backups.mdx b/docs/setup-installation/updating-and-backups.mdx index 9ff854c..36cadb0 100644 --- a/docs/setup-installation/updating-and-backups.mdx +++ b/docs/setup-installation/updating-and-backups.mdx @@ -90,15 +90,28 @@ You can also back up the Docker volume with a temporary helper container. Two th - **The volume name.** Docker Compose prefixes volumes with the project name, which is the name of the directory with `docker-compose.yml`. With the [installation guide](./docker), the volume is called `openinvento_openinvento-data`; with the manual `docker run` installation, it is `openinvento-data`. Check with `docker volume ls`. A wrong name silently creates a new, empty volume, and the backup contains nothing. - **Stop OpenInvento first.** The database is a SQLite file. Copying it while OpenInvento writes to it can produce a broken copy. +With Docker Compose: + ```bash -docker compose stop # or: docker stop openinvento -docker run --rm \ +docker compose stop && docker run --rm \ -v openinvento_openinvento-data:/volume-data \ -v "$(pwd)":/backup \ alpine tar -czvf /backup/openinvento-backup-$(date +%Y%m%d).tar.gz -C /volume-data . -docker compose start # or: docker start openinvento +docker compose start ``` +With the manual `docker run` installation: + +```bash +docker stop openinvento && docker run --rm \ + -v openinvento-data:/volume-data \ + -v "$(pwd)":/backup \ + alpine tar -czvf /backup/openinvento-backup-$(date +%Y%m%d).tar.gz -C /volume-data . +docker start openinvento +``` + +The `&&` makes sure nothing is archived if OpenInvento could not be stopped. The last command starts it again in any case. + This creates a timestamped compressed `.tar.gz` archive of your entire data volume in your current directory. :::caution Keep the SECRET_KEY with your backups @@ -123,21 +136,21 @@ This generates a ZIP archive containing structured CSV files for your areas, she To restore data from a previous volume backup archive: -1. Stop the running OpenInvento container: +1. Stop OpenInvento: ```bash - docker compose down + docker compose stop # manual installation: docker stop openinvento ``` -2. Restore the files into the data volume: +2. Restore the files into the data volume. The archive is checked first; only if it can be read completely are the current files deleted and replaced: ```bash docker run --rm \ -v openinvento_openinvento-data:/volume-data \ -v "$(pwd)":/backup \ - alpine sh -c "rm -rf /volume-data/* && tar -xzvf /backup/openinvento-backup-YYYYMMDD.tar.gz -C /volume-data" + alpine sh -c "tar -tzf /backup/openinvento-backup-YYYYMMDD.tar.gz > /dev/null && find /volume-data -mindepth 1 -delete && tar -xzvf /backup/openinvento-backup-YYYYMMDD.tar.gz -C /volume-data" ``` Use the same volume name as for the backup (`openinvento-data` for the manual `docker run` installation). -3. Restart the container: +3. Start OpenInvento again: ```bash - docker compose up -d + docker compose start # manual installation: docker start openinvento ``` From a3f15758e4ec362581581600e6583e1a31ad1afc Mon Sep 17 00:00:00 2001 From: tioan Date: Sun, 1 Nov 2026 20:20:59 +0100 Subject: [PATCH 3/4] Address CodeRabbit review: Node.js 24 and Corepack, failed backups, manual update options --- docs/contributing/code-contributions.mdx | 2 +- .../updating-and-backups.mdx | 38 ++++++++++++------- 2 files changed, 26 insertions(+), 14 deletions(-) diff --git a/docs/contributing/code-contributions.mdx b/docs/contributing/code-contributions.mdx index 4650b73..fcdae73 100644 --- a/docs/contributing/code-contributions.mdx +++ b/docs/contributing/code-contributions.mdx @@ -87,7 +87,7 @@ python manage.py runserver `create_initial_admin` only creates the administrator while the database has no users, as in the container. You are asked to set a new password at the first login. ### Frontend (React & Vite) -The frontend is located in `frontend/` and uses [pnpm](https://pnpm.io/) in the version pinned in `frontend/package.json` (`packageManager`). Recent npm versions refuse to run there, because `devEngines` requires pnpm. Corepack (shipped with Node.js) provides it: `corepack enable` installs the `pnpm` command, which then runs the pinned version. +The frontend is located in `frontend/` and uses [pnpm](https://pnpm.io/) in the version pinned in `frontend/package.json` (`packageManager`). Recent npm versions refuse to run there, because `devEngines` requires pnpm. Use Node.js 24, as the CI and the Docker image do. Corepack provides pnpm: `corepack enable` installs the `pnpm` command, which then runs the pinned version. Node.js 24 ships Corepack; from Node.js 25 on, install it first with `npm install --global corepack`. ```bash cd frontend diff --git a/docs/setup-installation/updating-and-backups.mdx b/docs/setup-installation/updating-and-backups.mdx index 36cadb0..f36f1ac 100644 --- a/docs/setup-installation/updating-and-backups.mdx +++ b/docs/setup-installation/updating-and-backups.mdx @@ -50,7 +50,7 @@ When OpenInvento starts, it automatically applies any pending database migration docker pull ghcr.io/openinvento/openinvento:latest ``` -3. Run the container again with **the same** volume and environment options as before, for example the `-e` options from the [installation](./docker#method-2-manual-docker-run). Keep the same `SECRET_KEY`. If you keep the variables in a file, `--env-file .env` replaces the `-e` options: +3. Run the container again with **the same** volume and environment options as before, for example the `-e` options from the [installation](./docker#method-2-manual-docker-run). Keep the same `SECRET_KEY`. The example uses `--env-file .env`; if you installed with `-e` options and have no `.env`, put those same `-e` options in its place: ```bash docker run -d \ --name openinvento \ @@ -93,24 +93,36 @@ You can also back up the Docker volume with a temporary helper container. Two th With Docker Compose: ```bash -docker compose stop && docker run --rm \ - -v openinvento_openinvento-data:/volume-data \ - -v "$(pwd)":/backup \ - alpine tar -czvf /backup/openinvento-backup-$(date +%Y%m%d).tar.gz -C /volume-data . -docker compose start +backup=openinvento-backup-$(date +%Y%m%d-%H%M%S).tar.gz +if docker compose stop; then + docker run --rm \ + -v openinvento_openinvento-data:/volume-data \ + -v "$(pwd)":/backup \ + alpine tar -czvf "/backup/$backup" -C /volume-data . \ + || { rm -f "$backup"; echo "Backup failed, partial archive removed." >&2; } + docker compose start +else + echo "OpenInvento could not be stopped, no backup taken." >&2 +fi ``` With the manual `docker run` installation: ```bash -docker stop openinvento && docker run --rm \ - -v openinvento-data:/volume-data \ - -v "$(pwd)":/backup \ - alpine tar -czvf /backup/openinvento-backup-$(date +%Y%m%d).tar.gz -C /volume-data . -docker start openinvento +backup=openinvento-backup-$(date +%Y%m%d-%H%M%S).tar.gz +if docker stop openinvento; then + docker run --rm \ + -v openinvento-data:/volume-data \ + -v "$(pwd)":/backup \ + alpine tar -czvf "/backup/$backup" -C /volume-data . \ + || { rm -f "$backup"; echo "Backup failed, partial archive removed." >&2; } + docker start openinvento +else + echo "OpenInvento could not be stopped, no backup taken." >&2 +fi ``` -The `&&` makes sure nothing is archived if OpenInvento could not be stopped. The last command starts it again in any case. +Nothing is archived if OpenInvento could not be stopped. If archiving fails, the partial archive is removed and the failure is reported; OpenInvento is started again either way. The time in the name keeps several backups of one day apart. This creates a timestamped compressed `.tar.gz` archive of your entire data volume in your current directory. @@ -146,7 +158,7 @@ To restore data from a previous volume backup archive: docker run --rm \ -v openinvento_openinvento-data:/volume-data \ -v "$(pwd)":/backup \ - alpine sh -c "tar -tzf /backup/openinvento-backup-YYYYMMDD.tar.gz > /dev/null && find /volume-data -mindepth 1 -delete && tar -xzvf /backup/openinvento-backup-YYYYMMDD.tar.gz -C /volume-data" + alpine sh -c "tar -tzf /backup/openinvento-backup-YYYYMMDD-HHMMSS.tar.gz > /dev/null && find /volume-data -mindepth 1 -delete && tar -xzvf /backup/openinvento-backup-YYYYMMDD-HHMMSS.tar.gz -C /volume-data" ``` Use the same volume name as for the backup (`openinvento-data` for the manual `docker run` installation). From 1fff1d00801dccc9d2cf99a1b255b167b99ab1cb Mon Sep 17 00:00:00 2001 From: tioan Date: Tue, 3 Nov 2026 19:32:14 +0100 Subject: [PATCH 4/4] API keys work for the CSV export and the PDF label sheet from v1.5.0 openinvento#97 added API key support to both endpoints, so the session-only notes now only apply to v1.4.1 and earlier. --- docs/openinvento/externalAPI.mdx | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/docs/openinvento/externalAPI.mdx b/docs/openinvento/externalAPI.mdx index 868fc82..2abaf2d 100644 --- a/docs/openinvento/externalAPI.mdx +++ b/docs/openinvento/externalAPI.mdx @@ -10,7 +10,7 @@ OpenInvento provides a comprehensive, RESTful API that enables you to automate i ## Authentication -External API requests authenticate using an **API Key**. API keys work for the endpoints on this page except the inventory CSV export and the PDF label sheet, which currently need a logged-in browser session. +External API requests authenticate using an **API Key**. API keys work for all endpoints on this page. In v1.4.1 and earlier, the inventory CSV export and the PDF label sheet need a logged-in browser session instead; they accept API keys from v1.5.0. ### Generating an API Key @@ -27,7 +27,7 @@ The full key is only displayed once upon creation. Store it securely in your sec ### Request Headers -For the endpoints that accept API keys (all on this page except the CSV export and the PDF label sheet), include the key in the `Authorization` header of the request: +Include the API key in the `Authorization` header of every HTTP request: ```http Authorization: Api-Key @@ -86,7 +86,7 @@ GET /api/inventories/{inventory_uuid}/export/ Returns a `ZIP` file containing CSV data for inventory entries. Separate area, shelf, box, and article exports are no longer provided. :::note -This endpoint does not accept API keys yet; it needs a logged-in session. +This endpoint accepts API keys from v1.5.0. In v1.4.1 and earlier, it needs a logged-in session. ::: --- @@ -341,7 +341,7 @@ POST /api/codes/pdf/ "layout": "vertical" } ``` -*Returns `application/pdf` binary data.* This endpoint does not accept API keys yet; it needs a logged-in session. +*Returns `application/pdf` binary data.* This endpoint accepts API keys from v1.5.0. In v1.4.1 and earlier, it needs a logged-in session. ---