groove/Part-DB-server
1
0
Fork 0
mirror of https://github.com/Part-DB/Part-DB-server.git synced 2026-01-14 06:09:33 +00:00
Code Issues Projects Releases Packages Wiki Activity Actions 5

Merge remote-tracking branch 'upstream/master' into Buerklin-provider

Browse source
This commit is contained in:
Marc Kreidler 2025-12-07 20:23:12 +01:00
commit b8638b6390
185 changed files with 23450 additions and 15606 deletions
Download patch file Download diff file Expand all files Collapse all files

10
docs/usage/backup_restore.md
View file

@ -6,7 +6,7 @@ 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
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.
@ -27,7 +27,7 @@ for more info about these options.
## Backup (manual)
3 parts have to be backup-ed: The configuration files, which contain the instance-specific options, the
Three parts have to be backed up: 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.
@ -44,7 +44,7 @@ You have to recursively copy the `uploads/` folder and the `public/media` folder
#### SQLite
If you are using sqlite, it is sufficient to just copy your `app.db` from your database location (normally `var/app.db`)
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.
#### MySQL / MariaDB
@ -56,7 +56,7 @@ interface (`mysqldump -uBACKUP -pPASSWORD DATABASE`)
## Restore
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.
have to use the same database type (SQLite or MySQL) as on the backed up server instance.
### Restore configuration
@ -71,7 +71,7 @@ Copy the `uploads/` and the `public/media/` folder from your backup into your ne
#### SQLite
Copy the backup-ed `app.db` into the database folder normally `var/app.db` in Part-DB root folder.
Copy the backed up `app.db` into the database folder normally `var/app.db` in Part-DB root folder.
#### MySQL / MariaDB

14
docs/usage/console_commands.md
View file

@ -8,7 +8,7 @@ parent: Usage
Part-DB provides some console commands to display various information or perform some tasks.
The commands are invoked from the main directory of Part-DB with the command `php bin/console [command]` in the context
of the database user (so usually the webserver user), so you maybe have to use `sudo` or `su` to execute the commands:
of the web server user (so usually the webserver user), so you may have to use `sudo` or `su` to execute the commands:
```bash
sudo -u www-data php bin/console [command]
@ -17,8 +17,8 @@ sudo -u www-data php bin/console [command]
You can get help for every command with the parameter `--help`. See `php bin/console` for a list of all available
commands.
If you are running Part-DB in a docker container, you must either execute the commands from a shell inside a container,
or use the `docker exec` command to execute the command directly inside the container. For example if you docker container
If you are running Part-DB in a Docker container, you must either execute the commands from a shell inside the container,
or use the `docker exec` command to execute the command directly inside the container. For example, if your Docker container
is named `partdb`, you can execute the command `php bin/console cache:clear` with the following command:
```bash
@ -61,7 +61,7 @@ docker exec --user=www-data partdb php bin/console cache:clear
* `partdb:attachments:clean-unused`: Remove all attachments which are not used by any database entry (e.g. orphaned
attachments)
* `partdb:cache:clear`: Clears all caches, so the next page load will be slower, but the cache will be rebuilt. This can
maybe fix some issues, when the cache were corrupted. This command is also needed after changing things in
maybe fix some issues when the cache was corrupted. This command is also needed after changing things in
the `parameters.yaml` file or upgrading Part-DB.
* `partdb:migrations:import-partkeepr`: Imports a mysqldump XML dump of a PartKeepr database into Part-DB. This is only
needed for users, which want to migrate from PartKeepr to Part-DB. *All existing data in the Part-DB database is
@ -76,6 +76,6 @@ The value of the environment variable is copied to the settings database, so the
## Attachment commands
* `php bin/console partdb:attachments:download`: Download all attachments, which are not already downloaded, to the
local filesystem. This is useful to create local backups of the attachments, no matter what happens on the remote and
also makes pictures thumbnails available for the frontend for them
* `php bin/console partdb:attachments:download`: Download all attachments that are not already downloaded to the
local filesystem. This is useful to create local backups of the attachments, no matter what happens on the remote, and
also makes picture thumbnails available for the frontend for them.

24
docs/usage/eda_integration.md
View file

@ -17,14 +17,24 @@ This also allows to configure available and usable parts and their properties in
## KiCad Setup
{: .important }
> Part-DB uses the HTTP library feature of KiCad, which is experimental and not part of the stable KiCad 7 releases. If you want to use this feature, you need to install a KiCad nightly build (7.99 version). This feature will most likely also be part of KiCad 8.
> Part-DB uses the HTTP library feature of KiCad, which was experimental in earlier versions. If you want to use this feature, you need to install KiCad 8 or newer.
Part-DB should be accessible from the PCs with KiCAD. The URL should be stable (so no dynamically changing IP).
You require a user account in Part-DB, which has permission to access Part-DB API and create API tokens. Every user can have its own account, or you set up a shared read-only account.
Part-DB should be accessible from the PCs with KiCad. The URL should be stable (so no dynamically changing IP).
You require a user account in Part-DB, which has permission to access the Part-DB API and create API tokens. Every user can have their own account, or you set up a shared read-only account.
{: .warning }
> **HTTPS with Self-Signed Certificates**
>
> KiCad does not trust self-signed SSL/TLS certificates. If your Part-DB instance uses HTTPS with a self-signed certificate, KiCad will fail to connect and show an error like: `API responded with error code: 0: Unknown`.
>
> To resolve this issue, you have the following options:
> - Use HTTP instead of HTTPS for the `root_url` (only recommended for local networks)
> - Use a certificate from a trusted Certificate Authority (CA) like [Let's Encrypt](https://letsencrypt.org/)
> - Add your self-signed certificate to the system's trusted certificate store on the computer running KiCad (the exact steps depend on your operating system)
To connect KiCad with Part-DB do the following steps:
1. Create an API token on the user settings page for the KiCAD application and copy/save it, when it is shown. Currently, KiCad can only read Part-DB database, so a token with a read-only scope is enough.
1. Create an API token on the user settings page for the KiCad application and copy/save it when it is shown. Currently, KiCad can only read the Part-DB database, so a token with a read-only scope is enough.
2. Add some EDA metadata to parts, categories, or footprints. Only parts with usable info will show up in KiCad. See below for more info.
3. Create a file `partd.kicad_httplib` (or similar, only the extension is important) with the following content:
```
@ -54,18 +64,18 @@ Part-DB doesn't save any concrete footprints or symbols for the part. Instead, P
You can define this on a per-part basis using the KiCad symbol and KiCad footprint field in the EDA tab of the part editor. Or you can define it at a category (symbol) or footprint level, to assign this value to all parts with this category and footprint.
For example, to configure the values for a BC547 transistor you would put `Transistor_BJT:BC547` on the parts Kicad symbol to give it the right schematic symbol in EEschema and `Package_TO_SOT_THT:TO-92` to give it the right footprint in PcbNew.
For example, to configure the values for a BC547 transistor you would put `Transistor_BJT:BC547` in the part's KiCad symbol field to give it the right schematic symbol in Eeschema and `Package_TO_SOT_THT:TO-92` to give it the right footprint in Pcbnew.
If you type in a character, you will get an autocomplete list of all symbols and footprints available in the KiCad standard library. You can also input your own value.
### Parts and category visibility
Only parts and their categories, on which there is any kind of EDA metadata are defined show up in KiCad. So if you want to see parts in KiCad,
Only parts and their categories on which there is any kind of EDA metadata defined show up in KiCad. So if you want to see parts in KiCad,
you need to define at least a symbol, footprint, reference prefix, or value on a part, category or footprint.
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 visible 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 that would change the visible categories in KiCad, you have to reload Eeschema to see the changes.*
### Category depth in KiCad

18
docs/usage/getting_started.md
View file

@ -6,7 +6,7 @@ nav_order: 4
# Getting started
After Part-DB you should begin with customizing the settings, and setting up the basic structures.
After installing Part-DB, you should begin with customizing the settings and setting up the basic structures.
Before starting, it's useful to read a bit about the [concepts of Part-DB]({% link concepts.md %}).
1. TOC
@ -14,8 +14,8 @@ Before starting, it's useful to read a bit about the [concepts of Part-DB]({% li
## Customize system settings
Before starting creating datastructures, you should check the system settings to ensure that they fit your needs.
After login as an administrator, you can find the settings in the sidebar under `Tools -> System -> Settings`.
Before starting creating data structures, you should check the system settings to ensure that they fit your needs.
After logging in as an administrator, you can find the settings in the sidebar under `Tools -> System -> Settings`.
![image]({% link assets/getting_started/system_settings.png %})
Here you can change various settings, like the name of your Part-DB instance (which is shown in the title bar of the
@ -35,9 +35,9 @@ 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
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)
can even be enforced for all members of a user group)
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
@ -64,7 +64,7 @@ $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`.
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
For each user who should use Part-DB, you should set up their own account so that tracking of what each user did works
properly.
![image]({% link assets/getting_started/user_admin.png %})
@ -207,7 +207,7 @@ You have to enter at least a name for the part and choose a category for it, the
However, it is recommended to fill out as much information as possible, as this will make it easier to find the part
later.
You can choose from your created datastructures to add manufacturer information, supplier information, etc. to the part.
You can also create new datastructures on the fly, if you want to add additional information to the part, by typing the
name of the new datastructure in the field and select the "New ..." option in the dropdown menu. See [tips]({% link
You can choose from your created data structures to add manufacturer information, supplier information, etc. to the part.
You can also create new data structures on the fly if you want to add additional information to the part, by typing the
name of the new data structure in the field and selecting the "New ..." option in the dropdown menu. See [tips]({% link
usage/tips_tricks.md %}) for more information.

8
docs/usage/import_export.md
View file

@ -20,7 +20,7 @@ Part-DB. Data can also be exported from Part-DB into various formats.
> individually in the permissions settings.
If you want to import data from PartKeepr you might want to look into the [PartKeepr migration guide]({% link
upgrade/upgrade_legacy.md %}).
partkeepr_migration.md %}).
### Import parts
@ -47,9 +47,9 @@ You can upload the file that should be imported here and choose various options
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 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.
* **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 exist. If this is not selected, only
existing data structures will be used, and if no matching data structure 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

18
docs/usage/information_provider_system.md
View file

@ -78,7 +78,7 @@ results will be shown.
## Data providers
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 an "info provider" and handles the communication with the external source.
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.
That way it is pretty easy to create new providers as they just need to do very little work.
@ -157,7 +157,7 @@ again, to establish a new connection.
### TME
The TME provider uses 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 get shopping information from
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/).
You have to generate a new anonymous key there and enter the key and secret in the Part-DB env configuration (see
@ -176,10 +176,10 @@ The following env configuration options are available:
### Farnell / Element14 / Newark
The Farnell provider uses the [Farnell API](https://partner.element14.com/) to search for parts and getting shopping
The Farnell provider uses the [Farnell API](https://partner.element14.com/) to search for parts and get shopping
information from [Farnell](https://www.farnell.com/).
You have to create an account at Farnell and get an API key on the [Farnell API page](https://partner.element14.com/).
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 do not matter, as long as you select the "Product Search API") and you will
get an API key.
The following env configuration options are available:
@ -191,17 +191,13 @@ The following env configuration options are available:
### Mouser
The Mouser provider uses the [Mouser API](https://www.mouser.de/api-home/) to search for parts and getting shopping
The Mouser provider uses the [Mouser API](https://www.mouser.de/api-home/) to search for parts and get shopping
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
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):
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
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 info.
Following env configuration options are available:
* `PROVIDER_MOUSER_KEY`: The API key you got from Mouser (mandatory)
@ -217,7 +213,7 @@ Following env configuration options are available:
webshop uses an internal JSON based API to render the page. Part-DB can use this inofficial API to get part information
from LCSC.
**Please note, that the use of this internal API is not intended or endorsed by LCS and it could break at any time. So use it at your own risk.**
**Please note that the use of this internal API is not intended or endorsed by LCSC and it could break at any time. So use it at your own risk.**
An API key is not required, it is enough to enable the provider using the following env configuration options:
@ -226,7 +222,7 @@ An API key is not required, it is enough to enable the provider using the follow
### OEMsecrets
The oemsecrets provider uses the [oemsecrets API](https://www.oemsecrets.com/) to search for parts and getting shopping
The oemsecrets provider uses the [oemsecrets API](https://www.oemsecrets.com/) to search for parts and get shopping
information from them. Similar to octopart it aggregates offers from different distributors.
You can apply for a free API key on the [oemsecrets API page](https://www.oemsecrets.com/api/) and put the key you get

4
docs/usage/labels.md
View file

@ -6,10 +6,10 @@ parent: Usage
# Labels
Part-DB support the generation and printing of labels for parts, part lots and storage locations.
Part-DB supports 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 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 for
many parts.
The content of the labels is defined by the template's content field. You can use the WYSIWYG editor to create and style

8
docs/usage/tips_tricks.md
View file

@ -65,7 +65,7 @@ $$E=mc^2$$
## Update currency exchange rates automatically
Part-DB can update the currency exchange rates of all defined currencies programmatically
by calling the `php bin/console partdb:currencies:update-exchange-rates`.
by calling `php bin/console partdb:currencies:update-exchange-rates`.
If you call this command regularly (e.g. with a cronjob), you can keep the exchange rates up-to-date.
@ -88,9 +88,9 @@ the user as "owner" of a part lot. This way, only he is allowed to add or remove
## Update notifications
Part-DB can show you a notification that there is a newer version than currently installed available. The notification
Part-DB can show you a notification that there is a newer version than currently installed. The notification
will be shown on the homepage and the server info page.
It is only be shown to users which has the `Show available Part-DB updates` permission.
It is only shown to users which have the `Show available Part-DB updates` permission.
For the notification to work, Part-DB queries the GitHub API every 2 days to check for new releases. No data is sent to
GitHub besides the metadata required for the connection (so the public IP address of your computer running Part-DB).
@ -98,6 +98,6 @@ If you don't want Part-DB to query the GitHub API, or if your server can not rea
update notifications by setting the `CHECK_FOR_UPDATES` option to `false`.
## Internet access via proxy
If you server running Part-DB does not have direct access to the internet, but has to use a proxy server, you can configure
If your server running Part-DB does not have direct access to the internet, but has to use a proxy server, you can configure
the proxy settings in the `.env.local` file (or docker env config). You can set the `HTTP_PROXY` and `HTTPS_PROXY` environment
variables to the URL of your proxy server. If your proxy server requires authentication, you can include the username and password in the URL.