Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 1 addition & 1 deletion docs/alternatives-comparison.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -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 |
Expand Down
23 changes: 19 additions & 4 deletions docs/contributing/code-contributions.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -63,26 +63,41 @@ 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=<output of: openssl rand -hex 32>
INIT_ADMIN_USERNAME=admin
INIT_ADMIN_PASSWORD=<a password for your local admin>
```

```bash
cd backend
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. 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
npm install
npm run dev
corepack enable
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
Expand Down
15 changes: 8 additions & 7 deletions docs/contributing/translations.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -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",
Expand All @@ -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/<language-code>/` (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.
6. Open a pull request on GitHub and remember to post the required CLA agreement comment!
1. Copy the English strings `frontend/src/locales/en.json` to `frontend/src/locales/<language-code>.json` (e.g. `it.json`).
Comment thread
coderabbitai[bot] marked this conversation as resolved.
Resolved
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.
Comment thread
coderabbitai[bot] marked this conversation as resolved.
Resolved
7. Open a pull request on GitHub and remember to post the required CLA agreement comment!
18 changes: 12 additions & 6 deletions docs/openinvento/externalAPI.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -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 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

Expand Down Expand Up @@ -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 accepts API keys from v1.5.0. In v1.4.1 and earlier, it needs a logged-in session.
:::

---

### 2. Inventory Entries
Expand All @@ -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.
Expand All @@ -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:

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

Expand Down Expand Up @@ -222,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
Expand Down Expand Up @@ -335,7 +341,7 @@ POST /api/codes/pdf/
"layout": "vertical"
}
```
*Returns `application/pdf` binary data.*
*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.

---

Expand Down
3 changes: 2 additions & 1 deletion docs/openinvento/health-check.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -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)"]
Comment thread
coderabbitai[bot] marked this conversation as resolved.
Resolved
interval: 30s
timeout: 10s
retries: 3
Expand Down
4 changes: 2 additions & 2 deletions docs/openinvento/scheduled-notifications.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -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 |
| :--- | :---: | :--- |
Expand Down
5 changes: 3 additions & 2 deletions docs/openinvento/user-management.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -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.

Expand Down
4 changes: 2 additions & 2 deletions docs/setup-installation/configuration.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -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=<output of openssl rand -hex 32>
```

---
Expand Down
6 changes: 4 additions & 2 deletions docs/setup-installation/docker.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -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=change-this-password
# Keep the single quotes: Compose would otherwise replace $... in the password with variables.
# Choose a password without single quotes.
INIT_ADMIN_PASSWORD='<set your own password before the first start>'

# Feature Flags
ENABLE_SIGNUP=false
Expand Down Expand Up @@ -119,7 +121,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='<set your own password before the first start>' \
-e CREATE_INIT_ADMIN=true \
-e ENABLE_SIGNUP=false \
-e ENABLE_UPDATE_CHECKER=true \
Expand Down
63 changes: 49 additions & 14 deletions docs/setup-installation/updating-and-backups.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -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`. 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 \
Expand Down Expand Up @@ -85,17 +85,51 @@ 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.

With Docker Compose:

```bash
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 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 .
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
```

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.

:::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
Expand All @@ -114,20 +148,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-data:/volume-data \
-v $(pwd):/backup \
alpine sh -c "rm -rf /volume-data/* && tar -xzvf /backup/openinvento-backup-YYYYMMDD.tar.gz -C /volume-data"
-v openinvento_openinvento-data:/volume-data \
-v "$(pwd)":/backup \
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).
Comment thread
coderabbitai[bot] marked this conversation as resolved.
Resolved

3. Restart the container:
3. Start OpenInvento again:
```bash
docker compose up -d
docker compose start # manual installation: docker start openinvento
```
Loading