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 more typos and grammar issues in docs

Browse source
This commit is contained in:
Jan Böhmer 2024-02-23 14:26:17 +01:00
parent 5d68922f2e
commit 861c0174df
10 changed files with 164 additions and 169 deletions
Download patch file Download diff file Expand all files Collapse all files

98
docs/concepts.md
View file

@ -11,55 +11,55 @@ This page explains the different concepts of Part-DB and what their intended use
1. TOC 1. TOC
{:toc} {:toc}
## Part managment ## Part management
### Part ### Part
A part is the central concept of Part-DB. A part represents a single kind (or type) of a thing, like an electronic A part is the central concept of Part-DB. A part represents a single kind (or type) of a thing, like an electronic
component, a device, a book or similar (depending on what you use Part-DB for). A part entity just represents a certain component, a device, a book or similar (depending on what you use Part-DB for). A part entity just represents a certain
type of thing, so if you have 1000 times an BC547 transistor you would create ONE part with the name BC547 and set its type of thing, so if you have 1000 times a BC547 transistor you would create ONE part with the name BC547 and set its
quantity to 1000. The individual quantities (so a single BC547 transistor) of a part, should be indistinguishable from quantity to 1000. The individual quantities (so a single BC547 transistor) of a part, should be indistinguishable from
each other, so that it does not matter which one of your 1000 things of Part you use. each other so that it does not matter which one of your 1000 things of Part you use.
A part entity have many fields, which can be used to describe it better. Most of the fields are optional: A part entity has many fields, which can be used to describe it better. Most of the fields are optional:
* **Name** (Required): The name of the part or how you want to call it. This could be a manufacturer provided name, or a * **Name** (Required): The name of the part or how you want to call it. This could be a manufacturer-provided name, or a
name you thought of your self. The name have to be unique in a single category. name you thought of yourself. The name have to be unique in a single category.
* **Description**: A short (single-line) description of what this part is/does. For longer information you should use * **Description**: A short (single-line) description of what this part is/does. For longer information, you should use
the comment field or the specifications the comment field or the specifications
* **Category** (Required): The category (see there) to which this part belongs to. * **Category** (Required): The category (see there) to which this part belongs to.
* **Tags**: The list of tags this part belong to. Tags can be used to group parts logically (similar to the category), * **Tags**: The list of tags this part belongs to. Tags can be used to group parts logically (similar to the category),
but tags are much less strict and formal (they don't have to be defined forehands) and you can assign multiple tags to but tags are much less strict and formal (they don't have to be defined forehands) and you can assign multiple tags to
a part. When clicking on a tag, a list with all parts which have the same tag, is shown. a part. When clicking on a tag, a list with all parts which have the same tag, is shown.
* **Min Instock**: *Not really implemented yet*. Parts where the total instock is below this value, will show up for * **Min Instock**: *Not really implemented yet*. Parts where the total instock is below this value, will show up for
ordering. ordering.
* **Footprint**: See there. Useful especially for electronic parts, which have one of the common electronic footprints ( * **Footprint**: See there. Useful especially for electronic parts, which have one of the common electronic footprints (
like DIP8, SMD0805 or similar). If a part has no explicit defined preview picture, the preview picture of its like DIP8, SMD0805 or similar). If a part has no explicitly defined preview picture, the preview picture of its
footprint will be shown instead in tables. footprint will be shown instead in tables.
* **Manufacturer**: The manufacturer which has manufactured (not sold) this part. See Manufacturer entity for more info. * **Manufacturer**: The manufacturer which has manufactured (not sold) this part. See Manufacturer entity for more info.
* **Manufacturer part number** (MPN): If you have used your own name for a part, you can put the part number the * **Manufacturer part number** (MPN): If you have used your own name for a part, you can put the part number the
manufacturer uses in this field, so that you can find a part also under its manufacturer number. manufacturer uses in this field so that you can find a part also under its manufacturer number.
* **Link to product page**: If you want to link to the manufacturer website of a part, and it is not possible to * **Link to product page**: If you want to link to the manufacturer website of a part, and it is not possible to
determine it automatically from the part name, set in the manufacturer entity (or no manufacturer is set), you can set determine it automatically from the part name, set in the manufacturer entity (or no manufacturer is set), you can set
the link here for each part individually. the link here for each part individually.
* **Manufacturing Status**: The manufacturing status of this part, meaning the information about where the part is in * **Manufacturing Status**: The manufacturing status of this part, meaning the information about where the part is in
its manufacturing lifecycle. its manufacturing lifecycle.
* **Needs review**: If you think parts information maybe are inaccurate or incomplete and needs some later * **Needs review**: If you think parts information may be inaccurate or incomplete and needs some later
review/checking, you can set this flag. A part with this flag is marked, so that users know the information are not review/checking, you can set this flag. A part with this flag is marked, so that users know the information is not
completely trustworthy. completely trustworthy.
* **Favorite**: Parts with this flag are highlighted in parts lists * **Favorite**: Parts with this flag are highlighted in parts lists
* **Mass**: The mass of a single piece of this part (so of a single transistor). Given in grams. * **Mass**: The mass of a single piece of this part (so of a single transistor). Given in grams.
* **Internal Part number** (IPN): Each part is automatically assigned a numerical ID which identifies a part in the * **Internal Part number** (IPN): Each part is automatically assigned a numerical ID that identifies a part in the
database. This ID depends on when a part was created and can not be changed. If you want to assign your own unique database. This ID depends on when a part was created and can not be changed. If you want to assign your own unique
identifiers, or sync parts identifiers with the identifiers of another database you can use this field. identifiers, or sync parts identifiers with the identifiers of another database you can use this field.
### Stock / Part lot ### Stock / Part lot
A part can have many stock at multiple different locations. This is represented by part lots / stocks, which consists A part can have many stocks at multiple different locations. This is represented by part lots/stocks, which consists
basically of a storage location (so where are the parts of this lot are stored) and an amount (how many parts are there). basically of a storage location (so where the parts of this lot are stored) and an amount (how many parts are there).
### Purchase Information ### Purchase Information
The purchase information describe where the part can be bought (at which vendors) and to which prices. The purchase information describes where the part can be bought (at which vendors) and at which prices.
The first part (the order information) describes at which supplier the part can be bought and which is the name of the The first part (the order information) describes at which supplier the part can be bought and which is the name of the
part under which you can order the part there. part under which you can order the part there.
An order information can contain multiple price information, which describes the prices for the part at the supplier An order information can contain multiple price information, which describes the prices for the part at the supplier
@ -67,13 +67,13 @@ including bulk discount, etc.
### Parameters ### Parameters
Parameters represents various specifications / parameters of a part, like the maximum current of a diode, etc. The Parameters represent various specifications/parameters of a part, like the maximum current of a diode, etc. The
advantage of using parameters instead of just putting the data in the comment field or so, is that you can filter for advantage of using parameters instead of just putting the data in the comment field or so, is that you can filter for
parameters values (including ranges and more) later on. parameter's values (including ranges and more) later on.
Parameters describe can describe numeric values and/or text values for which they can be filtered. This basically allows Parameters can describe numeric values and/or text values for which they can be filtered. This allows
you to define custom fields on a part. you to define custom fields on a part.
Using the group field a parameter allows you to group parameters together in the info page later (all parameters with Using the group field as a parameter allows you to group parameters together on the info page later (all parameters with
the same group value will be shown under the same group title). the same group value will be shown under the same group title).
## Core data ## Core data
@ -99,17 +99,17 @@ possible category tree could look like this:
### Supplier ### Supplier
A Supplier is a vendor / distributor where you can buy/order parts. Price information of parts are associated with a A Supplier is a vendor/distributor where you can buy/order parts. Price information of parts is associated with a
supplier. supplier.
### Manufacturer ### Manufacturer
A manufacturer represents the company that manufacturer / build various parts (not necessary sell them). If the A manufacturer represents the company that manufacturers/builds various parts (not necessarily sell them). If the
manufacturer also sell the parts, you have to create a supplier for that. manufacturer also sells the parts, you have to create a supplier for that.
### Storage location ### Storage location
A storage location represents a place where parts can be stored. This could be a box, a shelf or other things (like the A storage location represents a place where parts can be stored. This could be a box, a shelf, or other things (like the
SMD feeder of a machine or so). SMD feeder of a machine or so).
Storage locations are hierarchical to represent storage locations contained in each other. Storage locations are hierarchical to represent storage locations contained in each other.
@ -129,12 +129,12 @@ Storage locations should be defined down to the smallest possible location, to m
### Footprint ### Footprint
In electronics many components have one of the common components cases / footprints. The footprint entity describes such In electronics, many components have one of the common components cases/footprints. The footprint entity describes such
common footprints, which can be assigned to parts. common footprints, which can be assigned to parts.
You can assign an image (and an 3D model) as an attachment to a footprint, which will be used as preview for parts with You can assign an image (and a 3D model) as an attachment to a footprint, which will be used as preview for parts with
this footprint, even if the parts do not have an explicitly assigned preview image. this footprint, even if the parts do not have an explicitly assigned preview image.
Footprints are a hierarchically which allows you to build logical sorted trees. An example tree could look like this: Footprints are hierarchically which allows you to build logically sorted trees. An example tree could look like this:
* Through-Hole components * Through-Hole components
* DIP * DIP
@ -153,17 +153,17 @@ Footprints are a hierarchically which allows you to build logical sorted trees.
### Measurement Unit ### Measurement Unit
By default, part instock is counted in number of individual parts, which is fine for things like electronic components, By default, part instock is counted in number of individual parts, which is fine for things like electronic components,
which exists only in integer quantities. However, if you have things with fractional units like the length of a wire or which exist only in integer quantities. However, if you have things with fractional units like the length of a wire or
the volume of a liquid, you have to define a measurement unit. the volume of a liquid, you have to define a measurement unit.
The measurement unit represents a physical quantity like mass, volume or length. The measurement unit represents a physical quantity like mass, volume, or length.
You can define a short unit for it (like m for Meters, or g for gramms) which will be shown, when a quantity of a part You can define a short unit for it (like m for Meters, or g for grams) which will be shown when a quantity of a part
with this unit is shown. with this unit is shown.
### Currency ### Currency
By default, all prices are set in the base currency configured for the instance (by default euros). If you want to use By default, all prices are set in the base currency configured for the instance (by default euros). If you want to use
multiple currencies together (as e.g. vendors use foreign currencies for their price, and you do not want to update the multiple currencies together (e.g. vendors use foreign currencies for their price, and you do not want to update the
prices for every exchange rate change), you have to define these currencies here. prices for every exchange rate change), you have to define these currencies here.
You can set an exchange rate here in terms of the base currency (or fetch it from the internet if configured). The You can set an exchange rate here in terms of the base currency (or fetch it from the internet if configured). The
@ -173,57 +173,57 @@ exchange rate will be used to show users the prices in their preferred currency.
### Attachment ### Attachment
An attachment is a file that can be associated with another entity (like a Part, Storelocation, User, etc.). This could An attachment is a file that can be associated with another entity (like a Part, location, User, etc.). This could
for example be a datasheet in a Part, the logo of a vendor or some CAD drawing of a footprint. for example be a datasheet in a Part, the logo of a vendor or some CAD drawing of a footprint.
An attachment has an attachment type (see below), which groups the attachments logically (and optionally restricts the An attachment has an attachment type (see below), which groups the attachments logically (and optionally restricts the
allowed file types), a name describing the attachment and a file. The file can either be uploaded to the server and allowed file types), a name describing the attachment and a file. The file can either be uploaded to the server and
stored there, or given as a link to a file on another web path. If configured in the settings, it is also possible that stored there, or given as a link to a file on another web path. If configured in the settings, it is also possible that
the webserver downloads the file from the supplied website and stores it locally on the server. the web server downloads the file from the supplied website and stores it locally on the server.
By default, all uploaded files, are accessible for everyone (even non-logged-in users), if the link is known. If your By default, all uploaded files, are accessible for everyone (even non-logged-in users), if the link is known. If your
Part-DB instance is publicly available, and you want to store private/sensitive files on it, you should mark the Part-DB instance is publicly available, and you want to store private/sensitive files on it, you should mark the
attachment as "Private attachment". Private attachments are only accessible to users, which has the permission to access attachment as "Private attachment". Private attachments are only accessible to users, which has permission to access
private attachments. private attachments.
Please not, that no thumbnails are generated for private attachments, which can have a performance impact. Please note, that no thumbnails are generated for private attachments, which can have a performance impact.
Part-DB ships some preview images for various common footprints like DIP-8 and others, as internal resources. These can Part-DB ships some preview images for various common footprints like DIP-8 and others, as internal resources. These can
be accessed/searched by typing the keyword in the URL field of a part and choosing one of the choices from the dropdown. be accessed/searched by typing the keyword in the URL field of a part and choosing one of the choices from the dropdown.
### Preview image / attachment ### Preview image/attachment
Most entities with attachments allow you to select one of the defined attachments as "Preview image". You can select an Most entities with attachments allow you to select one of the defined attachments as "Preview image". You can select an
image attachment here, that previews the entity, this could be a picture of a Part, the logo of a manufacturer or image attachment here, that previews the entity, this could be a picture of a Part, the logo of a manufacturer or
supplier, the schematic symbol of a category or the image of a footprint. supplier, the schematic symbol of a category or the image of a footprint.
The preview image will be shown in various locations together with the entities name. The preview image will be shown in various locations together with the entity's name.
Please note that as long as the picture is not secret, it should be stored on the Part-DB instance (by upload, or Please note that as long as the picture is not secret, it should be stored on the Part-DB instance (by uploading, or
letting Part-DB download the file) and *not* be marked as a private attachments, so that thumbnails can be generated for letting Part-DB download the file) and *not* be marked as a private attachment, so that thumbnails can be generated for
the picture (which improves performance). the picture (which improves performance).
### Attachment types ### Attachment types
Attachment types define logical groups of attachments. For example, you could define an attachment group "Datasheets" Attachment types define logical groups of attachments. For example, you could define an attachment group "Datasheets"
where all datasheets of Parts, Footprints, etc. belong in, "Pictures" for preview images and more. where all datasheets of Parts, Footprints, etc. belong in, "Pictures" for preview images and more.
You can define file type restrictions, which file types and extensions are allowed for files with that attachment type. You can define file type restrictions, and which file types and extensions are allowed for files with that attachment type.
## User System ## User System
### User ### User
Each person which should be able to use Part-DB (by logging in) is represented by a user entity, which defines things Each person who should be able to use Part-DB (by logging in) is represented by a user entity, which defines things
like access rights, the password, and other things. For security reasons, every person which will use Part-DB should use like access rights, the password, and other things. For security reasons, every person who will use Part-DB should use
its own personal account with a secret password. This allows to track activity of the users via the log. their own personal account with a secret password. This allows to track activity of the users via the log.
There is a special user called `anonymous`, whose access rights are used to determine what a non-logged in user can do. There is a special user called `anonymous`, whose access rights are used to determine what a non-logged-in user can do.
Normally the anonymous user should be the most restricted user. Normally the anonymous user should be the most restricted user.
For simplification of access management users can be assigned to groups. For simplification of access management users can be assigned to groups.
### Group ### Group
A group is entity, to which users can be assigned to. This can be used to logically group users by for example A group is an entity, to which users can be assigned to. This can be used to logically group users by for example
organisational structures and to simplify permissions management, as you can define groups with access rights for common organizational structures and to simplify permissions management, as you can define groups with access rights for common
use cases and then just assign users to them, without the need to change every permission on the users individually. use cases and then just assign users to them, without the need to change every permission on the users individually.
## Labels ## Labels
@ -231,9 +231,9 @@ use cases and then just assign users to them, without the need to change every p
### Label profiles ### Label profiles
A label profile represents a template for a label (for a storage location, a part or part lot). It consists of a size, a A label profile represents a template for a label (for a storage location, a part or part lot). It consists of a size, a
barcode type and the content. There are various placeholders which can be inserted in the text content and which will be barcode type and the content. There are various placeholders that can be inserted in the text content and which will be
used replaced with data for the actual thing. replaced with data for the actual thing.
You do not have to define a label profile to generate labels (you can just set the settings on the fly in the label You do not have to define a label profile to generate labels (you can just set the settings on the fly in the label
dialog), however if you want to generate many labels, it is recommended to save the settings as label profile, to save dialog), however, if you want to generate many labels, it is recommended to save the settings as a label profile, to save
it for later usage. This ensures that all generated labels look the same. it for later usage. This ensures that all generated labels look the same.

71
docs/configuration.md
View file

@ -6,21 +6,21 @@ nav_order: 5
# Configuration # Configuration
Part-DBs behavior can be configured to your needs. There are different kind of configuration options: Options which are Part-DBs behavior can be configured to your needs. There are different kinds of configuration options: Options, which are
user changeable (changeable dynamically via frontend), options which can be configured by environment variables, and user-changeable (changeable dynamically via frontend), options that can be configured by environment variables, and
options which are only configurable via symfony config files. options that are only configurable via Symfony config files.
## User changeable ## User changeable
Following things can be changed for every user and a user can change it for himself (if he has the correct permission The following things can be changed for every user and a user can change it for himself (if he has the correct permission
for it). Configuration is either possible via the users own setting page (where you can also change the password) or via for it). Configuration is either possible via the user's own settings page (where you can also change the password) or via
the user admin page: the user admin page:
* **Language**: The language that the users prefers, and which will be used when no language is explicitly specified. * **Language**: The language that the users prefer, and which will be used when no language is explicitly specified.
Language can still always be changed via the language selector. By default, the global configured language is used. Language can still always be changed via the language selector. By default, the globally configured language is used.
* **Timezone**: The timezone which the user resides in and in which all dates and times should be shown. By default, the * **Timezone**: The timezone in which the user resides and in which all dates and times should be shown. By default, the
globally configured language. globally configured language.
* **Theme**: The theme to use for the frontend. Allows the user to choose the frontend design, he prefers. * **Theme**: The theme to use for the front end. Allows the user to choose the front end design, he prefers.
* **Preferred currency**: One of the defined currencies, in which all prices should be shown, if possible. Prices with * **Preferred currency**: One of the defined currencies, in which all prices should be shown, if possible. Prices with
other currencies will be converted to the price selected here other currencies will be converted to the price selected here
@ -28,19 +28,19 @@ the user admin page:
The following configuration options can only be changed by the server administrator, by either changing the server The following configuration options can only be changed by the server administrator, by either changing the server
variables, changing the `.env.local` file or setting env for your docker container. Here are just the most important variables, changing the `.env.local` file or setting env for your docker container. Here are just the most important
options listed, see `.env` file for full list of possible env variables. options listed, see `.env` file for the full list of possible env variables.
### General options ### General options
* `DATABASE_URL`: Configures the database which Part-DB uses. For mysql use a string in the form * `DATABASE_URL`: Configures the database which Part-DB uses. For mysql use a string in the form
of `mysql://<USERNAME>:<PASSWORD>@<HOST>:<PORT>/<TABLE_NAME>` here of `mysql://<USERNAME>:<PASSWORD>@<HOST>:<PORT>/<TABLE_NAME>` here
(e.g. `DATABASE_URL=mysql://user:password@127.0.0.1:3306/part-db`). For sqlite use the following format to specify the (e.g. `DATABASE_URL=mysql://user:password@127.0.0.1:3306/part-db`). For SQLite use the following format to specify the
absolute path where it should be located `sqlite:///path/part/app.db`. You can use `%kernel.project_dir%` as absolute path where it should be located `sqlite:///path/part/app.db`. You can use `%kernel.project_dir%` as
placeholder for the Part-DB root folder (e.g. `sqlite:///%kernel.project_dir%/var/app.db`) placeholder for the Part-DB root folder (e.g. `sqlite:///%kernel.project_dir%/var/app.db`)
* `DATABASE_MYSQL_USE_SSL_CA`: If this value is set to `1` or `true` and a MySQL connection is used, then the connection * `DATABASE_MYSQL_USE_SSL_CA`: If this value is set to `1` or `true` and a MySQL connection is used, then the connection
is encrypted by SSL/TLS and the server certificate is verified against the system CA certificates or the CA certificate is encrypted by SSL/TLS and the server certificate is verified against the system CA certificates or the CA certificate
bundled with Part-DB. Set `DATABASE_MYSQL_SSL_VERIFY_CERT` if you want to accept all certificates. bundled with Part-DB. Set `DATABASE_MYSQL_SSL_VERIFY_CERT` if you want to accept all certificates.
* `DEFAULT_LANG`: The default language to use server wide (when no language is explicitly specified by a user or via * `DEFAULT_LANG`: The default language to use server-wide (when no language is explicitly specified by a user or via
language chooser). Must be something like `en`, `de`, `fr`, etc. language chooser). Must be something like `en`, `de`, `fr`, etc.
* `DEFAULT_TIMEZONE`: The default timezone to use globally, when a user has no timezone specified. Must be something * `DEFAULT_TIMEZONE`: The default timezone to use globally, when a user has no timezone specified. Must be something
like `Europe/Berlin`. See [here](https://en.wikipedia.org/wiki/List_of_tz_database_time_zones) under TZ Database name like `Europe/Berlin`. See [here](https://en.wikipedia.org/wiki/List_of_tz_database_time_zones) under TZ Database name
@ -53,7 +53,7 @@ bundled with Part-DB. Set `DATABASE_MYSQL_SSL_VERIFY_CERT` if you want to accept
* `INSTANCE_NAME`: The name of your installation. It will be shown as a title in the navbar and other places. By * `INSTANCE_NAME`: The name of your installation. It will be shown as a title in the navbar and other places. By
default `Part-DB`, but you can customize it to something likes `ExampleCorp. Inventory`. default `Part-DB`, but you can customize it to something likes `ExampleCorp. Inventory`.
* `ALLOW_ATTACHMENT_DOWNLOADS` (allowed values `0` or `1`): By setting this option to 1, users can make Part-DB directly * `ALLOW_ATTACHMENT_DOWNLOADS` (allowed values `0` or `1`): By setting this option to 1, users can make Part-DB directly
download a file specified as a URL and create it as local file. Please note that this allows users access to all download a file specified as a URL and create it as a local file. Please note that this allows users access to all
resources publicly available to the server (so full access to other servers in the same local network), which could resources publicly available to the server (so full access to other servers in the same local network), which could
be a security risk. be a security risk.
* `ATTACHMENT_DOWNLOAD_BY_DEFAULT`: When this is set to 1, the "download external file" checkbox is checked by default * `ATTACHMENT_DOWNLOAD_BY_DEFAULT`: When this is set to 1, the "download external file" checkbox is checked by default
@ -63,7 +63,7 @@ bundled with Part-DB. Set `DATABASE_MYSQL_SSL_VERIFY_CERT` if you want to accept
not set their own picture). The users browsers have to download the pictures from a third-party (gravatar) server, so not set their own picture). The users browsers have to download the pictures from a third-party (gravatar) server, so
this might be a privacy risk. this might be a privacy risk.
* `MAX_ATTACHMENT_FILE_SIZE`: The maximum file size (in bytes) for attachments. You can use the suffix `K`, `M` or `G` * `MAX_ATTACHMENT_FILE_SIZE`: The maximum file size (in bytes) for attachments. You can use the suffix `K`, `M` or `G`
to specify the size in kilobytes, megabytes or gigabytes. By default `100M` (100 megabytes). Please note that this to specify the size in kilobytes, megabytes or gigabytes. By default `100M` (100 megabytes). Please note that this is
only the limit of Part-DB. You still need to configure the php.ini `upload_max_filesize` and `post_max_size` to allow only the limit of Part-DB. You still need to configure the php.ini `upload_max_filesize` and `post_max_size` to allow
bigger files to be uploaded. bigger files to be uploaded.
* `DEFAULT_URI`: The default URI base to use for the Part-DB, when no URL can be determined from the browser request. * `DEFAULT_URI`: The default URI base to use for the Part-DB, when no URL can be determined from the browser request.
@ -71,8 +71,8 @@ bundled with Part-DB. Set `DATABASE_MYSQL_SSL_VERIFY_CERT` if you want to accept
emails and other places, where the URL is needed. It is also used, when SAML is enabled.s If you are using a reverse emails and other places, where the URL is needed. It is also used, when SAML is enabled.s If you are using a reverse
proxy, you should set this to the URL of the reverse proxy (e.g. `https://part-db.example.com`). **This value must end proxy, you should set this to the URL of the reverse proxy (e.g. `https://part-db.example.com`). **This value must end
with a slash**. with a slash**.
* `ENFORCE_CHANGE_COMMENTS_FOR`: With this option you can configure, where users are enforced to give a change reason, * `ENFORCE_CHANGE_COMMENTS_FOR`: With this option, you can configure, where users are enforced to give a change reason,
which will be written to the log. This is a comma separated list of values (e.g. `part_edit,part_delete`). Leave empty which will be written to the log. This is a comma-separated list of values (e.g. `part_edit,part_delete`). Leave empty
to make change comments optional everywhere. Possible values are: to make change comments optional everywhere. Possible values are:
* `part_edit`: Edit operation of an existing part * `part_edit`: Edit operation of an existing part
* `part_delete`: Delete operation of an existing part * `part_delete`: Delete operation of an existing part
@ -91,10 +91,10 @@ bundled with Part-DB. Set `DATABASE_MYSQL_SSL_VERIFY_CERT` if you want to accept
mail account, you can use the following syntax `MAILER_DSN=smtp://user:password@smtp.mailserver.invalid:587` mail account, you can use the following syntax `MAILER_DSN=smtp://user:password@smtp.mailserver.invalid:587`
* `EMAIL_SENDER_EMAIL`: The email address from which emails should be sent from (in most cases this has to be the same * `EMAIL_SENDER_EMAIL`: The email address from which emails should be sent from (in most cases this has to be the same
as the email address used for SMTP access) as the email address used for SMTP access)
* `EMAIL_SENDER_NAME`: Similar to `EMAIL_SENDER_EMAIL` but this allows you to specify the name from which the mails are * `EMAIL_SENDER_NAME`: Similar to `EMAIL_SENDER_EMAIL`, but this allows you to specify the name from which the mails are
sent from. sent from.
* `ALLOW_EMAIL_PW_RESET`: Set this value to true, if you want to allow users to reset their password via an email * `ALLOW_EMAIL_PW_RESET`: Set this value to true, if you want to allow users to reset their password via an email
notification. You have to configure the mailprovider first before via the MAILER_DSN setting. notification. You have to configure the mail provider first before via the MAILER_DSN setting.
### Table related settings ### Table related settings
@ -105,15 +105,15 @@ bundled with Part-DB. Set `DATABASE_MYSQL_SSL_VERIFY_CERT` if you want to accept
Also specify the default order of the columns. This is a comma separated list of column names. Available columns Also specify the default order of the columns. This is a comma separated list of column names. Available columns
are: `name`, `id`, `ipn`, `description`, `category`, `footprint`, `manufacturer`, `storage_location`, `amount`, `minamount`, `partUnit`, `addedDate`, `lastModified`, `needs_review`, `favorite`, `manufacturing_status`, `manufacturer_product_number`, `mass`, `tags`, `attachments`, `edit`. are: `name`, `id`, `ipn`, `description`, `category`, `footprint`, `manufacturer`, `storage_location`, `amount`, `minamount`, `partUnit`, `addedDate`, `lastModified`, `needs_review`, `favorite`, `manufacturing_status`, `manufacturer_product_number`, `mass`, `tags`, `attachments`, `edit`.
### History/Eventlog related settings ### History/Eventlog-related settings
The following options are used to configure, which (and how much) data is written to the system log: The following options are used to configure, which (and how much) data is written to the system log:
* `HISTORY_SAVE_CHANGED_FIELDS`: When this option is set to true, the name of the fields which are changed, are saved to * `HISTORY_SAVE_CHANGED_FIELDS`: When this option is set to true, the name of the fields that are changed, are saved to
the DB (so for example it is logged that a user has changed, that the user has changed the name and description of the the DB (so for example it is logged that a user has changed, that the user has changed the name and description of the
field, but not the data/content of these changes) field, but not the data/content of these changes)
* `HISTORY_SAVE_CHANGED_DATA`: When this option is set to true, the changed data is saved to log (so it is logged, that * `HISTORY_SAVE_CHANGED_DATA`: When this option is set to true, the changed data is saved to log (so it is logged, that
a user has changed the name of a part and what the name was before). This can increase database size, when you have a a user has changed the name of a part and what the name was before). This can increase database size when you have a
lot of changes to entities. lot of changes to entities.
* `HISTORY_SAVE_REMOVED_DATA`: When this option is set to true, removed data is saved to log, meaning that you can * `HISTORY_SAVE_REMOVED_DATA`: When this option is set to true, removed data is saved to log, meaning that you can
easily undelete an entity, when it was removed accidentally. easily undelete an entity, when it was removed accidentally.
@ -126,10 +126,10 @@ then `HISTORY_SAVE_CHANGED_FIELDS`, `HISTORY_SAVE_CHANGED_DATA` and `HISTORY_SAV
### Error pages settings ### Error pages settings
* `ERROR_PAGE_ADMIN_EMAIL`: You can set an email-address here, which is shown on the error page, who should be contacted * `ERROR_PAGE_ADMIN_EMAIL`: You can set an email address here, which is shown on the error page, who should be contacted
about the issue (e.g. an IT support email of your company) about the issue (e.g. an IT support email of your company)
* `ERROR_PAGE_SHOW_HELP`: Set this 0, to disable the solution hints shown on an error page. These hints should not * `ERROR_PAGE_SHOW_HELP`: Set this 0, to disable the solution hints shown on an error page. These hints should not
contain sensitive information, but could confuse end-users. contain sensitive information but could confuse end-users.
### EDA related settings ### EDA related settings
@ -143,21 +143,21 @@ then `HISTORY_SAVE_CHANGED_FIELDS`, `HISTORY_SAVE_CHANGED_DATA` and `HISTORY_SAV
The following settings can be used to enable and configure Single-Sign on via SAML. This allows users to log in to The following settings can be used to enable and configure Single-Sign on via SAML. This allows users to log in to
Part-DB without entering a username and password, but instead they are redirected to a SAML Identity Provider (IdP) and Part-DB without entering a username and password, but instead they are redirected to a SAML Identity Provider (IdP) and
are logged in automatically. This is especially useful, when you want to use Part-DB in a company, where all users have are logged in automatically. This is especially useful when you want to use Part-DB in a company, where all users have
a SAML account (e.g. via Active Directory or LDAP). a SAML account (e.g. via Active Directory or LDAP).
You can find more advanced settings in the `config/packages/hslavich_onelogin_saml.yaml` file. Please note that this You can find more advanced settings in the `config/packages/hslavich_onelogin_saml.yaml` file. Please note that this
file is not backed up by the backup script, so you have to back up it manually, if you want to keep your changes. If you file is not backed up by the backup script, so you have to back up it manually, if you want to keep your changes. If you
want to edit it on docker, you have to map the file to a volume. want to edit it on docker, you have to map the file to a volume.
* `SAML_ENABLED`: When this is set to 1, SAML SSO is enabled and the SSO Login button is shown in the login form. You * `SAML_ENABLED`: When this is set to 1, SAML SSO is enabled and the SSO Login button is shown in the login form. You
have to configure the SAML settings below, before you can use this feature. have to configure the SAML settings below before you can use this feature.
* `SAML_BEHIND_PROXY`: Set this to 1, if Part-DB is behind a reverse proxy. See [here]({% link installation/reverse-proxy.md %}) * `SAML_BEHIND_PROXY`: Set this to 1, if Part-DB is behind a reverse proxy. See [here]({% link installation/reverse-proxy.md %})
for more information. Otherwise, leave it to 0 (default.) for more information. Otherwise, leave it to 0 (default.)
* `SAML_ROLE_MAPPING`: A [JSON](https://en.wikipedia.org/wiki/JSON) encoded map which specifies how Part-DB should * `SAML_ROLE_MAPPING`: A [JSON](https://en.wikipedia.org/wiki/JSON)-encoded map which specifies how Part-DB should
convert the user roles given by SAML attribute `group` should be converted to a Part-DB group (specified by ID). You convert the user roles given by SAML attribute `group` should be converted to a Part-DB group (specified by ID). You
can use a wildcard `*` to map all otherwise unmapped roles to a certain group. can use a wildcard `*` to map all otherwise unmapped roles to a certain group.
Example: `{"*": 1, "admin": 2, "editor": 3}`. This would map all roles to the group with ID 1, except the Example: `{"*": 1, "admin": 2, "editor": 3}`. This would map all roles to the group with ID 1, except the
role `admin`, which is mapped to the group with ID 2 and the role `editor`, which is mapped to the group with ID 3. role `admin`, which is mapped to the group with ID 2, and the role `editor`, which is mapped to the group with ID 3.
* `SAML_UPDATE_GROUP_ON_LOGIN`: When this is enabled the group of the user is updated on every login of the user based * `SAML_UPDATE_GROUP_ON_LOGIN`: When this is enabled the group of the user is updated on every login of the user based
on the SAML role attributes. When this is disabled, the group is only assigned on the first login of the user, and a on the SAML role attributes. When this is disabled, the group is only assigned on the first login of the user, and a
Part-DB administrator can change the group afterward by editing the user. Part-DB administrator can change the group afterward by editing the user.
@ -185,27 +185,27 @@ want to edit it on docker, you have to map the file to a volume.
The settings prefixes with `PROVIDER_*` are used to configure the information providers. The settings prefixes with `PROVIDER_*` are used to configure the information providers.
See the [information providers]({% link usage/information_provider_system.md %}) page for more information. See the [information providers]({% link usage/information_provider_system.md %}) page for more information.
### Other / less used options ### Other / less-used options
* `TRUSTED_PROXIES`: Set the IP addresses (or IP blocks) of trusted reverse proxies here. This is needed to get correct * `TRUSTED_PROXIES`: Set the IP addresses (or IP blocks) of trusted reverse proxies here. This is needed to get correct
IP information (see [here](https://symfony.com/doc/current/deployment/proxies.html) for more info). IP information (see [here](https://symfony.com/doc/current/deployment/proxies.html) for more info).
* `TRUSTED_HOSTS`: To prevent `HTTP Host header attacks` you can set a regex containing all host names via which Part-DB * `TRUSTED_HOSTS`: To prevent `HTTP Host header attacks` you can set a regex containing all host names via which Part-DB
should be accessible. If accessed via the wrong hostname, an error will be shown. should be accessible. If accessed via the wrong hostname, an error will be shown.
* `DEMO_MODE`: Set Part-DB into demo mode, which forbids users to change their passwords and settings. Used for the demo * `DEMO_MODE`: Set Part-DB into demo mode, which forbids users to change their passwords and settings. Used for the demo
instance, should not be needed for normal installations. instance. This should not be needed for normal installations.
* `NO_URL_REWRITE_AVAILABLE` (allowed values `true` or `false`): Set this value to true, if your webserver does not * `NO_URL_REWRITE_AVAILABLE` (allowed values `true` or `false`): Set this value to true, if your webserver does not
support rewrite. In this case, all URL paths will contain index.php/, which is needed then. Normally this setting do support rewrite. In this case, all URL paths will contain index.php/, which is needed then. Normally this setting does
not need to be changed. not need to be changed.
* `REDIRECT_TO_HTTPS`: If this is set to true, all requests to http will be redirected to https. This is useful, if your * `REDIRECT_TO_HTTPS`: If this is set to true, all requests to http will be redirected to https. This is useful if your
webserver does not already do this (like the one used in the demo instance). If your webserver already redirects to web server does not already do this (like the one used in the demo instance). If your web server already redirects to
https, you don't need to set this. Ensure that Part-DB is accessible via https, before you enable this setting. https, you don't need to set this. Ensure that Part-DB is accessible via HTTPS before you enable this setting.
* `FIXER_API_KEY`: If you want to automatically retrieve exchange rates for base currencies other than euros, you have to * `FIXER_API_KEY`: If you want to automatically retrieve exchange rates for base currencies other than euros, you have to
configure an exchange rate provider API. [Fixer.io](https://fixer.io/) is preconfigured, and you just have to register configure an exchange rate provider API. [Fixer.io](https://fixer.io/) is preconfigured, and you just have to register
there and set the retrieved API key in this environment variable. there and set the retrieved API key in this environment variable.
* `APP_ENV`: This value should always be set to `prod` in normal use. Set it to `dev` to enable debug/development * `APP_ENV`: This value should always be set to `prod` in normal use. Set it to `dev` to enable debug/development
mode. (**You should not do this on a publicly accessible server, as it will leak sensitive information!**) mode. (**You should not do this on a publicly accessible server, as it will leak sensitive information!**)
* `BANNER`: You can configure the text that should be shown as the banner on the homepage. Useful especially for docker * `BANNER`: You can configure the text that should be shown as the banner on the homepage. Useful especially for docker
container. In all other applications you can just change the `config/banner.md` file. containers. In all other applications you can just change the `config/banner.md` file.
## Banner ## Banner
@ -218,8 +218,7 @@ markdown (and even some subset of HTML) syntax to format the text.
You can also configure some options via the `config/parameters.yaml` file. This should normally not need, You can also configure some options via the `config/parameters.yaml` file. This should normally not need,
and you should know what you are doing, when you change something here. You should expect, that you will have to do some and you should know what you are doing, when you change something here. You should expect, that you will have to do some
manual merge, when you have changed something here and update to a newer version of Part-DB. It is possible that manual merge, when you have changed something here and update to a newer version of Part-DB. It is possible that
configuration configuration options here will change or be completely removed in future versions of Part-DB.
options here will change or completely removed in future versions of Part-DB.
If you change something here, you have to clear the cache, before the changes will take effect with the If you change something here, you have to clear the cache, before the changes will take effect with the
command `bin/console cache:clear`. command `bin/console cache:clear`.

6
docs/index.md
View file

@ -25,10 +25,10 @@ It is installed on a web server and so can be accessed with any browser without
## Features ## Features
* Inventory management of your electronic parts. Each part can be assigned to a category, footprint, manufacturer * Inventory management of your electronic parts. Each part can be assigned to a category, footprint, manufacturer,
and multiple store locations and price information. Parts can be grouped using tags. You can associate various files and multiple store locations and price information. Parts can be grouped using tags. You can associate various files
like datasheets or pictures with the parts. like datasheets or pictures with the parts.
* Multi-Language support (currently German, English, Russian, Japanese and French (experimental)) * Multi-language support (currently German, English, Russian, Japanese and French (experimental))
* Barcodes/Labels generator for parts and storage locations, scan barcodes via webcam using the builtin barcode scanner * Barcodes/Labels generator for parts and storage locations, scan barcodes via webcam using the builtin barcode scanner
* User system with groups and detailed (fine granular) permissions. * User system with groups and detailed (fine granular) permissions.
Two-factor authentication is supported (Google Authenticator and Webauthn/U2F keys) and can be enforced for groups. Two-factor authentication is supported (Google Authenticator and Webauthn/U2F keys) and can be enforced for groups.
@ -46,7 +46,7 @@ It is installed on a web server and so can be accessed with any browser without
* Support for multiple currencies and automatic update of exchange rates supported * Support for multiple currencies and automatic update of exchange rates supported
* Powerful search and filter function, including parametric search (search for parts according to some specifications) * Powerful search and filter function, including parametric search (search for parts according to some specifications)
* Easy migration from an existing PartKeepr instance (see [here]({%link partkeepr_migration.md %})) * Easy migration from an existing PartKeepr instance (see [here]({%link partkeepr_migration.md %}))
* Use cloud providers (like Octopart, Digikey, farnell or TME) to automatically get part information, datasheets and * Use cloud providers (like Octopart, Digikey, Farnell or TME) to automatically get part information, datasheets and
prices for parts (see [here]({% link usage/information_provider_system.md %})) prices for parts (see [here]({% link usage/information_provider_system.md %}))
* API to access Part-DB from other applications/scripts * API to access Part-DB from other applications/scripts
* [Integration with KiCad]({%link usage/eda_integration.md %}): Use Part-DB as central datasource for your * [Integration with KiCad]({%link usage/eda_integration.md %}): Use Part-DB as central datasource for your

26
docs/partkeepr_migration.md
View file

@ -12,34 +12,34 @@ nav_order: 101
This guide describes how to migrate from [PartKeepr](https://partkeepr.org/) to Part-DB. This guide describes how to migrate from [PartKeepr](https://partkeepr.org/) to Part-DB.
Part-DB has a built-in migration tool, which can be used to migrate the data from an existing PartKeepr instance to Part-DB has a built-in migration tool, which can be used to migrate the data from an existing PartKeepr instance to
a new Part-DB instance. Most of the data can be migrated, however there are some limitations, you can find below. a new Part-DB instance. Most of the data can be migrated, however, there are some limitations, that you can find below.
## What can be imported ## What can be imported
* Datastructures (Categories, Footprints, Storage Locations, Manufacturers, Distributors, Part Measurement Units) * Data structures (Categories, Footprints, Storage Locations, Manufacturers, Distributors, Part Measurement Units)
* Basic part information's (Name, Description, Comment, etc.) * Basic part information (Name, Description, Comment, etc.)
* Attachments and images of parts, projects, footprints, manufacturers and storage locations * Attachments and images of parts, projects, footprints, manufacturers, and storage locations
* Part prices (distributor infos) * Part prices (distributor infos)
* Part parameters * Part parameters
* Projects (including parts and attachments) * Projects (including parts and attachments)
* Users (optional): Passwords however will be not migrated, and need to be reset later * Users (optional): Passwords however will not be migrated, and need to be reset later
## What can't be imported ## What can't be imported
* Metaparts (A dummy version of the metapart will be created in Part-DB, however it will not function as metapart) * Metaparts (A dummy version of the metapart will be created in Part-DB, however, it will not function as metapart)
* Multiple manufacturers per part (only the last manufacturer of a part will be migrated) * Multiple manufacturers per part (only the last manufacturer of a part will be migrated)
* Overage information for project parts (the overage info will be set as comment in the project BOM, but will have no * Overage information for project parts (the overage info will be set as a comment in the project BOM, but will have no
effect) effect)
* Batch Jobs * Batch Jobs
* Parameter Units (the units will be written into the parameters) * Parameter Units (the units will be written into the parameters)
* Project Reports and Project Runs * Project Reports and Project Runs
* Stock history * Stock History
* Any kind of PartKeepr preferences * Any kind of PartKeepr preferences
## How to migrate ## How to migrate
1. Install Part-DB like described in the installation guide. You can use any database backend you want (mysql or 1. Install Part-DB as described in the installation guide. You can use any database backend you want (MySQL or
sqlite). Run the database migration, but do not create any new data yet. SQLite). Run the database migration, but do not create any new data yet.
2. Export your PartKeepr database as XML file using [mysqldump](https://dev.mysql.com/doc/refman/8.0/en/mysqldump.html): 2. Export your PartKeepr database as XML file using [mysqldump](https://dev.mysql.com/doc/refman/8.0/en/mysqldump.html):
When the MySQL database is running on the local computer, and you are root you can just run the When the MySQL database is running on the local computer, and you are root you can just run the
command `mysqldump --xml PARTKEEPR_DATABASE --result-file pk.xml`. command `mysqldump --xml PARTKEEPR_DATABASE --result-file pk.xml`.
@ -47,7 +47,7 @@ a new Part-DB instance. Most of the data can be migrated, however there are some
run `mysqldump --xml -h PARTKEEPR_HOST -u PARTKEEPR_USER -p PARTKEEPR_DATABASE`, where you replace `PARTKEEPR_HOST` run `mysqldump --xml -h PARTKEEPR_HOST -u PARTKEEPR_USER -p PARTKEEPR_DATABASE`, where you replace `PARTKEEPR_HOST`
with the hostname of your MySQL database and `PARTKEEPR_USER` with the username of MySQL user which has access to the with the hostname of your MySQL database and `PARTKEEPR_USER` with the username of MySQL user which has access to the
PartKeepr database. You will be asked for the MySQL user password. PartKeepr database. You will be asked for the MySQL user password.
3. Go the Part-DB main folder and run the command `php bin/console partdb:migrations:import-partkeepr path/to/pk.xml`. 3. Go to the Part-DB main folder and run the command `php bin/console partdb:migrations:import-partkeepr path/to/pk.xml`.
This step will delete all existing data in the Part-DB database and import the contents of PartKeepr. This step will delete all existing data in the Part-DB database and import the contents of PartKeepr.
4. Copy the contents of `data/files/` from your PartKeepr installation to the `uploads/` folder of your Part-DB 4. Copy the contents of `data/files/` from your PartKeepr installation to the `uploads/` folder of your Part-DB
installation and the contents of `data/images` from PartKeepr to `public/media/` of Part-DB. installation and the contents of `data/images` from PartKeepr to `public/media/` of Part-DB.
@ -63,5 +63,5 @@ option on the database import command (step 3):
All imported users of PartKeepr will be assigned to a new group "PartKeepr Users", which has normal user permissions (so All imported users of PartKeepr will be assigned to a new group "PartKeepr Users", which has normal user permissions (so
editing data, but no administrative tasks). You can change the group and permissions later in Part-DB users management. editing data, but no administrative tasks). You can change the group and permissions later in Part-DB users management.
Passwords can not be imported from PartKeepr and all imported users get marked as disabled user. So to allow users to Passwords can not be imported from PartKeepr and all imported users get marked as disabled. So to allow users to
login, you need to enable them in the user management and assign a password. log in, you need to enable them in the user management and assign a password.

4
docs/troubleshooting.md
View file

@ -16,7 +16,7 @@ on how to fix the problem. If you have a problem that is not listed here, please
If you encounter an error, try the following steps: If you encounter an error, try the following steps:
* Clear cache of Part-DB with the console command: * Clear the cache of Part-DB with the console command:
```bash ```bash
php bin/console cache:clear php bin/console cache:clear
@ -30,7 +30,7 @@ php bin/console doctrine:migrations:migrate
If this does not help, please [open an issue on GitHub](https://github.com/Part-DB/Part-DB-symfony). If this does not help, please [open an issue on GitHub](https://github.com/Part-DB/Part-DB-symfony).
## Search for user and reset password: ## Search for the user and reset the password:
You can list all users with the following command: `php bin/console partdb:users:list` You can list all users with the following command: `php bin/console partdb:users:list`
To reset the password of a user you can use the following To reset the password of a user you can use the following

31
docs/upgrade_legacy.md
View file

@ -18,33 +18,32 @@ sections carefully before proceeding to upgrade.
* PHP 8.1 or higher is required now (Part-DB 0.5 required PHP 5.4+, Part-DB 0.6 PHP 7.0). * PHP 8.1 or higher is required now (Part-DB 0.5 required PHP 5.4+, Part-DB 0.6 PHP 7.0).
Releases are available for Windows too, so almost everybody should be able to use PHP 8.1 Releases are available for Windows too, so almost everybody should be able to use PHP 8.1
* **Console access highly required.** The installation of composer and frontend dependencies require console access, * **Console access is highly recommended.** The installation of composer and frontend dependencies require console access,
also more sensitive stuff like database migration work via CLI now, so you should have console access on your server. also more sensitive stuff like database migration works via CLI now, so you should have console access on your server.
* Markdown/HTML is now used instead of BBCode for rich text in description and command fields. * Markdown/HTML is now used instead of BBCode for rich text in description and command fields.
It is possible to migrate your existing BBCode to Markdown It is possible to migrate your existing BBCode to Markdown
via `php bin/console php bin/console partdb:migrations:convert-bbcode`. via `php bin/console php bin/console partdb:migrations:convert-bbcode`.
* Server exceptions are not logged to event log anymore. For security reasons (exceptions can contain sensitive * Server exceptions are not logged into event log anymore. For security reasons (exceptions can contain sensitive
information) information) exceptions are only logged to server log (by default under './var/log'), so only the server admins can access it.
exceptions are only logged to server log (by default under './var/log'), so only the server admins can access it. * Profile labels are now saved in the database (before they were saved in a separate JSON file). **The profiles of legacy
* Profile labels are now saved in Database (before they were saved in a separate JSON file). **The profiles of legacy
Part-DB versions can not be imported into new Part-DB 1.0** Part-DB versions can not be imported into new Part-DB 1.0**
* Label placeholders now use the `[[PLACEHOLDER]]` format instead of `%PLACEHOLDER%`. Also, some placeholders has * Label placeholders now use the `[[PLACEHOLDER]]` format instead of `%PLACEHOLDER%`. Also, some placeholders have
changed. changed.
* Configuration is now done via configuration files / environment variables instead of the WebUI (this maybe change in * Configuration is now done via configuration files/environment variables instead of the WebUI (this may change in
the future). the future).
* Database updated are now done via console instead of the WebUI * Database updates are now done via console instead of the WebUI
* Permission system changed: **You will have to newly set the permissions of all users and groups!** * Permission system changed: **You will have to newly set the permissions of all users and groups!**
* Import / Export file format changed. Fields must be english now (unlike in legacy Part-DB versions, where german * Import / Export file format changed. Fields must be English now (unlike in legacy Part-DB versions, where German
fields in CSV were possible) fields in CSV were possible)
and you maybe have to change the header line/field names of your CSV files. and you may have to change the header line/field names of your CSV files.
## Missing features ## Missing features
* No possibility to mark parts for ordering (yet) * No possibility of marking parts for ordering (yet)
* No support for 3D models of footprints (yet) * No support for 3D models of footprints (yet)
* No possibility to disable footprints, manufacturers globally (or per category). This should not have a big impact, * No possibility to disable footprints, manufacturers globally (or per category). This should not have a big impact
when you forbid users to edit/create them. when you forbid users to edit/create them.
* No resistor calculator or SMD labels tools * No resistor calculator or SMD label tools
## Upgrade process ## Upgrade process
@ -56,12 +55,12 @@ sections carefully before proceeding to upgrade.
> Beware that all user and group permissions will be reset, and you have to set the permissions again > Beware that all user and group permissions will be reset, and you have to set the permissions again
> the new Part-DB as many permissions changed, and automatic migration is not possible. > the new Part-DB as many permissions changed, and automatic migration is not possible.
1. Upgrade your existing Part-DB version the newest Part-DB 0.5.* version (at the moment Part-DB 0.5.8), like described 1. Upgrade your existing Part-DB version the newest Part-DB 0.5.* version (at the moment Part-DB 0.5.8), as described
in the old Part-DB's repository. in the old Part-DB's repository.
2. Make a backup of your database and attachments. If something goes wrong during migration, you can use this backup to 2. Make a backup of your database and attachments. If something goes wrong during migration, you can use this backup to
start over. If you have some more complex permission configuration, you maybe want to do screenshots of it, so you start over. If you have some more complex permission configuration, you maybe want to do screenshots of it, so you
can redo it again later. can redo it again later.
3. Set up the new Part-DB like described in installation section. You will need to do the setup for a MySQL instance ( 3. Set up the new Part-DB as described in the installation section. You will need to do the setup for a MySQL instance (
either via docker or direct installation). Set the `DATABASE_URL` environment variable in your `.env.local` ( either via docker or direct installation). Set the `DATABASE_URL` environment variable in your `.env.local` (
or `docker-compose.yaml`) to your existing database. ( or `docker-compose.yaml`) to your existing database. (
e.g. `DATABASE_URL=mysql://PARTDB_USER:PASSWORD@localhost:3306/DATABASE_NAME`) e.g. `DATABASE_URL=mysql://PARTDB_USER:PASSWORD@localhost:3306/DATABASE_NAME`)

39
docs/usage/information_provider_system.md
View file

@ -6,11 +6,11 @@ parent: Usage
# Information provider system # Information provider system
Part-DB can create parts based on information from external sources: For example with the right setup you can just Part-DB can create parts based on information from external sources: For example, with the right setup you can just
search for a part number search for a part number
and Part-DB will query selected distributors and manufacturers for the part and create a part with the information it and Part-DB will query selected distributors and manufacturers for the part and create a part with the information it
found. found.
This way your Part-DB parts automatically get datasheet links, prices, parameters and more, with just a few clicks. This way your Part-DB parts automatically get datasheet links, prices, parameters, and more, with just a few clicks.
## Usage ## Usage
@ -45,13 +45,13 @@ part.
Part-DB tries to automatically find existing elements from your database for the information it got from the providers Part-DB tries to automatically find existing elements from your database for the information it got from the providers
for fields like manufacturer, footprint, etc. for fields like manufacturer, footprint, etc.
For this it searches for an element with the same name (case-insensitive) as the information it got from the provider. So For this, it searches for an element with the same name (case-insensitive) as the information it got from the provider. So
e.g. if the provider returns "EXAMPLE CORP" as manufacturer, e.g. if the provider returns "EXAMPLE CORP" as the manufacturer,
Part-DB will automatically select the element with the name "Example Corp" from your database. Part-DB will automatically select the element with the name "Example Corp" from your database.
As the names of these fields differ from provider to provider (and maybe not even normalized for the same provider), you As the names of these fields differ from provider to provider (and maybe not even normalized for the same provider), you
can define multiple alternative names for an element (on their editing page). can define multiple alternative names for an element (on their editing page).
For example if define a manufacturer "Example Corp" with the alternative names "Example Corp.", "Example Corp", "Example For example, if you define a manufacturer "Example Corp" with the alternative names "Example Corp.", "Example Corp", "Example
Corp. Inc." and "Example Corporation", Corp. Inc." and "Example Corporation",
then the provider can return any of these names and Part-DB will still automatically select the right element. then the provider can return any of these names and Part-DB will still automatically select the right element.
@ -72,12 +72,12 @@ add the alternative names "Datasheet" and "Image" to the alternative names field
The system tries to be as flexible as possible, so many different information sources can be used. The system tries to be as flexible as possible, so many different information sources can be used.
Each information source is called am "info provider" and handles the communication with the external source. Each information source is called am "info provider" and handles the communication with the external source.
The providers are just a driver which handles the communication with the different external sources and converts them The providers are just a driver that handles the communication with the different external sources and converts them
into a common format Part-DB understands. into a common format Part-DB understands.
That way it is pretty easy to create new providers as they just need to do very little work. That way it is pretty easy to create new providers as they just need to do very little work.
Normally the providers utilize an API of a service, and you need to create an account at the provider and get an API key. Normally the providers utilize an API of a service, and you need to create an account at the provider and get an API key.
Also, there are limits on how many requests you can do per day or months, depending on the provider and your contract Also, there are limits on how many requests you can do per day or month, depending on the provider and your contract
with them. with them.
The following providers are currently available and shipped with Part-DB: The following providers are currently available and shipped with Part-DB:
@ -86,8 +86,7 @@ The following providers are currently available and shipped with Part-DB:
### Octopart ### Octopart
The Octopart provider uses the [Octopart / Nexar API](https://nexar.com/api) to search for parts and getting The Octopart provider uses the [Octopart / Nexar API](https://nexar.com/api) to search for parts and get information.
information.
To use it you have to create an account at Nexar and create a new application on To use it you have to create an account at Nexar and create a new application on
the [Nexar Portal](https://portal.nexar.com/). the [Nexar Portal](https://portal.nexar.com/).
The name does not matter, but it is important that the application has access to the "Supply" scope. The name does not matter, but it is important that the application has access to the "Supply" scope.
@ -100,7 +99,7 @@ can see your current usage on the Nexar portal.
Part-DB caches the search results internally, so if you have searched for a part before, it will not count against your Part-DB caches the search results internally, so if you have searched for a part before, it will not count against your
monthly limit again, when you create it from the search results. monthly limit again, when you create it from the search results.
Following env configuration options are available: The following env configuration options are available:
* `PROVIDER_OCTOPART_CLIENT_ID`: The client ID you got from Nexar (mandatory) * `PROVIDER_OCTOPART_CLIENT_ID`: The client ID you got from Nexar (mandatory)
* `PROVIDER_OCTOPART_SECRET`: The client secret you got from Nexar (mandatory) * `PROVIDER_OCTOPART_SECRET`: The client secret you got from Nexar (mandatory)
@ -109,18 +108,18 @@ Following env configuration options are available:
Part-DB will save the prices in their native currency, and you can use Part-DB currency conversion feature to convert Part-DB will save the prices in their native currency, and you can use Part-DB currency conversion feature to convert
it to your preferred currency. it to your preferred currency.
* `PROVIDER_OCOTPART_COUNTRY`: The country you want to get prices in if available (optional, 2 letter ISO-code, * `PROVIDER_OCOTPART_COUNTRY`: The country you want to get prices in if available (optional, 2 letter ISO-code,
default: `DE`). To get correct prices, you have to set this and the currency setting to the correct value. default: `DE`). To get the correct prices, you have to set this and the currency setting to the correct value.
* `PROVIDER_OCTOPART_SEARCH_LIMIT`: The maximum number of results to return per search (optional, default: `10`). This * `PROVIDER_OCTOPART_SEARCH_LIMIT`: The maximum number of results to return per search (optional, default: `10`). This
affects how quickly your monthly limit is used up. affects how quickly your monthly limit is used up.
* `PROVIDER_OCTOPART_ONLY_AUTHORIZED_SELLERS`: If set to `true`, only offers * `PROVIDER_OCTOPART_ONLY_AUTHORIZED_SELLERS`: If set to `true`, only offers
from [authorized sellers](https://octopart.com/authorized) will be returned (optional, default: `false`). from [authorized sellers](https://octopart.com/authorized) will be returned (optional, default: `false`).
**Attention**: If you change the octopart clientID after you have already used the provider, you have to remove the **Attention**: If you change the Octopart clientID after you have already used the provider, you have to remove the
OAuth token in the Part-DB database. Remove the entry in the table `oauth_tokens` with the name `ip_octopart_oauth`. OAuth token in the Part-DB database. Remove the entry in the table `oauth_tokens` with the name `ip_octopart_oauth`.
### Digi-Key ### Digi-Key
The Digi-Key provider uses the [Digi-Key API](https://developer.digikey.com/) to search for parts and getting shopping The Digi-Key provider uses the [Digi-Key API](https://developer.digikey.com/) to search for parts and get shopping
information from [Digi-Key](https://www.digikey.com/). information from [Digi-Key](https://www.digikey.com/).
To use it you have to create an account at Digi-Key and get an API key on To use it you have to create an account at Digi-Key and get an API key on
the [Digi-Key API page](https://developer.digikey.com/). the [Digi-Key API page](https://developer.digikey.com/).
@ -128,7 +127,7 @@ You must create an organization there and create a "Production app". Most settin
grant access to the "Product Information" API. grant access to the "Product Information" API.
You will get a Client ID and a Client Secret, which you have to put in the Part-DB env configuration (see below). You will get a Client ID and a Client Secret, which you have to put in the Part-DB env configuration (see below).
Following env configuration options are available: The following env configuration options are available:
* `PROVIDER_DIGIKEY_CLIENT_ID`: The client ID you got from Digi-Key (mandatory) * `PROVIDER_DIGIKEY_CLIENT_ID`: The client ID you got from Digi-Key (mandatory)
* `PROVIDER_DIGIKEY_SECRET`: The client secret you got from Digi-Key (mandatory) * `PROVIDER_DIGIKEY_SECRET`: The client secret you got from Digi-Key (mandatory)
@ -138,7 +137,7 @@ Following env configuration options are available:
The Digi-Key provider needs an additional OAuth connection. To do this, go to the information provider The Digi-Key provider needs an additional OAuth connection. To do this, go to the information provider
list (`https://your-partdb-instance.tld/tools/info_providers/providers`), list (`https://your-partdb-instance.tld/tools/info_providers/providers`),
go the Digi-Key provider (in the disabled page) and click on the "Connect OAuth" button. You will be redirected to go to Digi-Key provider (in the disabled page), and click on the "Connect OAuth" button. You will be redirected to
Digi-Key, where you have to log in and grant access to the app. Digi-Key, where you have to log in and grant access to the app.
To do this your user needs the "Manage OAuth tokens" permission from the "System" section in the "System" tab. To do this your user needs the "Manage OAuth tokens" permission from the "System" section in the "System" tab.
The OAuth connection should only be needed once, but if you have any problems with the provider, just click the button The OAuth connection should only be needed once, but if you have any problems with the provider, just click the button
@ -146,13 +145,13 @@ again, to establish a new connection.
### TME ### TME
The TME provider use the API of [TME](https://www.tme.eu/) to search for parts and getting shopping information from The TME provider uses the API of [TME](https://www.tme.eu/) to search for parts and getting shopping information from
them. them.
To use it you have to create an account at TME and get an API key on the [TME API page](https://developers.tme.eu/en/). To use it you have to create an account at TME and get an API key on the [TME API page](https://developers.tme.eu/en/).
You have to generate a new anonymous key there and enter the key and secret in the Part-DB env configuration (see You have to generate a new anonymous key there and enter the key and secret in the Part-DB env configuration (see
below). below).
Following env configuration options are available: The following env configuration options are available:
* `PROVIDER_TME_KEY`: The API key you got from TME (mandatory) * `PROVIDER_TME_KEY`: The API key you got from TME (mandatory)
* `PROVIDER_TME_SECRET`: The API secret you got from TME (mandatory) * `PROVIDER_TME_SECRET`: The API secret you got from TME (mandatory)
@ -171,7 +170,7 @@ You have to create an account at Farnell and get an API key on the [Farnell API
Register a new application there (settings does not matter, as long as you select the "Product Search API") and you will Register a new application there (settings does not matter, as long as you select the "Product Search API") and you will
get an API key. get an API key.
Following env configuration options are available: The following env configuration options are available:
* `PROVIDER_ELEMENT14_KEY`: The API key you got from Farnell (mandatory) * `PROVIDER_ELEMENT14_KEY`: The API key you got from Farnell (mandatory)
* `PROVIDER_ELEMENT14_STORE_ID`: The store ID you want to use. This decides the language of results, currency and * `PROVIDER_ELEMENT14_STORE_ID`: The store ID you want to use. This decides the language of results, currency and
@ -185,11 +184,11 @@ information from [Mouser](https://www.mouser.com/).
You have to create an account at Mouser and register for an API key for the Search API on You have to create an account at Mouser and register for an API key for the Search API on
the [Mouser API page](https://www.mouser.de/api-home/). the [Mouser API page](https://www.mouser.de/api-home/).
You will receive an API token, which you have to put in the Part-DB env configuration (see below): You will receive an API token, which you have to put in the Part-DB env configuration (see below):
At the registration you choose a country, language and currency in which you want to get the results. At the registration you choose a country, language, and currency in which you want to get the results.
*Attention*: Currently (January 2024) the mouser API seems to be somewhat broken, in the way that it does not return any *Attention*: Currently (January 2024) the mouser API seems to be somewhat broken, in the way that it does not return any
information about datasheets and part specifications. Therefore Part-DB can not retrieve them, even if they are shown information about datasheets and part specifications. Therefore Part-DB can not retrieve them, even if they are shown
at the mouser page. See [issue #503](https://github.com/Part-DB/Part-DB-server/issues/503) for more infos. at the mouser page. See [issue #503](https://github.com/Part-DB/Part-DB-server/issues/503) for more info.
Following env configuration options are available: Following env configuration options are available:

4
docs/usage/keybindings.md
View file

@ -93,7 +93,7 @@ all text and search fields in Part-DB.
### Currency symbols ### Currency symbols
Please not the following keybindings are bound to a specific keycode. The key character is not the same on all Please note, the following keybindings are bound to a specific keycode. The key character is not the same on all
keyboards. keyboards.
It is given here for a US keyboard layout. It is given here for a US keyboard layout.
@ -108,7 +108,7 @@ For a German keyboard layout, replace ; with ö, and ' with ä.
### Others ### Others
Please not the following keybindings are bound to a specific keycode. The key character is not the same on all Please note the following keybindings are bound to a specific keycode. The key character is not the same on all
keyboards. keyboards.
It is given here for a US keyboard layout. It is given here for a US keyboard layout.

14
docs/usage/labels.md
View file

@ -7,12 +7,12 @@ parent: Usage
# Labels # Labels
Part-DB support the generation and printing of labels for parts, part lots and storage locations. Part-DB support the generation and printing of labels for parts, part lots and storage locations.
You can use the "Tools -> Label generator" menu entry to create labels, or click the label generation link on the part. You can use the "Tools -> Label generator" menu entry to create labels or click the label generation link on the part.
You can define label templates by creating Label profiles. This way you can create many similar looking labels with for You can define label templates by creating Label profiles. This way you can create many similar-looking labels with for
many parts. many parts.
The content of the labels is defined by the templates content field. You can use the WYSIWYG editor to create and style The content of the labels is defined by the template's content field. You can use the WYSIWYG editor to create and style
the content (or write HTML code). the content (or write HTML code).
Using the "Label placeholder" menu in the editor, you can insert placeholders for the data of the parts. Using the "Label placeholder" menu in the editor, you can insert placeholders for the data of the parts.
It will be replaced by the concrete data when the label is generated. It will be replaced by the concrete data when the label is generated.
@ -20,7 +20,7 @@ It will be replaced by the concrete data when the label is generated.
## Label placeholders ## Label placeholders
A placeholder has the format `[[PLACEHOLDER]]` and will be filled with the concrete data by Part-DB. A placeholder has the format `[[PLACEHOLDER]]` and will be filled with the concrete data by Part-DB.
You can use the "Placeholders" dropdown in content editor, to automatically insert the placeholders. You can use the "Placeholders" dropdown in the content editor, to automatically insert the placeholders.
### Common ### Common
@ -124,12 +124,12 @@ the label generator settings:
The default used font (DejaVu) does not support all characters. Especially characters from non-latin languages like The default used font (DejaVu) does not support all characters. Especially characters from non-latin languages like
Chinese, Japanese, Korean, Arabic, Hebrew, Cyrillic, etc. are not supported. Chinese, Japanese, Korean, Arabic, Hebrew, Cyrillic, etc. are not supported.
For this we use [Unifont](http://unifoundry.com/unifont.html) as fallback font. This font supports all (or most) unicode For this, we use [Unifont](http://unifoundry.com/unifont.html) as fallback font. This font supports all (or most) Unicode
characters, but is not as beautiful as DejaVu. characters but is not as beautiful as DejaVu.
If you want to use a different (more beautiful) font, you can use the [custom fonts](#use-custom-fonts-for-pdf-labels) If you want to use a different (more beautiful) font, you can use the [custom fonts](#use-custom-fonts-for-pdf-labels)
feature. feature.
There is the [Noto](https://www.google.com/get/noto/) font family from Google, which supports a lot of languages and is There is the [Noto](https://www.google.com/get/noto/) font family from Google, which supports a lot of languages and is
available in different styles (regular, bold, italic, bold-italic). available in different styles (regular, bold, italic, bold-italic).
For example, you can use [Noto CJK](https://github.com/notofonts/noto-cjk) for more beautiful Chinese, Japanese For example, you can use [Noto CJK](https://github.com/notofonts/noto-cjk) for more beautiful Chinese, Japanese,
and Korean characters. and Korean characters.

40
docs/usage/tips_tricks.md
View file

@ -8,35 +8,35 @@ parent: Usage
Following you can find miscellaneous tips and tricks for using Part-DB. Following you can find miscellaneous tips and tricks for using Part-DB.
## Create datastructures directly from part edit page ## Create data structures directly from part edit page
Instead of first creating a category, manufacturer, footprint, etc. and then creating the part, you can create the Instead of first creating a category, manufacturer, footprint, etc., and then creating the part, you can create the
datastructures directly from the part edit page: Just type the name of the datastructure you want to create into the data structures directly from the part edit page: Just type the name of the data structure you want to create into the
select field on the part edit page and press "Create new ...". The new datastructure will be created, when you save select field on the part edit page and press "Create new ...". The new data structure will be created when you save
the part changes. the part changes.
You can create also create nested datastructures this way. For example, if you want to create a new category "AVRs", You can create also create nested data structures this way. For example, if you want to create a new category "AVRs",
as a subcategory of "MCUs", you can just type "MCUs->AVRs" into the category select field and press "Create new". as a subcategory of "MCUs", you can just type "MCUs->AVRs" into the category select field and press "Create new".
The new category "AVRs" will be created as a subcategory of "MCUs". If the category "MCUs" does not exist, it will The new category "AVRs" will be created as a subcategory of "MCUs". If the category "MCUs" does not exist, it will
be created too. be created too.
## Builtin footprint images ## Built-in footprint images
Part-DB includes several builtin images for common footprints. You can use these images in your footprint Part-DB includes several built-in images for common footprints. You can use these images in your footprint
datastructures, data structures,
by creating an attachment on the datastructure and selecting it as preview image. by creating an attachment on the data structure and selecting it as the preview image.
Type the name of the footprint image you want to use into the URL field of the attachment and select it from the Type the name of the footprint image you want to use into the URL field of the attachment and select it from the
dropdown menu. You can find a gallery of all builtin footprint images and their names in the "Builtin footprint image dropdown menu. You can find a gallery of all builtin footprint images and their names in the "Builtin footprint image
gallery", gallery",
which you can find in the "Tools" menu (you maybe need to give your user the permission to access this tool). which you can find in the "Tools" menu (you may need to give your user the permission to access this tool).
## Parametric search ## Parametric search
In the "parameters" tab of the filter panel on parts list page, you can define constraints, which parameter values In the "parameters" tab of the filter panel on parts list page, you can define constraints, and which parameter values
have to fulfill. This allows you to search for parts with specific parameters (or parameter ranges), for example you have to fulfill. This allows you to search for parts with specific parameters (or parameter ranges), for example, you
can search for all parts with a voltage rating of greater than 5 V. can search for all parts with a voltage rating of greater than 5 V.
## View own users permissions ## View own user's permissions
If you want to see which permissions your user has, you can find a list of the permissions in the "Permissions" panel If you want to see which permissions your user has, you can find a list of the permissions in the "Permissions" panel
on the user info page. on the user info page.
@ -49,10 +49,8 @@ part).
You can find a list of supported features in the [KaTeX documentation](https://katex.org/docs/supported.html). You can find a list of supported features in the [KaTeX documentation](https://katex.org/docs/supported.html).
To input a LaTeX equation, you have to wrap it in a pair of dollar signs (`$`). Single dollar signs mark inline To input a LaTeX equation, you have to wrap it in a pair of dollar signs (`$`). Single dollar signs mark inline
equations, equations, double dollar signs mark displayed equations (which will be their own line and centered).
double dollar signs mark displayed equations (which will be its own line and centered). For example, the following For example, the following equation will be rendered as an inline equation:
equation
will be rendered as an inline equation:
``` ```
$E=mc^2$ $E=mc^2$
@ -77,16 +75,16 @@ free API used by default only supports the Euro as base currency.
## Enforce log comments ## Enforce log comments
On almost any editing operation it is possible to add a comment describing, what or why you changed something. On almost any editing operation it is possible to add a comment describing, what or why you changed something.
This comment will be written to change log and can be viewed later. This comment will be written to changelog and can be viewed later.
If you want to enforce your users to add comments to certain operations, you can do this by setting If you want to force your users to add comments to certain operations, you can do this by setting
the `ENFORCE_CHANGE_COMMENTS_FOR` option. the `ENFORCE_CHANGE_COMMENTS_FOR` option.
See the configuration reference for more information. See the configuration reference for more information.
## Personal stocks and stock locations ## Personal stocks and stock locations
For makerspaces and universities with a lot of users, where each user can have his own stock, which only he should be For maker spaces and universities with a lot of users, where each user can have his own stock, which only he should be
able to access, you can assign able to access, you can assign
the user as "owner" of a part lot. This way, only him is allowed to add or remove parts from this lot. the user as "owner" of a part lot. This way, only he is allowed to add or remove parts from this lot.
## Update notifications ## Update notifications