mirror of
https://github.com/Part-DB/Part-DB-server.git
synced 2026-01-14 06:09:33 +00:00
Merge remote-tracking branch 'upstream/master' into Buerklin-provider
This commit is contained in:
Marc Kreidler
commit
b8638b6390
185 changed files with 23450 additions and 15606 deletions
|
|
@ -17,7 +17,7 @@ This allows external applications to interact with Part-DB, extend it or integra
|
|||
> Some features might be missing or not working yet.
|
||||
> Also be aware, that there might be security issues in the API, which could allow attackers to access or edit data via
|
||||
> the API, which
|
||||
> they normally should be able to access. So currently you should only use the API with trusted users and trusted
|
||||
> they normally should not be able to access. So currently you should only use the API with trusted users and trusted
|
||||
> applications.
|
||||
|
||||
Part-DB uses [API Platform](https://api-platform.com/) to provide the API, which allows for easy creation of REST APIs
|
||||
|
|
@ -46,7 +46,7 @@ See [Authentication chapter]({% link api/authentication.md %}) for more details.
|
|||
|
||||
The API is split into different endpoints, which are reachable under the `/api/` path of your Part-DB instance (
|
||||
e.g. `https://your-part-db.local/api/`).
|
||||
There are various endpoints for each entity type (like `part`, `manufacturer`, etc.), which allow you to read and write data, and some special endpoints like `search` or `statistics`.
|
||||
There are various endpoints for each entity type (like `parts`, `manufacturers`, etc.), which allow you to read and write data, and some special endpoints like `search` or `statistics`.
|
||||
|
||||
For example, all API endpoints for managing categories are available under `/api/categories/`. Depending on the exact
|
||||
path and the HTTP method used, you can read, create, update or delete categories.
|
||||
|
|
@ -56,7 +56,7 @@ For most entities, there are endpoints like this:
|
|||
* **POST**: `/api/categories/` - Create a new category
|
||||
* **GET**: `/api/categories/{id}` - Get a specific category by its ID
|
||||
* **DELETE**: `/api/categories/{id}` - Delete a specific category by its ID
|
||||
* **UPDATE**: `/api/categories/{id}` - Update a specific category by its ID. Only the fields which are sent in the
|
||||
* **PATCH**: `/api/categories/{id}` - Update a specific category by its ID. Only the fields which are sent in the
|
||||
request are updated, all other fields are left unchanged.
|
||||
Be aware that you have to set the [JSON Merge Patch](https://datatracker.ietf.org/doc/html/rfc7386) content type
|
||||
header (`Content-Type: application/merge-patch+json`) for this to work.
|
||||
|
|
@ -106,11 +106,11 @@ This is a great way to test the API and see how it works, without having to writ
|
|||
|
||||
By default, all list endpoints are paginated, which means only a certain number of results is returned per request.
|
||||
To get another page of the results, you have to use the `page` query parameter, which contains the page number you want
|
||||
to get (e.g. `/api/categoues/?page=2`).
|
||||
to get (e.g. `/api/categories/?page=2`).
|
||||
When using JSONLD, the links to the next page are also included in the `hydra:view` property of the response.
|
||||
|
||||
To change the size of the pages (the number of items in a single page) use the `itemsPerPage` query parameter (
|
||||
e.g. `/api/categoues/?itemsPerPage=50`).
|
||||
e.g. `/api/categories/?itemsPerPage=50`).
|
||||
|
||||
See [API Platform docs](https://api-platform.com/docs/core/pagination) for more infos.
|
||||
|
||||
|
|
|
|||
|
|
@ -23,14 +23,14 @@ each other so that it does not matter which one of your 1000 things of Part you
|
|||
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 you thought of yourself. Each name needs to be unique and must exist in a single category.
|
||||
name you thought of yourself. Each name needs to be unique and must exist in a single category only.
|
||||
* **Description**: A short (single-line) description of what this part is/does. For longer information, you should use
|
||||
the comment field or the specifications
|
||||
* **Category** (Required): The category (see there) to which this part belongs to.
|
||||
* **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 beforehand) 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.
|
||||
* **Min Instock**: *Not really implemented yet*. Parts where the total instock is below this value, will show up for
|
||||
* **Min Instock**: *Not fully implemented yet*. Parts where the total instock is below this value will show up for
|
||||
ordering.
|
||||
* **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 explicitly defined preview picture, the preview picture of its
|
||||
|
|
@ -48,9 +48,9 @@ A part entity has many fields, which can be used to describe it better. Most of
|
|||
completely trustworthy.
|
||||
* **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.
|
||||
* **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
|
||||
identifiers, or sync parts identifiers with the identifiers of another database you can use this field.
|
||||
* **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 cannot 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.
|
||||
|
||||
### Stock / Part lot
|
||||
|
||||
|
|
@ -99,12 +99,12 @@ possible category tree could look like this:
|
|||
|
||||
### Supplier
|
||||
|
||||
A Supplier is a vendor/distributor where you can buy/order parts. Price information of parts is associated with a
|
||||
A supplier is a vendor/distributor where you can buy/order parts. Price information of parts is associated with a
|
||||
supplier.
|
||||
|
||||
### Manufacturer
|
||||
|
||||
A manufacturer represents the company that manufacturers/builds various parts (not necessarily sell them). If the
|
||||
A manufacturer represents the company that manufactures/builds various parts (not necessarily sells them). If the
|
||||
manufacturer also sells the parts, you have to create a supplier for that.
|
||||
|
||||
### Storage location
|
||||
|
|
|
|||
|
|
@ -6,11 +6,11 @@ nav_order: 5
|
|||
|
||||
# Configuration
|
||||
|
||||
Part-DBs behavior can be configured to your needs. There are different kinds of configuration options: Options, which are
|
||||
Part-DB's behavior can be configured to your needs. There are different kinds of configuration options: Options that are
|
||||
user-changeable (changeable dynamically via frontend), options that can be configured by environment variables, and
|
||||
options that are only configurable via Symfony config files.
|
||||
|
||||
## User configruation
|
||||
## User configuration
|
||||
|
||||
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 user's own settings page (where you can also change the password) or via
|
||||
|
|
@ -40,10 +40,10 @@ The following configuration options can only be changed by the server administra
|
|||
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 the full list of possible env variables.
|
||||
|
||||
Environment variables allow to overwrite settings in the web interface. This is useful, if you want to enforce certain
|
||||
settings to be unchangable by users, or if you want to configure settings in a central place in a deployed environment.
|
||||
Environment variables allow you to overwrite settings in the web interface. This is useful if you want to enforce certain
|
||||
settings to be unchangeable by users, or if you want to configure settings in a central place in a deployed environment.
|
||||
On the settings page, you can hover over a setting to see, which environment variable can be used to overwrite it, it
|
||||
is shown as tooltip. API keys or similar sensitve data which is overwritten by env variables, are redacted on the web
|
||||
is shown as tooltip. API keys or similar sensitive data which is overwritten by env variables, are redacted on the web
|
||||
interface, so that even administrators cannot see them (only the last 2 characters and the length).
|
||||
|
||||
For technical and security reasons some settings can only be configured via environment variables and not via the web
|
||||
|
|
@ -105,17 +105,27 @@ bundled with Part-DB. Set `DATABASE_MYSQL_SSL_VERIFY_CERT` if you want to accept
|
|||
* `part_delete`: Delete operation of an existing part
|
||||
* `part_create`: Creation of a new part
|
||||
* `part_stock_operation`: Stock operation on a part (therefore withdraw, add or move stock)
|
||||
* `datastructure_edit`: Edit operation of an existing datastructure (e.g. category, manufacturer, ...)
|
||||
* `datastructure_delete`: Delete operation of a existing datastructure (e.g. category, manufacturer, ...)
|
||||
* `datastructure_create`: Creation of a new datastructure (e.g. category, manufacturer, ...)
|
||||
* `CHECK_FOR_UPDATES` (default `1`): Set this to 0, if you do not want Part-DB to connect to GitHub to check for new
|
||||
versions, or if your server can not connect to the internet.
|
||||
* `datastructure_edit`: Edit operation of an existing data structure (e.g. category, manufacturer, ...)
|
||||
* `datastructure_delete`: Delete operation of an existing data structure (e.g. category, manufacturer, ...)
|
||||
* `datastructure_create`: Creation of a new data structure (e.g. category, manufacturer, ...)
|
||||
* `CHECK_FOR_UPDATES` (default `1`): Set this to 0 if you do not want Part-DB to connect to GitHub to check for new
|
||||
versions, or if your server cannot connect to the internet.
|
||||
* `APP_SECRET` (env only): This variable is a configuration parameter used for various security-related purposes,
|
||||
particularly for securing and protecting various aspects of your application. It's a secret key that is used for
|
||||
cryptographic operations and security measures (session management, CSRF protection, etc..). Therefore this
|
||||
value should be handled as confidential data and not shared publicly.
|
||||
* `SHOW_PART_IMAGE_OVERLAY`: Set to 0 to disable the part image overlay, which appears if you hover over an image in the
|
||||
part image gallery
|
||||
* `IPN_SUGGEST_REGEX`: A global regular expression, that part IPNs have to fulfill. Enforce your own format for your users.
|
||||
* `IPN_SUGGEST_REGEX_HELP`: Define your own user help text for the Regex format specification.
|
||||
* `IPN_AUTO_APPEND_SUFFIX`: When enabled, an incremental suffix will be added to the user input when entering an existing
|
||||
* IPN again upon saving.
|
||||
* `IPN_SUGGEST_PART_DIGITS`: Defines the fixed number of digits used as the increment at the end of an IPN (Internal Part Number).
|
||||
IPN prefixes, maintained within part categories and their hierarchy, form the foundation for suggesting complete IPNs.
|
||||
These suggestions become accessible during IPN input of a part. The constant specifies the digits used to calculate and assign
|
||||
unique increments for parts within a category hierarchy, ensuring consistency and uniqueness in IPN generation.
|
||||
* `IPN_USE_DUPLICATE_DESCRIPTION`: When enabled, the part’s description is used to find existing parts with the same
|
||||
description and to determine the next available IPN by incrementing their numeric suffix for the suggestion list.
|
||||
|
||||
### E-Mail settings (all env only)
|
||||
|
||||
|
|
@ -136,7 +146,7 @@ bundled with Part-DB. Set `DATABASE_MYSQL_SSL_VERIFY_CERT` if you want to accept
|
|||
* `TABLE_PARTS_DEFAULT_COLUMNS`: The columns in parts tables, which are visible by default (when loading table for first
|
||||
time).
|
||||
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`, `partCustomState`, `addedDate`, `lastModified`, `needs_review`, `favorite`, `manufacturing_status`, `manufacturer_product_number`, `mass`, `tags`, `attachments`, `edit`.
|
||||
|
||||
### History/Eventlog-related settings
|
||||
|
||||
|
|
@ -252,10 +262,10 @@ markdown (and even some subset of HTML) syntax to format the text.
|
|||
|
||||
## parameters.yaml
|
||||
|
||||
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
|
||||
manual merge, when you have changed something here and update to a newer version of Part-DB. It is possible that
|
||||
configuration options here will change or be completely removed in future versions of Part-DB.
|
||||
You can also configure some options via the `config/parameters.yaml` file. This should normally not be needed,
|
||||
and you should know what you are doing when you change something here. You should expect that you will have to do some
|
||||
manual merges when you have changed something here and update to a newer version of Part-DB. It is possible that
|
||||
configuration options here will change or be 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
|
||||
command `bin/console cache:clear`.
|
||||
|
|
|
|||
|
|
@ -18,8 +18,7 @@ It is installed on a web server and so can be accessed with any browser without
|
|||
> You can log in with username: **user** and password: **user**, to change/create data.
|
||||
>
|
||||
> Every change to the master branch gets automatically deployed, so it represents the current development progress and
|
||||
> is
|
||||
> maybe not completely stable. Please mind, that the free Heroku instance is used, so it can take some time when loading
|
||||
> may not be completely stable. Please mind, that the free Heroku instance is used, so it can take some time when loading
|
||||
> the page
|
||||
> for the first time.
|
||||
|
||||
|
|
@ -28,32 +27,32 @@ It is installed on a web server and so can be accessed with any browser without
|
|||
* 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
|
||||
like datasheets or pictures with the parts.
|
||||
* 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
|
||||
* User system with groups and detailed (fine granular) permissions.
|
||||
* Multi-language support (currently German, English, Russian, Japanese, French, Czech, Danish, and Chinese)
|
||||
* Barcodes/Labels generator for parts and storage locations, scan barcodes via webcam using the built-in barcode scanner
|
||||
* User system with groups and detailed (fine-grained) permissions.
|
||||
Two-factor authentication is supported (Google Authenticator and Webauthn/U2F keys) and can be enforced for groups.
|
||||
Password reset via email can be setup.
|
||||
Password reset via email can be set up.
|
||||
* Optional support for single sign-on (SSO) via SAML (using an intermediate service
|
||||
like [Keycloak](https://www.keycloak.org/) you can connect Part-DB to an existing LDAP or Active Directory server)
|
||||
* Import/Export system
|
||||
* Project management: Create projects and assign parts to the bill of material (BOM), to show how often you could build
|
||||
this project and directly withdraw all components needed from DB
|
||||
* Event log: Track what changes happens to your inventory, track which user does what. Revert your parts to older
|
||||
* Event log: Track what changes happen to your inventory, track which user does what. Revert your parts to older
|
||||
versions.
|
||||
* Responsive design: You can use Part-DB on your PC, your tablet and your smartphone using the same interface.
|
||||
* Responsive design: You can use Part-DB on your PC, your tablet, and your smartphone using the same interface.
|
||||
* MySQL, SQLite and PostgreSQL are supported as database backends
|
||||
* Support for rich text descriptions and comments in parts
|
||||
* 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)
|
||||
* 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, Mouser, or TME) to automatically get part information, datasheets, and
|
||||
prices for parts (see [here]({% link usage/information_provider_system.md %}))
|
||||
* 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
|
||||
KiCad and see available parts from Part-DB directly inside KiCad.
|
||||
* [Integration with KiCad]({%link usage/eda_integration.md %}): Use Part-DB as the central datasource for your
|
||||
KiCad and see available parts from Part-DB directly inside KiCad.
|
||||
|
||||
With these features Part-DB is useful to hobbyists, who want to keep track of their private electronic parts inventory,
|
||||
or makerspaces, where many users have should have (controlled) access to the shared inventory.
|
||||
With these features, Part-DB is useful to hobbyists, who want to keep track of their private electronic parts inventory,
|
||||
or makerspaces, where many users should have (controlled) access to the shared inventory.
|
||||
|
||||
Part-DB is also used by small companies and universities for managing their inventory.
|
||||
|
||||
|
|
@ -68,11 +67,11 @@ See [LICENSE](https://github.com/Part-DB/Part-DB-symfony/blob/master/LICENSE) fo
|
|||
## Donate for development
|
||||
|
||||
If you want to donate to the Part-DB developer, see the sponsor button in the top bar (next to the repo name).
|
||||
There you will find various methods to support development on a monthly or a one time base.
|
||||
There you will find various methods to support development on a monthly or a one-time basis.
|
||||
|
||||
## Built with
|
||||
|
||||
* [Symfony 5](https://symfony.com/): The main framework used for the serverside PHP
|
||||
* [Symfony 6](https://symfony.com/): The main framework used for the serverside PHP
|
||||
* [Bootstrap 5](https://getbootstrap.com/) and [Bootswatch](https://bootswatch.com/): Used as website theme
|
||||
* [Fontawesome](https://fontawesome.com/): Used as icon set
|
||||
* [Hotwire Stimulus](https://stimulus.hotwired.dev/) and [Hotwire Turbo](https://turbo.hotwired.dev/): Frontend
|
||||
|
|
|
|||
|
|
@ -38,7 +38,7 @@ you have started creating data**. So you should choose the database type for you
|
|||
|
||||
* **Performance**: SQLite is not as fast as MySQL or PostgreSQL, especially when using complex queries or many users.
|
||||
* **Emulated RegEx search**: SQLite does not support RegEx search natively. Part-DB can emulate it, however that is pretty slow.
|
||||
* **Emualted natural sorting**: SQLite does not support natural sorting natively. Part-DB can emulate it, but it is pretty slow.
|
||||
* **Emulated natural sorting**: SQLite does not support natural sorting natively. Part-DB can emulate it, but it is pretty slow.
|
||||
* **Limitations with Unicode**: SQLite has limitations in comparisons and sorting of Unicode characters, which might lead to
|
||||
unexpected behavior when using non-ASCII characters in your data. For example `µ` (micro sign) is not seen as equal to
|
||||
`μ` (greek minuscule mu), therefore searching for `µ` (micro sign) will not find parts containing `μ` (mu) and vice versa.
|
||||
|
|
@ -131,7 +131,7 @@ The host (here 127.0.0.1) and port should also be specified according to your My
|
|||
In the `serverVersion` parameter you can specify the version of the MySQL/MariaDB server you are using, in the way the server returns it
|
||||
(e.g. `8.0.37` for MySQL and `10.4.14-MariaDB`). If you do not know it, you can leave the default value.
|
||||
|
||||
If you want to use a unix socket for the connection instead of a TCP connnection, you can specify the socket path in the `unix_socket` parameter.
|
||||
If you want to use a unix socket for the connection instead of a TCP connection, you can specify the socket path in the `unix_socket` parameter.
|
||||
```shell
|
||||
DATABASE_URL="mysql://user:password@localhost/database?serverVersion=8.0.37&unix_socket=/var/run/mysqld/mysqld.sock"
|
||||
```
|
||||
|
|
@ -150,7 +150,7 @@ In the `serverVersion` parameter you can specify the version of the PostgreSQL s
|
|||
|
||||
The `charset` parameter specify the character set of the database. It should be set to `utf8` to ensure that all characters are stored correctly.
|
||||
|
||||
If you want to use a unix socket for the connection instead of a TCP connnection, you can specify the socket path in the `host` parameter.
|
||||
If you want to use a unix socket for the connection instead of a TCP connection, you can specify the socket path in the `host` parameter.
|
||||
```shell
|
||||
DATABASE_URL="postgresql://db_user@localhost/db_name?serverVersion=16.6&charset=utf8&host=/var/run/postgresql"
|
||||
```
|
||||
|
|
@ -177,6 +177,6 @@ In natural sorting, it would be sorted as:
|
|||
Part-DB can sort names in part tables and tree views naturally. PostgreSQL and MariaDB 10.7+ support natural sorting natively,
|
||||
and it is automatically used if available.
|
||||
|
||||
For SQLite and MySQL < 10.7 it has to be emulated if wanted, which is pretty slow. Therefore it has to be explicity enabled by setting the
|
||||
For SQLite and MySQL < 10.7 it has to be emulated if wanted, which is pretty slow. Therefore it has to be explicitly enabled by setting the
|
||||
`DATABASE_EMULATE_NATURAL_SORT` environment variable to `1`. If it is 0 the classical binary sorting is used, on these databases. The emulations
|
||||
might have some quirks and issues, so it is recommended to use a database which supports natural sorting natively, if you want to use it.
|
||||
|
|
|
|||
|
|
@ -15,13 +15,75 @@ To make emails work you have to properly configure a mail provider in Part-DB.
|
|||
## Configuration
|
||||
|
||||
Part-DB uses [Symfony Mailer](https://symfony.com/doc/current/mailer.html) to send emails, which supports multiple
|
||||
automatic mail providers (like MailChimp or SendGrid). If you want to use one of these providers, check the Symfony
|
||||
mail providers (like Mailgun, SendGrid, or Brevo). If you want to use one of these providers, check the Symfony
|
||||
Mailer documentation for more information.
|
||||
|
||||
We will only cover the configuration of an SMTP provider here, which is sufficient for most use-cases.
|
||||
You will need an email account, which you can use send emails from via password-bases SMTP authentication, this account
|
||||
You will need an email account, which you can use to send emails from via password-based SMTP authentication, this account
|
||||
should be dedicated to Part-DB.
|
||||
|
||||
### Using specialized mail providers (Mailgun, SendGrid, etc.)
|
||||
|
||||
If you want to use a specialized mail provider like Mailgun, SendGrid, Brevo (formerly Sendinblue), Amazon SES, or
|
||||
Postmark instead of SMTP, you need to install the corresponding Symfony mailer package first.
|
||||
|
||||
#### Docker installation
|
||||
|
||||
If you are using Part-DB in Docker, you can install additional mailer packages by setting the `COMPOSER_EXTRA_PACKAGES`
|
||||
environment variable in your `docker-compose.yaml`:
|
||||
|
||||
```yaml
|
||||
environment:
|
||||
- COMPOSER_EXTRA_PACKAGES=symfony/mailgun-mailer
|
||||
- MAILER_DSN=mailgun+api://API_KEY:DOMAIN@default
|
||||
- EMAIL_SENDER_EMAIL=noreply@yourdomain.com
|
||||
- EMAIL_SENDER_NAME=Part-DB
|
||||
- ALLOW_EMAIL_PW_RESET=1
|
||||
```
|
||||
|
||||
You can install multiple packages by separating them with spaces:
|
||||
|
||||
```yaml
|
||||
environment:
|
||||
- COMPOSER_EXTRA_PACKAGES=symfony/mailgun-mailer symfony/sendgrid-mailer
|
||||
```
|
||||
|
||||
The packages will be installed automatically when the container starts.
|
||||
|
||||
Common mailer packages:
|
||||
- `symfony/mailgun-mailer` - For [Mailgun](https://www.mailgun.com/)
|
||||
- `symfony/sendgrid-mailer` - For [SendGrid](https://sendgrid.com/)
|
||||
- `symfony/brevo-mailer` - For [Brevo](https://www.brevo.com/) (formerly Sendinblue)
|
||||
- `symfony/amazon-mailer` - For [Amazon SES](https://aws.amazon.com/ses/)
|
||||
- `symfony/postmark-mailer` - For [Postmark](https://postmarkapp.com/)
|
||||
|
||||
#### Direct installation (non-Docker)
|
||||
|
||||
If you have installed Part-DB directly on your server (not in Docker), you need to manually install the required
|
||||
mailer package using composer.
|
||||
|
||||
Navigate to your Part-DB installation directory and run:
|
||||
|
||||
```bash
|
||||
# Install the package as the web server user
|
||||
sudo -u www-data composer require symfony/mailgun-mailer
|
||||
|
||||
# Clear the cache
|
||||
sudo -u www-data php bin/console cache:clear
|
||||
```
|
||||
|
||||
Replace `symfony/mailgun-mailer` with the package you need. You can install multiple packages at once:
|
||||
|
||||
```bash
|
||||
sudo -u www-data composer require symfony/mailgun-mailer symfony/sendgrid-mailer
|
||||
```
|
||||
|
||||
After installing the package, configure the `MAILER_DSN` in your `.env.local` file according to the provider's
|
||||
documentation (see [Symfony Mailer documentation](https://symfony.com/doc/current/mailer.html) for DSN format for
|
||||
each provider).
|
||||
|
||||
## SMTP Configuration
|
||||
|
||||
To configure the SMTP provider, you have to set the following environment variables:
|
||||
|
||||
`MAILER_DSN`: You have to provide the SMTP server address and the credentials for the email account here. The format is
|
||||
|
|
|
|||
|
|
@ -8,4 +8,4 @@ has_children: true
|
|||
# Installation
|
||||
Below you can find some guides to install Part-DB.
|
||||
|
||||
For the hobbyists without much experience, we recommend the docker installation or direct installation on debian.
|
||||
For hobbyists without much experience, we recommend the Docker installation or direct installation on Debian.
|
||||
|
|
@ -80,7 +80,11 @@ services:
|
|||
#- BANNER=This is a test banner<br>with a line break
|
||||
|
||||
# If you use a reverse proxy in front of Part-DB, you must configure the trusted proxies IP addresses here (see reverse proxy documentation for more information):
|
||||
# - TRUSTED_PROXIES=127.0.0.0/8,::1,10.0.0.0/8,172.16.0.0/12,192.168.0.0/16
|
||||
# - TRUSTED_PROXIES=127.0.0.0/8,::1,10.0.0.0/8,172.16.0.0/12,192.168.0.0/16
|
||||
|
||||
# If you need to install additional composer packages (e.g., for specific mailer transports), you can specify them here:
|
||||
# The packages will be installed automatically when the container starts
|
||||
# - COMPOSER_EXTRA_PACKAGES=symfony/mailgun-mailer symfony/sendgrid-mailer
|
||||
```
|
||||
|
||||
4. Customize the settings by changing the environment variables (or adding new ones). See [Configuration]({% link
|
||||
|
|
@ -136,19 +140,22 @@ services:
|
|||
# In docker env logs will be redirected to stderr
|
||||
- APP_ENV=docker
|
||||
|
||||
# Uncomment this, if you want to use the automatic database migration feature. With this you have you do not have to
|
||||
# Uncomment this, if you want to use the automatic database migration feature. With this you do not have to
|
||||
# run the doctrine:migrations:migrate commands on installation or upgrade. A database backup is written to the uploads/
|
||||
# folder (under .automigration-backup), so you can restore it, if the migration fails.
|
||||
# This feature is currently experimental, so use it at your own risk!
|
||||
# - DB_AUTOMIGRATE=true
|
||||
|
||||
# You can configure Part-DB using the webUI or environment variables
|
||||
# However you can add add any other environment configuration you want here
|
||||
# However you can add any other environment configuration you want here
|
||||
# See .env file for all available options or https://docs.part-db.de/configuration.html
|
||||
|
||||
# Override value if you want to show to show a given text on homepage.
|
||||
# When this is outcommented the webUI can be used to configure the banner
|
||||
# Override value if you want to show a given text on homepage.
|
||||
# When this is commented out the webUI can be used to configure the banner
|
||||
#- BANNER=This is a test banner<br>with a line break
|
||||
|
||||
# If you need to install additional composer packages (e.g., for specific mailer transports), you can specify them here:
|
||||
# - COMPOSER_EXTRA_PACKAGES=symfony/mailgun-mailer symfony/sendgrid-mailer
|
||||
|
||||
database:
|
||||
container_name: partdb_database
|
||||
|
|
@ -169,6 +176,38 @@ services:
|
|||
|
||||
```
|
||||
|
||||
### Installing additional composer packages
|
||||
|
||||
If you need to use specific mailer transports or other functionality that requires additional composer packages, you can
|
||||
install them automatically at container startup using the `COMPOSER_EXTRA_PACKAGES` environment variable.
|
||||
|
||||
For example, if you want to use Mailgun as your email provider, you need to install the `symfony/mailgun-mailer` package.
|
||||
Add the following to your docker-compose.yaml environment section:
|
||||
|
||||
```yaml
|
||||
environment:
|
||||
- COMPOSER_EXTRA_PACKAGES=symfony/mailgun-mailer
|
||||
- MAILER_DSN=mailgun+api://API_KEY:DOMAIN@default
|
||||
```
|
||||
|
||||
You can specify multiple packages by separating them with spaces:
|
||||
|
||||
```yaml
|
||||
environment:
|
||||
- COMPOSER_EXTRA_PACKAGES=symfony/mailgun-mailer symfony/sendgrid-mailer
|
||||
```
|
||||
|
||||
{: .info }
|
||||
> The packages will be installed when the container starts. This may increase the container startup time on the first run.
|
||||
> The installed packages will persist in the container until it is recreated.
|
||||
|
||||
Common mailer packages you might need:
|
||||
- `symfony/mailgun-mailer` - For Mailgun email service
|
||||
- `symfony/sendgrid-mailer` - For SendGrid email service
|
||||
- `symfony/brevo-mailer` - For Brevo (formerly Sendinblue) email service
|
||||
- `symfony/amazon-mailer` - For Amazon SES email service
|
||||
- `symfony/postmark-mailer` - For Postmark email service
|
||||
|
||||
### Update Part-DB
|
||||
|
||||
You can update Part-DB by pulling the latest image and restarting the container.
|
||||
|
|
|
|||
|
|
@ -7,7 +7,7 @@ nav_order: 10
|
|||
|
||||
# Nginx
|
||||
|
||||
You can also use [nginx](https://www.nginx.com/) as webserver for Part-DB. Setup Part-DB with apache is a bit easier, so
|
||||
You can also use [nginx](https://www.nginx.com/) as webserver for Part-DB. Setting up Part-DB with Apache is a bit easier, so
|
||||
this is the method shown in the guides. This guide assumes that you already have a working nginx installation with PHP
|
||||
configured.
|
||||
|
||||
|
|
|
|||
|
|
@ -21,7 +21,7 @@ LDAP or Active Directory server.
|
|||
|
||||
{: .warning }
|
||||
> This feature is currently in beta. Please report any bugs you find.
|
||||
> So far it has only tested with Keycloak, but it should work with any SAML 2.0 compatible identity provider.
|
||||
> So far it has only been tested with Keycloak, but it should work with any SAML 2.0 compatible identity provider.
|
||||
|
||||
This guide will show you how to configure Part-DB with [Keycloak](https://www.keycloak.org/) as the SAML identity
|
||||
provider, but it should work with any SAML 2.0 compatible identity provider.
|
||||
|
|
@ -75,8 +75,8 @@ the [Keycloak Getting Started Guide](https://www.keycloak.org/docs/latest/gettin
|
|||
|
||||
### Configure Part-DB to use SAML
|
||||
|
||||
1. Open the `.env.local` file of Part-DB (or the docker-compose.yaml) for edit
|
||||
2. Set the `SAMLP_SP_PRIVATE_KEY` environment variable to the content of the private key file you downloaded in the
|
||||
1. Open the `.env.local` file of Part-DB (or the docker-compose.yaml) for editing
|
||||
2. Set the `SAML_SP_PRIVATE_KEY` environment variable to the content of the private key file you downloaded in the
|
||||
previous step. It should start with `MIEE` and end with `=`.
|
||||
3. Set the `SAML_SP_X509_CERT` environment variable to the content of the Certificate field shown in the `Keys` tab of
|
||||
the SAML client in Keycloak. It should start with `MIIC` and end with `=`.
|
||||
|
|
|
|||
|
|
@ -9,7 +9,7 @@ Sometimes things go wrong and Part-DB shows an error message. This page should h
|
|||
|
||||
## Error messages
|
||||
|
||||
When a common, easy fixable error occurs (like a non-up-to-date database), Part-DB will show you some short instructions
|
||||
When a common, easily fixable error occurs (like a non-up-to-date database), Part-DB will show you some short instructions
|
||||
on how to fix the problem. If you have a problem that is not listed here, please open an issue on GitHub.
|
||||
|
||||
## General procedure
|
||||
|
|
@ -28,9 +28,9 @@ php bin/console cache:clear
|
|||
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-server).
|
||||
|
||||
## Search for the user and reset the password:
|
||||
## Search for a user and reset the password
|
||||
|
||||
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
|
||||
|
|
@ -50,6 +50,21 @@ docker-compose logs -f
|
|||
|
||||
Please include the error logs in your issue on GitHub, if you open an issue.
|
||||
|
||||
## KiCad Integration Issues
|
||||
|
||||
### "API responded with error code: 0: Unknown"
|
||||
|
||||
If you get this error when trying to connect KiCad to Part-DB, it is most likely caused by KiCad not trusting your SSL/TLS certificate.
|
||||
|
||||
**Cause:** KiCad does not trust self-signed SSL/TLS certificates.
|
||||
|
||||
**Solutions:**
|
||||
- Use HTTP instead of HTTPS for the `root_url` in your KiCad library configuration (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)
|
||||
|
||||
For more information about KiCad integration, see the [EDA / KiCad integration](../usage/eda_integration.md) documentation.
|
||||
|
||||
## Report Issue
|
||||
|
||||
If an error occurs, or you found a bug, please [open an issue on GitHub](https://github.com/Part-DB/Part-DB-symfony).
|
||||
If an error occurs, or you found a bug, please [open an issue on GitHub](https://github.com/Part-DB/Part-DB-server).
|
||||
|
|
|
|||
|
|
@ -27,7 +27,7 @@ about the requirements at all.
|
|||
|
||||
## Changes
|
||||
* Configuration is now preferably done via a web settings interface. You can still use environment variables, these overwrite
|
||||
the settings in the web interface. Existing configuration will still work, but you should consider migriting them to the
|
||||
the settings in the web interface. Existing configuration will still work, but you should consider migrating them to the
|
||||
web interface as described below.
|
||||
* The `config/banner.md` file that could been used to customize the banner text, was removed. You can now set the banner text
|
||||
directly in the admin interface, or by setting the `BANNER` environment variable. If you want to keep your existing
|
||||
|
|
@ -43,7 +43,7 @@ The upgrade process works very similar to a normal (minor release) upgrade.
|
|||
|
||||
### Direct installation
|
||||
|
||||
**Be sure to execute the following steps as the user that owns the Part-DB files (e.g. `www-data`, or your webserver user). So prepend a `sudo -u wwww-data` where necessary.**
|
||||
**Be sure to execute the following steps as the user that owns the Part-DB files (e.g. `www-data`, or your webserver user). So prepend a `sudo -u www-data` where necessary.**
|
||||
|
||||
1. Make a backup of your existing Part-DB installation, including the database, data directories and the configuration files and `.env.local` file.
|
||||
The `php bin/console partdb:backup` command can help you with this.
|
||||
|
|
@ -51,7 +51,7 @@ The `php bin/console partdb:backup` command can help you with this.
|
|||
3. Remove the `var/cache/` directory inside the Part-DB installation to ensure that no old cache files remain.
|
||||
4. Run `composer install --no-dev -o` to update the dependencies.
|
||||
5. Run `yarn install` and `yarn build` to update the frontend assets.
|
||||
6. Rund `php bin/console doctrine:migrations:migrate` to update the database schema.
|
||||
6. Run `php bin/console doctrine:migrations:migrate` to update the database schema.
|
||||
7. Clear the cache with `php bin/console cache:clear`.
|
||||
8. Open your Part-DB instance in the browser and log in as an admin user.
|
||||
9. Go to the user or group permissions page, and give yourself (and other administrators) the right to change system settings (under "System" and "Configuration").
|
||||
|
|
@ -79,7 +79,7 @@ To change it, you must migrate your environment variable configuration to the ne
|
|||
|
||||
For this there is the new console command `settings:migrate-env-to-settings`, which reads in all environment variables used to overwrite
|
||||
settings and write them to the database, so that you can safely delete them from your environment variable configuration afterwards, without
|
||||
loosing your configuration.
|
||||
losing your configuration.
|
||||
|
||||
To run the command, execute `php bin/console settings:migrate-env-to-settings --all` as webserver user (or run `docker exec --user=www-data -it partdb php bin/console settings:migrate-env-to-settings --all` for docker containers).
|
||||
It will list you all environment variables, it found and ask you for confirmation to migrate them. Answer with `yes` to migrate them and hit enter.
|
||||
|
|
|
|||
|
|
@ -5,5 +5,7 @@ nav_order: 7
|
|||
has_children: true
|
||||
---
|
||||
|
||||
# Upgrade
|
||||
|
||||
This section provides information on how to upgrade Part-DB to the latest version.
|
||||
This is intended for major release upgrades, where requirements or things changes significantly.
|
||||
This is intended for major release upgrades, where requirements or things change significantly.
|
||||
|
|
|
|||
|
|
@ -24,7 +24,7 @@ sections carefully before proceeding to upgrade.
|
|||
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.
|
||||
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 partdb:migrations:convert-bbcode`.
|
||||
* Server exceptions are not logged into event log anymore. For security reasons (exceptions can contain sensitive
|
||||
information) 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
|
||||
|
|
|
|||
|
|
@ -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
|
||||
|
||||
|
|
|
|||
|
|
@ -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.
|
||||
|
|
|
|||
|
|
@ -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
|
||||
|
||||
|
|
|
|||
|
|
@ -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`.
|
||||
|
||||
|
||||
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).
|
|||
|
||||
|
||||
|
||||
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.
|
||||
|
||||
|
||||
|
|
@ -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.
|
||||
|
|
|
|||
|
|
@ -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
|
||||
|
|
|
|||
|
|
@ -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
|
||||
|
|
|
|||
|
|
@ -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
|
||||
|
|
|
|||
|
|
@ -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.
|
||||
|
|
|
|||
Loading…
Add table
Add a link
Reference in a new issue