mirror/Part-DB.Part-DB-server
1
0
Fork 1
mirror of https://github.com/Part-DB/Part-DB-server.git synced 2025-06-20 17:15:51 +02:00
Code Issues Projects Releases Packages Wiki Activity Actions

Fixed some typos and grammar issues in documentation

Browse source
This commit is contained in:
Jan Böhmer 2024-02-23 13:56:23 +01:00
parent 20ee16e3c0
commit 5d68922f2e
11 changed files with 142 additions and 153 deletions
Download patch file Download diff file Expand all files Collapse all files

13
docs/api/authentication.md
View file

@ -11,15 +11,14 @@ To use API endpoints, the external application has to authenticate itself, so th
the data and which permissions
the application should have during the access. Authentication is always bound to a specific user, so the external
applications is acting on behalf of a
specific user. This user limits the permissions of the application, so that it can only access data, which the user is
specific user. This user limits the permissions of the application so that it can only access data, which the user is
allowed to access.
The only method currently available for authentication is to use API tokens:
## API tokens
An API token is a long alphanumeric string, which is bound to a specific user and can be used to authenticate as this
user, when accessing the API.
An API token is a long alphanumeric string, which is bound to a specific user and can be used to authenticate as this user when accessing the API.
The API token is passed via the `Authorization` HTTP header during the API request, like the
following: `Authorization: Bearer tcp_sdjfks....`.
@ -36,7 +35,7 @@ not access the API anymore with this token.
### Token permissions and scopes
API tokens are ultimately limited by the permissions of the user, which belongs to the token. That means that the token
can only access data, which the user is allowed to access, no matter the token permissions.
can only access data, that the user is allowed to access, no matter the token permissions.
But you can further limit the permissions of a token by choosing a specific scope for the token. The scope defines which
subset of permissions the token has, which can be less than the permissions of the user. For example, you can have a
@ -50,15 +49,15 @@ change anything in the database.
> Only use the full or admin scope, if you really need it, as they could potentially be used to do a lot of damage to
> your Part-DB instance.
Following token scopes are available:
The following token scopes are available:
* **Read-Only**: The token can only read non-sensitive data (like parts, but no users or groups) from the API and can
not change anything.
* **Edit**: The token can read and write non-sensitive data via the API. This includes creating, updating and deleting
data. This should be enough for most applications.
* **Admin**: The token can read and write all data via the API, including sensitive data like users and groups. This
should only be used for trusted applications, which need to access sensitive data, and perform administrative actions.
* **Full**: The token can do anything the user can do, including changing the users password and create new tokens. This
should only be used for trusted applications, which need to access sensitive data and perform administrative actions.
* **Full**: The token can do anything the user can do, including changing the user's password and creating new tokens. This
should only be used for highly trusted applications!!
Please note, that in early versions of the API, there might be no endpoints yet, to really perform the actions, which

51
docs/api/intro.md
View file

@ -29,15 +29,14 @@ features and how to use them.
The API is available under the `/api` path, but not reachable without proper permissions.
You have to give the users, which should be able to access the API the proper permissions (Miscellaneous -> API).
Please note that there are two relevant permissions, the first one allows users to access the `/api/` path at all and
showing the documentation,
and the second one allows them to create API tokens which is needed for authentication of external applications.
Please note that there are two relevant permissions, the first one allows users to access the `/api/` path at all and show the documentation,
and the second one allows them to create API tokens which are needed for the authentication of external applications.
## Authentication
To use API endpoints, the external application has to authenticate itself, so that Part-DB knows which user is accessing
the data and
which permissions the application should have. Basically this is done by creating an API token for a user and then
which permissions the application should have. Basically, this is done by creating an API token for a user and then
passing it on every request
with the `Authorization` header as bearer token, so you add a header `Authorization: Bearer <your token>`.
@ -46,11 +45,10 @@ See [Authentication chapter]({% link api/authentication.md %}) for more details.
## API endpoints
The API is split into different endpoints, which are reachable under the `/api/` path of your Part-DB instance (
so `https://your-part-db.local/api/`).
There are various endpoints for each entity type (like `part`, `manufacturer`, etc.), which allow you to read and write
data and some special endpoints like `search` or `statistics`.
e.g. `https://your-part-db.local/api/`).
There are various endpoints for each entity type (like `part`, `manufacturer`, etc.), which allow you to read and write data, and some special endpoints like `search` or `statistics`.
For example all API endpoints for managing categories are available under `/api/categories/`. Depending on the exact
For example, all API endpoints for managing categories are available under `/api/categories/`. Depending on the exact
path and the HTTP method used, you can read, create, update or delete categories.
For most entities, there are endpoints like this:
@ -66,29 +64,28 @@ For most entities, there are endpoints like this:
A full (interactive) list of endpoints can be displayed when visiting the `/api/` path in your browser, when you are
logged in with a user, which is allowed to access the API.
There is also a link to this page, on the user settings page in the API token section.
This documentation also list all available fields for each entity type and the allowed operations.
This documentation also lists all available fields for each entity type and the allowed operations.
## Formats
The API supports different formats for the request and response data, which you can control via the `Accept`
and `Content-Type` headers.
You should use [JSON-LD](https://json-ld.org/) as format, which is basically JSON with some additional metadata, which
allows
to describe the data in a more structured way and also allows to link between different entities. You can achieve this
allows you to describe the data in a more structured way and also allows to link between different entities. You can achieve this
by setting `Accept: application/ld+json` header to the API requests.
To get plain JSON without any metadata or links, use the `Accept: application/json` header.
Without an `Accept` header (e.g. when you call the endpoint in a browser), the API will return an HTML page with the
documentation, so be sure to include the desired `Accept` header in your API requests.
If you can not control the `Accept` header, you can add an `.json` or `.jsonld` suffix to the URL to enforce a JSON or
If you can not control the `Accept` header, you can add a `.json` or `.jsonld` suffix to the URL to enforce a JSON or
JSON-LD response (e.g. `/api/parts.jsonld`).
## OpenAPI schema
Part-DB provides a [OpenAPI](https://swagger.io/specification/) (formally Swagger) schema for the API
under `/api/docs.json` (so `https://your-part-db.local/api/docs.json`).
This schema is a machine-readable description of the API, which can be imported in software to test the API or even
This schema is a machine-readable description of the API, which can be imported into software to test the API or even
automatically generate client libraries for the API.
API generators which can generate a client library for the API from the schema are available for many programming
@ -120,14 +117,10 @@ See [API Platform docs](https://api-platform.com/docs/core/pagination) for more
## Filtering results / Searching
When retrieving a list of entities, you can restrict the results by various filters. Almost all entities have a search
filter,
which allows you to only include entities, which (text) fields match the given search term: For example if you only want
to
get parts, with the Name "BC547", you can use `/api/parts.jsonld?name=BC547`. You can use `%` as wildcard for multiple
characters
in the search term (Be sure to properly encode the search term, if you use special characters). For example if you want
to get all parts,
whose name starts with "BC", you can use `/api/parts.jsonld?name=BC%25` (the `%25` is the url encoded version of `%`).
filter, which allows you to only include entities, which (text) fields match the given search term: For example, if you only want
to get parts, with the Name "BC547", you can use `/api/parts.jsonld?name=BC547`. You can use `%` as a wildcard for multiple
characters in the search term (Be sure to properly encode the search term, if you use special characters). For example, if you want
to get all parts, whose name starts with "BC", you can use `/api/parts.jsonld?name=BC%25` (the `%25` is the url encoded version of `%`).
There are other filters available for some entities, allowing you to search on other fields, or restricting the results
by numeric values or dates. See the endpoint documentation for the available filters.
@ -136,8 +129,8 @@ by numeric values or dates. See the endpoint documentation for the available fil
To get all parts with a certain category, manufacturer, etc. you can use the `category`, `manufacturer`, etc. query
parameters of the `/api/parts` endpoint.
They are so-called entity filters and accept a comma separated list of IDs of the entities you want to filter by.
For example if you want to get all parts with the category "Resistor" (Category ID 1) and "Capacitor" (Category ID 2),
They are so-called entity filters and accept a comma-separated list of IDs of the entities you want to filter by.
For example, if you want to get all parts with the category "Resistor" (Category ID 1) and "Capacitor" (Category ID 2),
you can use `/api/parts.jsonld?category=1,2`.
Suffix an id with `+` to suffix, to include all direct children categories of the given category. Use the `++` suffix to
@ -150,7 +143,7 @@ See the endpoint documentation for the available entity filters.
## Ordering results
When retrieving a list of entities, you can order the results by various fields using the `order` query parameter.
For example if you want to get all parts ordered by their name, you can use `/api/parts/?order[name]=asc`. You can use
For example, if you want to get all parts ordered by their name, you can use `/api/parts/?order[name]=asc`. You can use
this parameter multiple times to order by multiple fields.
See the endpoint documentation for the available fields to order by.
@ -161,12 +154,12 @@ Sometimes you only want to get a subset of the properties of an entity, for exam
part, but not all the other properties.
You can achieve this using the `properties[]` query parameter with the name of the field you want to get. You can use
this parameter multiple times to get multiple fields.
For example if you only want to get the name and the description of a part, you can
For example, if you only want to get the name and the description of a part, you can
use `/api/parts/123?properties[]=name&properties[]=description`.
It is also possible to use this filters on list endpoints (get collection), to only get a subset of the properties of
It is also possible to use these filters on list endpoints (get collection), to only get a subset of the properties of
all entities in the collection.
See [API Platform docs](https://api-platform.com/docs/core/filters/#property-filter) for more infos.
See [API Platform docs](https://api-platform.com/docs/core/filters/#property-filter) for more info.
## Change comment
@ -174,7 +167,7 @@ Similar to the changes using Part-DB web interface, you can add a change comment
which will be
visible in the log of the entity.
You can pass the text for this via the `_comment` query parameter (beware the proper encoding). For
You can pass the text for this via the `_comment` query parameter (beware of the proper encoding). For
example `/api/parts/123?_comment=This%20is%20a%20change%20comment`.
## Creating attachments and parameters
@ -182,7 +175,7 @@ example `/api/parts/123?_comment=This%20is%20a%20change%20comment`.
{: .warning }
> The way described below is more a workaround than a proper solution. This might break in future versions of Part-DB!
Currently it is not possible to create attachments or parameters via a `POST` operation on the entity endpoint.
Currently, it is not possible to create attachments or parameters via a `POST` operation on the entity endpoint.
The workaround for this is to send a patch request to the owning entity endpoint (e.g. parts `/api/parts/123`):
```

13
docs/installation/choosing_database.md
View file

@ -24,16 +24,15 @@ To use **MySQL/MariaDB** as database, you have to install and configure the MySQ
database and user for Part-DB, which needs some additional work. When using docker you need an additional docker
container, and volume for the data
When using **SQLite** The database can be backuped easily by just copying the SQLite file to a safe place. Ideally the *
When using **SQLite** The database can be backuped easily by just copying the SQLite file to a safe place. Ideally, the *
*MySQL** database has to be dumped to a SQL file (using `mysqldump`). The `console partdb:backup` command can do this
automatically
However, SQLite does not support certain operations like regex search, which has to be emulated by PHP and therefore are
pretty slow compared to the same operation at MySQL. In future there might be features that may only be available, when
using MySQL. Also SQLite has limitations in comparisons and sorting of unicode characters, which might lead to unexpected
behavior when using non-ASCII characters in your data. For example `µ` (micro sign) is not seen as equal to `μ`(greek minuscle mu),
therefore searching for `µ` (micro sign) will not find parts containing `μ` (mu) and vice versa. In MySQL identical
looking characters are seen as equal, which is more intuitive in most cases.
However, SQLite does not support certain operations like regex search, which has to be emulated by PHP and therefore is
pretty slow compared to the same operation at MySQL. In the future, there might be features that may only be available, when
using MySQL. Also, SQLite has limitations in comparisons and sorting of Unicode characters, which might lead to unexpected
behavior when using non-ASCII characters in your data. For example `µ` (micro sign) is not seen as equal to `μ(greek minuscule mu),
therefore searching for `µ` (micro sign) will not find parts containing `μ` (mu) and vice versa. In MySQL identical-looking characters are seen as equal, which is more intuitive in most cases.
In general MySQL might perform better for big Part-DB instances with many entries, lots of users and high activity, than
SQLite.

22
docs/installation/installation_docker.md
View file

@ -20,7 +20,7 @@ where docker is available (especially recommended for Windows and macOS).
Docker-compose configures the needed images and automatically creates the needed containers and volumes.
1. Install docker and docker-compose like described under https://docs.docker.com/compose/install/
1. Install docker and docker-compose as described under https://docs.docker.com/compose/install/
2. Create a folder where the Part-DB data should live
3. Create a file named docker-compose.yaml with the following content:
@ -74,7 +74,7 @@ services:
# - TRUSTED_PROXIES=127.0.0.0/8,::1,10.0.0.0/8,172.16.0.0/12,192.168.0.0/16
```
4. Customize the settings by changing the environment variables (or add new ones). See [Configuration]({% link
4. Customize the settings by changing the environment variables (or adding new ones). See [Configuration]({% link
configuration.md %}) for more information.
5. Inside the folder, run
@ -90,10 +90,10 @@ docker exec --user=www-data partdb php bin/console doctrine:migrations:migrate
and watch for the password output
6. Part-DB is available under `http://localhost:8080` and you can log in with username `admin` and the password shown
6. Part-DB is available under `http://localhost:8080` and you can log in with the username `admin` and the password shown
before
The docker image uses a SQLite database and all data (database, uploads and other media) is put into folders relative to
The docker image uses a SQLite database and all data (database, uploads, and other media) is put into folders relative to
the docker-compose.yml.
### MySQL
@ -183,15 +183,15 @@ docker exec --user=www-data partdb php bin/console doctrine:migrations:migrate
## Direct use of docker image
You can use the `jbtronics/part-db1:master` image directly. You have to expose the port 80 to a host port and configure
You can use the `jbtronics/part-db1:master` image directly. You have to expose port 80 to a host port and configure
volumes for `/var/www/html/uploads` and `/var/www/html/public/media`.
If you want to use SQLite database (which is default), you have to configure Part-DB to put the database file in a
mapped volume via the `DATABASE_URL` environment variable.
For example if you set `DATABASE_URL=sqlite:///%kernel.project_dir%/var/db/app.db` then you will have to map
For example, if you set `DATABASE_URL=sqlite:///%kernel.project_dir%/var/db/app.db` then you will have to map
the `/var/www/html/var/db/` folder to the docker container (see docker-compose.yaml for example).
You also have to create the database like described above in step 4.
You also have to create the database as described above in step 4.
## Running console commands
@ -200,8 +200,8 @@ executing `docker exec --user=www-data -it partdb bin/console [command]`
## Troubleshooting
*Login not possible. Login page is just reloading and no error message is shown or something like "CSFR token invalid"*:
*Login is not possible. Login page is just reloading and no error message is shown or something like "CSFR token invalid"*:
Clear all cookies in your browser or use an inkognito tab for Part-DB.
This related to the fact that Part-DB can not set cookies via HTTP, after some webpage has set cookies before under
localhost via https. This is a security mechanism of the browser and can not be bypassed by Part-DB.
Clear all cookies in your browser or use an incognito tab for Part-DB.
This is related to the fact that Part-DB can not set cookies via HTTP after some webpages have set cookies before under
localhost via HTTPS. This is a security mechanism of the browser and can not be bypassed by Part-DB.

33
docs/installation/installation_guide-debian.md
View file

@ -8,9 +8,9 @@ nav_order: 4
# Part-DB installation guide for Debian 11 (Bullseye)
This guide shows you how to install Part-DB directly on Debian 11 using apache2 and SQLite. This guide should work with
recent Ubuntu and other Debian based distributions with little to no changes.
recent Ubuntu and other Debian-based distributions with little to no changes.
Depending on what you want to do, using the prebuilt docker images may be a better choice, as you don't need to install
this many dependencies. See [here]({% link installation/installation_docker.md %}) for more information of the docker
this many dependencies. See [here]({% link installation/installation_docker.md %}) for more information on the docker
installation.
{: .warning }
@ -30,8 +30,8 @@ sudo apt install git curl zip ca-certificates software-properties-common apt-tra
### Install PHP and apache2
Part-DB is written in [PHP](https://php.net) and therefore needs an PHP interpreter to run. Part-DB needs PHP 8.1 or
higher, however it is recommended to use the most recent version of PHP for performance reasons and future
Part-DB is written in [PHP](https://php.net) and therefore needs a PHP interpreter to run. Part-DB needs PHP 8.1 or
higher. However, it is recommended to use the most recent version of PHP for performance reasons and future
compatibility.
As Debian 11 does not ship PHP 8.1 in its default repositories, we have to add a repository for it. You can skip this
@ -46,7 +46,7 @@ sudo curl -sSL https://packages.sury.org/php/README.txt | sudo bash -x
sudo apt update && sudo apt upgrade
```
Now you can install PHP 8.1 and required packages (change the 8.1 in the package version according to the version you
Now you can install PHP 8.1 and the required packages (change the 8.1 in the package version according to the version you
want to use):
```bash
@ -57,8 +57,8 @@ The apache2 webserver should be already installed with this command and configur
### Install composer
Part-DB uses [composer](https://getcomposer.org/) to install required PHP libraries. As the versions shipped in the
repositories is pretty old we install it manually:
Part-DB uses [composer](https://getcomposer.org/) to install required PHP libraries. As the version shipped in the
repositories is pretty old, we will install it manually:
```bash
# Download composer installer script
@ -71,8 +71,8 @@ chmod +x /usr/local/bin/composer
### Install yarn and nodejs
To build the frontend (the user interface) Part-DB uses [yarn](https://yarnpkg.com/). As it depends on Node.js and the
shipped versions are pretty old, we install new versions from official Node.js repository:
To build the front end (the user interface) Part-DB uses [yarn](https://yarnpkg.com/). As it depends on Node.js and the
shipped versions are pretty old, we install new versions from the official Node.js repository:
```bash
# Add recent node repository (nodejs 18 is supported until 2025)
@ -102,7 +102,7 @@ later.
git clone https://github.com/Part-DB/Part-DB-symfony.git /var/www/partdb
```
By default, you are now on the latest development version. In most cases you want to use the latest stable version. You
By default, you are now on the latest development version. In most cases, you want to use the latest stable version. You
can switch to the latest stable version (tagged) by running the following command:
```bash
@ -110,7 +110,7 @@ can switch to the latest stable version (tagged) by running the following comman
git checkout $(git describe --tags $(git rev-list --tags --max-count=1))
```
Alternatively you can check out a specific version by running (
Alternatively, you can check out a specific version by running (
see [GitHub Releases page](https://github.com/Part-DB/Part-DB-server/releases) for a list of available versions):
```bash
@ -176,12 +176,12 @@ To check if everything is installed, run the following command:
sudo -u www-data php bin/console partdb:check-requirements
```
The most things should be green, and no red ones. Yellow messages means optional dependencies which are not important
Most things should be green, and no red ones. Yellow messages mean optional dependencies which are not important
but can improve performance and functionality.
### Create a database for Part-DB
Part-DB by default uses a file based sqlite database to store the data. Use the following command to create the
Part-DB by default uses a file-based SQLite database to store the data. Use the following command to create the
database. The database will normally be created at `/var/www/partdb/var/app.db`.
```bash
@ -191,8 +191,7 @@ sudo -u www-data php bin/console doctrine:migrations:migrate
The command will warn you about schema changes and potential data loss. Continue with typing `yes`.
The command will output several lines of information. Somewhere should be a yellow background message
like `The initial password for the "admin" user is: f502481134`. Write down this password as you will need it later for
initial login.
like `The initial password for the "admin" user is: f502481134`. Write down this password as you will need it later for the initial login.
### Configure apache2 to show Part-DB
@ -248,7 +247,7 @@ sudo service apache2 restart
```
and Part-DB should now be available under `http://YourServerIP` (or `http://partdb.lan` if you configured DNS in your
network to point on the server).
network to point to the server).
### Login to Part-DB
@ -288,7 +287,7 @@ sudo -u www-data php bin/console cache:clear
## MySQL/MariaDB database
To use a MySQL database, follow the steps from above (except the creation of database, we will do this later).
To use a MySQL database, follow the steps from above (except the creation of the database, we will do this later).
Debian 11 does not ship MySQL in its repositories anymore, so we use the compatible MariaDB instead:
1. Install maria-db with:

2
docs/installation/nginx.md
View file

@ -13,7 +13,7 @@ configured.
## Setup
1. Install composer and yarn like described in the [apache guide]({% link installation/installation_guide-debian.md
1. Install composer and yarn as described in the [apache guide]({% link installation/installation_guide-debian.md
%}#install-composer).
2. Create a folder for Part-DB and install and configure it as described
3. Instead of creating the config for apache, add the following snippet to your nginx config:

28
docs/installation/saml_sso.md
View file

@ -48,7 +48,7 @@ the [Keycloak Getting Started Guide](https://www.keycloak.org/docs/latest/gettin
*It is recommended to set this value to the domain name of your Part-DB installation, with an attached `/sp` (
e.g. `https://partdb.yourdomain.invalid/sp`)*.
The name field should be set to something human-readable, like `Part-DB`.
3. Click on `Save` to create the new client.
3. Click on `Save` to create a new client.
### Configure the SAML client
@ -56,7 +56,7 @@ the [Keycloak Getting Started Guide](https://www.keycloak.org/docs/latest/gettin
* Set `Home URL` to the homepage of your Part-DB installation (e.g. `https://partdb.yourdomain.invalid/`).
* Set `Valid redirect URIs` to your homepage with a wildcard at the end (
e.g. `https://partdb.yourdomain.invalid/*`).
* Set `Valid post logout redirect URIs` to `+` to allow all urls from the `Valid redirect URIs`.
* Set `Valid post logout redirect URIs` to `+` to allow all URLs from the `Valid redirect URIs`.
* Set `Name ID format` to `username`
* Ensure `Force POST binding` is enabled.
* Ensure `Sign documents` is enabled.
@ -135,8 +135,8 @@ On the first login of a SAML user, Part-DB will create a new user in the databas
as the SAML user, but no password set. The user will be marked as a SAML user, so he can only log in via SAML in the
future. However, in other aspects the user is a normal user, so Part-DB admins can set permissions for SAML users like
for any other user and override permissions assigned via groups.
For large organizations you maybe want to automatically assign permissions to SAML users based on the roles or
For large organizations, you maybe want to automatically assign permissions to SAML users based on the roles or
groups configured in the identity provider. For this purpose Part-DB allows you to map SAML roles or groups to Part-DB
groups. See the next section for details.
@ -144,11 +144,11 @@ groups. See the next section for details.
Part-DB allows you to configure a mapping between SAML roles or groups and Part-DB groups. This allows you to
automatically assign permissions to SAML users based on the roles or groups configured in the identity provider. For
example if a user at your SAML provider has the role `admin`, you can configure Part-DB to assign the `admin` group to
example, if a user at your SAML provider has the role `admin`, you can configure Part-DB to assign the `admin` group to
this user. This will give the user all permissions of the `admin` group.
For this you need first have to create the groups in Part-DB, to which you want to assign the users and configure their
permissions. You will need the IDs of the groups, which you can find in the `System->Group` page of Part-DB in the Info
For this, you need first have to create the groups in Part-DB, to which you want to assign the users and configure their
permissions. You will need the IDs of the groups, which you can find on the `System->Group` page of Part-DB in the Info
tab.
The map is provided as [JSON](https://en.wikipedia.org/wiki/JSON) encoded map between the SAML role and the group ID,
@ -158,7 +158,7 @@ you can configure via the `.env.local` or `docker-compose.yml` file. Please note
string in single quotes here, as JSON itself uses double quotes (
e.g. `SAML_ROLE_MAPPING='{ "*": 2, "editor": 3, "admin": 1 }`).
For example if you want to assign the group with ID 1 (by default admin) to every SAML user which has the role `admin`,
For example, if you want to assign the group with ID 1 (by default admin) to every SAML user which has the role `admin`,
the role with ID 3 (by default editor) to every SAML user with the role `editor` and everybody else to the group with ID
2 (by default readonly), you can configure the following map:
@ -176,9 +176,9 @@ If you want to assign users with a certain role to an empty group, provide the g
valid group ID, so the user will not be assigned to any group.
The SAML roles (or groups depending on your configuration), have to be supplied via a SAML attribute `group`. You have
to configure your SAML identity provider to provide this attribute. For example in Keycloak you can configure this
attribute in the `Client scopes` page. Select the `sp-dedicated` client scope (or create a new one) and click
on `Add mappers`. Select `Role mapping` or `Group membership`, change the field name and click `Add`. Now Part-DB will
to configure your SAML identity provider to provide this attribute. For example, in Keycloak you can configure this
attribute on the `Client scopes` page. Select the `sp-dedicated` client scope (or create a new one) and click
on `Add mappers`. Select `Role mapping` or `Group membership`, change the field name, and click `Add`. Now Part-DB will
be provided with the groups of the user based on the Keycloak user database.
By default, the group is assigned to the user on the first login and updated on every login based on the SAML
@ -203,12 +203,12 @@ provide these attributes, you can use to automatically fill the corresponding fi
## Use SAML Login for existing users
Part-DB distinguishes between local users and SAML users. Local users are users, which can log in via Part-DB login form
and which use the password (hash) saved in the Part-DB database. SAML users are stored in the database too (they are
Part-DB distinguishes between local users and SAML users. Local users are users, that can log in via the Part-DB login form
and use the password (hash) saved in the Part-DB database. SAML users are stored in the database too (they are
created on the first login of the user via SAML), but they use the SAML identity provider to authenticate the user and
have no password stored in the database. When you try you will get an error message.
For security reasons it is not possible to authenticate via SAML as a local user (and vice versa). So if you have
For security reasons, it is not possible to authenticate via SAML as a local user (and vice versa). So if you have
existing users in your Part-DB database and want them to be able to log in via SAML in the future, you can use
the `php bin/console partdb:user:convert-to-saml-user username` command to convert them to SAML users. This will remove
the password hash from the database and mark them as SAML users, so they can log in via SAML in the future.

16
docs/usage/backup_restore.md
View file

@ -7,8 +7,8 @@ parent: Usage
# Backup and Restore Data
When working productively you should back up the data and configuration of Part-DB regularly to prevent data loss. This
is also useful, if you want to migrate your Part-DB instance from one server to another. In that case you just have to
back up the data on server 1, move the backup to server 2, install Part-DB on server 2 and restore the backup.
is also useful if you want to migrate your Part-DB instance from one server to another. In that case, you just have to
back up the data on server 1, move the backup to server 2, install Part-DB on server 2, and restore the backup.
## Backup (automatic / Part-DB supported)
@ -23,11 +23,11 @@ To back up all possible data, run the following
command: `php bin/console partdb:backup --full /path/to/backup/partdb_backup.zip`.
It is possible to do only partial backups (config, attachments, or database). See `php bin/console partdb:backup --help`
for more infos about these options.
for more info about these options.
## Backup (manual)
There are 3 parts which have to be backup-ed: The configuration files, which contains the instance specific options, the
3 parts have to be backup-ed: The configuration files, which contain the instance-specific options, the
uploaded files of attachments, and the database containing the most data of Part-DB.
Everything else like thumbnails and cache files, are recreated automatically when needed.
@ -42,7 +42,7 @@ You have to recursively copy the `uploads/` folder and the `public/media` folder
### Database
#### Sqlite
#### SQLite
If you are using sqlite, it is sufficient to just copy your `app.db` from your database location (normally `var/app.db`)
to your backup location.
@ -55,8 +55,8 @@ interface (`mysqldump -uBACKUP -pPASSWORD DATABASE`)
## Restore
Install Part-DB as usual as described in the installation section, except the database creation / migration part. You
have to use the same database type (sqlite or mysql) as on the back-up server instance.
Install Part-DB as usual as described in the installation section, except for the database creation/migration part. You
have to use the same database type (SQLite or MySQL) as on the backuped server instance.
### Restore configuration
@ -69,7 +69,7 @@ Copy the `uploads/` and the `public/media/` folder from your backup into your ne
### Restore database
#### Sqlite
#### SQLite
Copy the backup-ed `app.db` into the database folder normally `var/app.db` in Part-DB root folder.

4
docs/usage/eda_integration.md
View file

@ -65,11 +65,11 @@ you need to define at least a symbol, footprint, reference prefix, or value on a
You can use the "Force visibility" checkbox on a part or category to override this behavior and force parts to be visible or hidden in KiCad.
*Please note that KiCad caches the library categories. So if you change something, which would change the visibile categories in KiCad, you have to reload EEschema to see the changes.*
*Please note that KiCad caches the library categories. So if you change something, which would change the visible categories in KiCad, you have to reload EEschema to see the changes.*
### Category depth in KiCad
For performance reasons, only the mmost top-level categories of Part-DB are shown as categories in KiCad. All parts in the subcategories are shown in the top-level category.
For performance reasons, only the most top-level categories of Part-DB are shown as categories in KiCad. All parts in the subcategories are shown in the top-level category.
You can configure the depth of the categories shown in KiCad, via the `EDA_KICAD_CATEGORY_DEPTH` env option. The default value is 0, which means only the top-level categories are shown.
To show more levels of categories, you can set this value to a higher number.

61
docs/usage/getting_started.md
View file

@ -18,22 +18,22 @@ Before you start creating data structures, you should configure Part-DB to your
options.
This is done either via changing the `.env.local` file in a direct installation or by changing the env variables in
your `docker-compose.yaml` file.
A list of possible configuration options, can be found [here]({% link configuration.md %}).
A list of possible configuration options can be found [here]({% link configuration.md %}).
## Change password, Set up Two-Factor-Authentication & Customize User settings
If you have not already done, you should change your user password. You can do this in the user settings (available in
the navigation bar drop down with the user symbol).
If you have not already done so, you should change your user password. You can do this in the user settings (available in
the navigation bar drop-down with the user symbol).
![image]({% link assets/getting_started/change_password.png %})
There you can also find the option, to set up Two-Factor Authentication methods like Google Authenticator. Using this is
highly recommended (especially if you have admin permissions) to increase the security of your account. (Two-Factor
Authentication even can be enforced for all members of a user group)
highly recommended (especially if you have admin permissions) to increase the security of your account. (Two-factor authentication
even can be enforced for all members of a user group)
In the user settings panel you can change account infos like your username, your first and last name (which will be
shown alongside your username to identify you better), department information and your email address. The email address
is used to send password reset mails, if your system is configured to use this.
In the user settings panel, you can change account info like your username, your first and last name (which will be
shown alongside your username to identify you better), department information, and your email address. The email address
is used to send password reset mails if your system is configured to use this.
![image]({% link assets/getting_started/user_settings.png %})
@ -46,7 +46,7 @@ used.
The banner which is shown on the homepage, can be customized/changed by changing the `config/banner.md` file with a text
editor. You can use markdown and (safe) HTML here, to style and customize the banner.
You can even use Latex style equations by wrapping the expressions into `$` (like `$E=mc^2$`, which is rendered inline:
You can even use LaTeX-style equations by wrapping the expressions into `$` (like `$E=mc^2$`, which is rendered inline:
$E=mc^2$) or `$$` (like `$$E=mc^2$$`) which will be rendered as a block, like so: $$E=mc^2$$
## Create groups, users and customize permissions
@ -55,14 +55,14 @@ $E=mc^2$) or `$$` (like `$$E=mc^2$$`) which will be rendered as a block, like so
When logged in as administrator, you can open the users menu in the `Tools` section of the sidebar
under `System -> Users`.
At this page you can create new users, change their passwords and settings and change their permissions.
For each user which should use Part-DB you should set up an own account, so that tracking of what user did what works
On this page you can create new users, change their passwords and settings, and change their permissions.
For each user who should use Part-DB you should set up their own account so that tracking of what user did works
properly.
![image]({% link assets/getting_started/user_admin.png %})
You should check the permissions for every user and ensure that they are in the intended way, and no user has more
permissions than he needs.
For each capability you can choose between allow, forbid and inherit. In the last case, the permission is determined by
For each capability, you can choose between allow, forbid, and inherit. In the last case, the permission is determined by
the group a user has (if no group is chosen, it equals forbid)
![image]({% link assets/getting_started/user_permissions.png %})
@ -75,35 +75,34 @@ to restrict the permissions.
### Groups
If you have many users which should share the same permissions, it is useful to define the permissions using user
If you have many users who should share the same permissions, it is useful to define the permissions using user
groups, which you can create and edit in the `System -> Groups` menu.
By default 3 groups are defined:
By default, 3 groups are defined:
* `readonly` which users only have read permissions (like viewing, searching parts, attachments, etc.)
* `users` which users also have rights to edit/delete/create elements
* `admin` which users can do administrative operations (like creating new users, show global system log, etc.)
* `admin` which users can do administrative operations (like creating new users, showing global system log, etc.)
Users only use the setting of a capability from a group, if the user has a group associated and the capability on the
user is set to `inherit` (which is the default if creating a new user). You can override the permissions settings of a
group per user by explicitly settings the permission at the user.
group per user by explicitly setting the permission of the user.
Groups are organized as trees, meaning a group can have parent and child permissions and child groups can inherit
permissions from their parents.
To inherit the permissions from a parent group set the capability to inherit, otherwise set it explicitly to override
To inherit the permissions from a parent group set the capability to inherit, otherwise, set it explicitly to override
the parents' permission.
## Create Attachment types
Every attachment (that is a file associated with a part, data structure, etc.) must have an attachment type. They can
be used to group attachments logically, like differentiating between datasheets, pictures and other documents.
be used to group attachments logically, like differentiating between datasheets, pictures, and other documents.
You can create/edit attachment types in the tools sidebar under "Edit -> Attachment types":
![image]({% link assets/getting_started/attachment_type_admin.png %})
Depending on your use case different entries here make sense. For part management the following (additional) entries
maybe make sense:
Depending on your use case different entries here make sense. For part management the following (additional) entries may make sense:
* Datasheets (restricted to pdfs, Allowed filetypes: `application/pdf`)
* Pictures (for generic pictures of components, storage locations, etc., Allowed filetypes: `image/*`
@ -111,34 +110,34 @@ maybe make sense:
For every attachment type a list of allowed file types, which can be uploaded to an attachment with this attachment
type, can be defined. You can either pass a list of allowed file extensions (e.g. `.pdf, .zip, .docx`) and/or a list
of [Mime Types](https://en.wikipedia.org/wiki/Media_type) (e.g. `application/pdf, image/jpeg`) or a combination of both
here. To allow all browser supported images, you can use `image/*` wildcard here.
here. To allow all browser-supported images, you can use `image/*` wildcard here.
## (Optional) Create Currencies
If you want to save price information for parts in a currency different to your global currency (by default Euro), you
If you want to save price information for parts in a currency different from your global currency (by default Euro), you
have to define the additional currencies you want to use under `Edit -> Currencies`:
![image]({% link assets/getting_started/currencies_admin.png %})
You create a new currency, name it however you want (it is recommended to use the official name of the currency) and
select the currency ISO code from the list and save it. The currency symbol is determined automatically from chose ISO
You create a new currency, name it however you want (it is recommended to use the official name of the currency),
select the currency ISO code from the list, and save it. The currency symbol is determined automatically from the chosen ISO
code.
You can define an exchange rate in terms of your base currency (e.g. how many euros is one unit of your currency worth)
to convert the currencies values in your preferred display currency automatically.
to convert the currency values in your preferred display currency automatically.
## (Optional) Create Measurement Units
By default, Part-DB assumes that the parts in inventory can be counted by individual indivisible pieces, like LEDs in a
box or books in a shelf.
box or books on a shelf.
However, if you want to manage things, that are divisible and the stock is described by a physical quantity, like
length for cables, or volumina of a liquid, you have to define additional measurement units.
length for cables, or volumes of a liquid, you have to define additional measurement units.
This is possible under `Edit -> Measurement Units`:
![image]({% link assets/getting_started/units_admin.png %})
You can give the measurement unit a name and an optional unit symbol (like `m` for meters) which is shown when
quantities in this unit are displayed. The option `Use SI prefix` is useful for almost all physical quantities, as big
and small numbers are automatically formatted with SI-prefixes (like 1.5kg instead 1500 grams).
and small numbers are automatically formatted with SI prefixes (like 1.5kg instead 1500 grams).
The measurement unit can be selected for each part individually, by setting the option in the advanced tab of a part`s
edit menu.
@ -157,16 +156,16 @@ Every part has to be assigned to a category, so you should create at least one c
## (Optional) Create Footprints
Footprints are used to describe the physical shape of a part, like a resistor or a capacitor.
They can be used to group parts by their physical shape and to find parts with in the same package.
They can be used to group parts by their physical shape and to find parts within the same package.
You can create/edit footprints in the tools sidebar under "Edit -> Footprints".
It is useful to create footprints for the most common packages, like SMD resistors, capacitors, etc. to make it easier
to find parts with the same footprint.
You should create these as a tree structure, so that you can group footprints by their type.
You should create these as a tree structure so that you can group footprints by their type.
See [Concepts]({% link concepts.md %}) for an example tree structure.
You can define attachments here which are associated with the footprint. The attachment set as preview image, will be
You can define attachments here which are associated with the footprint. The attachment set as the preview image, will be
used whenever a visual representation of the footprint is needed (e.g. in the part list).
For many common footprints, you can use the built-in footprints, which can be found in the "Builtin footprint image

52
docs/usage/import_export.md
View file

@ -7,7 +7,7 @@ parent: Usage
# Import & Export data
Part-DB offers the possibility to import existing data (parts, datastructures, etc.) from existing data sources into
Part-DB offers the possibility to import existing data (parts, data structures, etc.) from existing data sources into
Part-DB. Data can also be exported from Part-DB into various formats.
## Import
@ -34,23 +34,23 @@ find in the "Tools" sidebar panel.
> You will not be able to check the data before it is written to the database, so you should review the data before
> using the import tool.
You can upload the file which should be imported here and choose various options on how the data should be treated:
You can upload the file that should be imported here and choose various options on how the data should be treated:
* **Format**: By default "auto" is selected here and Part-DB will try to detect the format of the file automatically
based on its file extension. If you want to force a specific format or Part-DB can not auto-detect the format, you can
select it here.
* **CSV delimiter**: If you upload an CSV file, you can select the delimiter character which is used to separate the
columns in the CSV file. Depending on the CSV file, this might be a comma (`,`), semicolon (`;`).
* **CSV delimiter**: If you upload a CSV file, you can select the delimiter character which is used to separate the
columns in the CSV file. Depending on the CSV file, this might be a comma (`,`) or semicolon (`;`).
* **Category override**: You can select (or create) a category here, to which all imported parts should be assigned, no
matter what was specified in the import file. This can be useful if you want to assign all imports to a certain
category or if no category is specified in the data. If you leave this field empty, the category will be determined by
the import file (or the export will error, if no category is specified).
* **Mark all imported parts as "Needs review"**: If this is selected, all imported parts will be marked as "Needs
review" after the import. This can be useful if you want to review all imported parts before using them.
* **Create unknown datastructures**: If this is selected Part-DB will create new datastructures (like categories,
manufacturers, etc.) if no datastructure(s) with the same name and path already exists. If this is not selected, only
existing datastructures will be used and if no matching datastrucure is found, the imported parts field will be empty.
* **Path delimiter**: Part-DB allows you to create/select nested datastructures (like categories, manufacturers, etc.)
* **Create unknown data structures**: If this is selected Part-DB will create new data structures (like categories,
manufacturers, etc.) if no data structure(s) with the same name and path already exists. If this is not selected, only
existing data structures will be used and if no matching data strucure is found, the imported parts field will be empty.
* **Path delimiter**: Part-DB allows you to create/select nested data structures (like categories, manufacturers, etc.)
by using a path (e.g. `Category 1->Category 1.1`, which will select/create the `Category 1.1` whose parent
is `Category 1`). This path is separated by the path delimiter. If you want to use a different path delimiter than the
default one (which is `>`), you can select it here.
@ -59,7 +59,7 @@ You can upload the file which should be imported here and choose various options
is not selected, the import will continue for the other parts and only the invalid parts will be skipped.
After you have selected the options, you can start the import by clicking the "Import" button. When the import is
finished, you will see the results of the import in the lower half of the page. You find a table with the imported
finished, you will see the results of the import in the lower half of the page. You can find a table with the imported
parts (including links to them) there.
#### Fields description
@ -83,14 +83,14 @@ leave them empty or do not include the column in your file.
* **`manufacturing_status`**: The manufacturing status of the part, must be one of the following
values: `announced`, `active`, `nrfnd`, `eol`, `discontinued` or left empty.
* **`needs_review`** or **`needs_review`**: If this is set to `1`, the part will be marked as "needs review".
* **`tags`**: A comma separated list of tags for the part.
* **`tags`**: A comma-separated list of tags for the part.
* **`mass`**: The mass of the part in grams.
* **`ipn`**: The IPN (Item Part Number) of the part.
* **`minamount`**: The minimum amount of the part which should be in stock.
* **`partUnit`**: The measurement unit of the part to use. Can be a path similar to the category field.
With the following fields you can specify storage locations and amount / quantity in stock of the part. An PartLot will
be created automatically from the data and assigned to the part. The following fields are helpers for an easy import for
With the following fields, you can specify storage locations and amount/quantity in stock of the part. A PartLot will
be created automatically from the data and assigned to the part. The following fields are helpers for an easy import of
parts at one storage location. If you need to create a Part with multiple PartLots you have to use JSON format (or CSV)
with nested objects:
@ -99,7 +99,7 @@ field.
**`amount`**, **`quantity`** or **`instock`**: The amount of the part in stock. If this value is not set, the part lot
will be marked with "unknown amount"
The following fields can be used to specify the supplier/distributor, supplier product number and the price of the part.
The following fields can be used to specify the supplier/distributor, supplier product number, and the price of the part.
This is only possible for a single supplier/distributor and price with these fields. If you need to specify multiple
suppliers/distributors or prices, you have to use JSON format (or CSV) with nested objects.
**Please note that the supplier fields is required, if you want to import prices or supplier product numbers**. If the
@ -125,31 +125,31 @@ give the user any additional information.
You can export data structures (like categories, manufacturers, etc.) in the respective edit page (e.g. Tools Panel ->
Edit -> Category).
If you select a certain datastructure from your list, you can export it (and optionally all sub-datastructures) in the "
If you select a certain data structure from your list, you can export it (and optionally all sub data structures) in the "
Export" tab.
If you want to export all datastructures of a certain type (e.g. all categories in your database), you can select the "
If you want to export all data structures of a certain type (e.g. all categories in your database), you can select the "
Export all" function in the "Import / Export" tab of the "new element" page.
You can select between the following export formats:
* **CSV** (Comma Separated Values): A semicolon separated list of values, where every line represents an element. This
* **CSV** (Comma Separated Values): A semicolon-separated list of values, where every line represents an element. This
format can be imported into Excel or LibreOffice Calc and is easy to work with. However, it does not support nested
datastructures or sub data (like parameters, attachments, etc.), very well (many columns are generated, as every
possible sub data is exported as a separate column).
data structures or sub data (like parameters, attachments, etc.), very well (many columns are generated, as every
possible sub-data is exported as a separate column).
* **JSON** (JavaScript Object Notation): A text-based format, which is easy to work with programming languages. It
supports nested datastructures and sub data (like parameters, attachments, etc.) very well. However, it is not easy to
work with in Excel or LibreOffice Calc and you maybe need to write some code to work with the exported data
supports nested data structures and sub-data (like parameters, attachments, etc.) very well. However, it is not easy to
work with in Excel or LibreOffice Calc and you may need to write some code to work with the exported data
efficiently.
* **YAML** (Yet another Markup Language): Very similar to JSON
* **XML** (Extensible Markup Language): Good support with nested datastructures. Similar use case as JSON and YAML.
* **YAML** (Yet Another Markup Language): Very similar to JSON
* **XML** (Extensible Markup Language): Good support with nested data structures. Similar use cases as JSON and YAML.
Also, you can select between the following export levels:
* **Simple**: This will only export very basic information about the name (like the name, or description for parts)
* **Extended**: This will export all commonly used information about this datastructure (like notes, options, etc.)
* **Full**: This will export all available information about this datastructure (like all parameters, attachments)
* **Extended**: This will export all commonly used information about this data structure (like notes, options, etc.)
* **Full**: This will export all available information about this data structure (like all parameters, attachments)
Please note that the level will also be applied to all sub data or children elements. So if you select "Full" for a
Please note that the level will also be applied to all sub-data or children elements. So if you select "Full" for a
part, all the associated categories, manufacturers, footprints, etc. will also be exported with all available
information, this can lead to very large export files.
@ -158,4 +158,4 @@ information, this can lead to very large export files.
You can export parts in all part tables. Select the parts you want via the checkbox in the table line and select the
export format and level in the appearing menu.
See the section about exporting datastructures for more information about the export formats and levels.
See the section about exporting data structures for more information about the export formats and levels.