mirror of
https://github.com/Part-DB/Part-DB-server.git
synced 2026-01-13 21:59:34 +00:00
Merge tag 'v2.1.2' into Buerklin-provider
# Conflicts: # .docker/symfony.conf # VERSION
This commit is contained in:
Marc Kreidler
commit
5b2fc7ef4b
366 changed files with 32347 additions and 19045 deletions
BIN
docs/assets/getting_started/system_settings.png
Normal file
BIN
docs/assets/getting_started/system_settings.png
Normal file
Binary file not shown.
|
After Width: | Height: | Size: 49 KiB |
|
|
@ -10,7 +10,7 @@ Part-DBs behavior can be configured to your needs. There are different kinds of
|
|||
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 changeable
|
||||
## User configruation
|
||||
|
||||
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
|
||||
|
|
@ -24,15 +24,34 @@ the user admin page:
|
|||
* **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
|
||||
|
||||
## System configuration (via web interface)
|
||||
|
||||
Many common configuration options can be changed via the web interface. You can find the settings page in the sidebar under
|
||||
"System" -> "Settings". You need to have the "Change system settings" permission to access this page.
|
||||
|
||||
If a setting is greyed out and cannot be changed, it means that this setting is currently overwritten by an environment
|
||||
variable. You can either change the environment variable to change the setting, or you can migrate the setting to the
|
||||
database, so that it can be changed via the web interface. To do this, you can use the `php bin/console settings:migrate-env-to-settings` command
|
||||
and remove the environment variable afterward.
|
||||
|
||||
## Environment variables (.env.local)
|
||||
|
||||
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
|
||||
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.
|
||||
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
|
||||
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
|
||||
interface. These settings are marked with "(env only)" in the description below.
|
||||
|
||||
### General options
|
||||
|
||||
* `DATABASE_URL`: Configures the database which Part-DB uses:
|
||||
* `DATABASE_URL` (env only): Configures the database which Part-DB uses:
|
||||
* For MySQL (or MariaDB) use a string in the form 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
|
||||
|
|
@ -42,10 +61,10 @@ options listed, see `.env` file for the full list of possible env variables.
|
|||
|
||||
Please note that **`serverVersion=x.y`** variable is required due to dependency of Symfony framework.
|
||||
|
||||
* `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` (env only): 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
|
||||
bundled with Part-DB. Set `DATABASE_MYSQL_SSL_VERIFY_CERT` if you want to accept all certificates.
|
||||
* `DATABASE_EMULATE_NATURAL_SORT` (default 0): If set to 1, Part-DB will emulate natural sorting, even if the database
|
||||
* `DATABASE_EMULATE_NATURAL_SORT` (default 0) (env only): If set to 1, Part-DB will emulate natural sorting, even if the database
|
||||
does not support it natively. However this is much slower than the native sorting, and contain bugs or quirks, so use
|
||||
it only, if you have to.
|
||||
* `DEFAULT_LANG`: The default language to use server-wide (when no language is explicitly specified by a user or via
|
||||
|
|
@ -74,7 +93,7 @@ bundled with Part-DB. Set `DATABASE_MYSQL_SSL_VERIFY_CERT` if you want to accept
|
|||
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
|
||||
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` (env only): The default URI base to use for the Part-DB, when no URL can be determined from the browser request.
|
||||
This should be the primary URL/Domain, which is used to access Part-DB. This value is used to create correct links in
|
||||
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
|
||||
|
|
@ -91,12 +110,14 @@ bundled with Part-DB. Set `DATABASE_MYSQL_SSL_VERIFY_CERT` if you want to accept
|
|||
* `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.
|
||||
* `APP_SECRET`: This variable is a configuration parameter used for various security-related purposes,
|
||||
* `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
|
||||
|
||||
### E-Mail settings
|
||||
### E-Mail settings (all env only)
|
||||
|
||||
* `MAILER_DSN`: You can configure the mail provider which should be used for email delivery (
|
||||
see https://symfony.com/doc/current/components/mailer.html for full documentation). If you just want to use an SMTP
|
||||
|
|
@ -136,7 +157,7 @@ The following options are used to configure, which (and how much) data is writte
|
|||
If you want to use want to revert changes or view older revisions of entities,
|
||||
then `HISTORY_SAVE_CHANGED_FIELDS`, `HISTORY_SAVE_CHANGED_DATA` and `HISTORY_SAVE_REMOVED_DATA` all have to be true.
|
||||
|
||||
### Error pages settings
|
||||
### Error pages settings (all env only)
|
||||
|
||||
* `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)
|
||||
|
|
@ -151,7 +172,7 @@ then `HISTORY_SAVE_CHANGED_FIELDS`, `HISTORY_SAVE_CHANGED_DATA` and `HISTORY_SAV
|
|||
All parts in the selected category and all subcategories are shown in KiCad. Set this to a higher value, if you want to show more categories in KiCad.
|
||||
When you set this value to -1, all parts are shown inside a single category in KiCad.
|
||||
|
||||
### SAML SSO settings
|
||||
### SAML SSO settings (all env only)
|
||||
|
||||
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
|
||||
|
|
@ -199,26 +220,26 @@ See the [information providers]({% link usage/information_provider_system.md %})
|
|||
|
||||
### 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` (env only): 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).
|
||||
* `TRUSTED_HOSTS`: To prevent `HTTP Host header attacks` you can set a regex containing all host names via which Part-DB
|
||||
* `TRUSTED_HOSTS` (env only): 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.
|
||||
* `DEMO_MODE`: Set Part-DB into demo mode, which forbids users to change their passwords and settings. Used for the demo
|
||||
* `DEMO_MODE` (env only): Set Part-DB into demo mode, which forbids users to change their passwords and settings. Used for the demo
|
||||
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`) (env only): 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 does
|
||||
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` (env only): If this is set to true, all requests to http will be redirected to https. This is useful if your
|
||||
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.
|
||||
* `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
|
||||
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` (env only): 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!**)
|
||||
* `BANNER`: You can configure the text that should be shown as the banner on the homepage. Useful especially for docker
|
||||
containers. In all other applications you can just change the `config/banner.md` file.
|
||||
* `DISABLE_YEAR2038_BUG_CHECK`: If set to `1`, the year 2038 bug check is disabled on 32-bit systems, and dates after
|
||||
* `DISABLE_YEAR2038_BUG_CHECK` (env only): If set to `1`, the year 2038 bug check is disabled on 32-bit systems, and dates after
|
||||
2038 are no longer forbidden. However this will lead to 500 error messages when rendering dates after 2038 as all current
|
||||
32-bit PHP versions can not format these dates correctly. This setting is for the case that future PHP versions will
|
||||
handle this correctly on 32-bit systems. 64-bit systems are not affected by this bug, and the check is always disabled.
|
||||
|
|
@ -226,7 +247,7 @@ handle this correctly on 32-bit systems. 64-bit systems are not affected by this
|
|||
## Banner
|
||||
|
||||
To change the banner you can find on the homepage, you can either set the `BANNER` environment variable to the text you
|
||||
want to show, or you can edit the `config/banner.md` file. The banner is written in markdown, so you can use all
|
||||
want to show, or change it in the system settings webinterface. The banner is written in markdown, so you can use all
|
||||
markdown (and even some subset of HTML) syntax to format the text.
|
||||
|
||||
## parameters.yaml
|
||||
|
|
@ -241,8 +262,6 @@ command `bin/console cache:clear`.
|
|||
|
||||
The following options are available:
|
||||
|
||||
* `partdb.global_theme`: The default theme to use, when no user specific theme is set. Should be one of the themes from
|
||||
the `partdb.available_themes` config option.
|
||||
* `partdb.locale_menu`: The codes of the languages, which should be shown in the language chooser menu (the one with the
|
||||
user icon in the navbar). The first language in the list will be the default language.
|
||||
* `partdb.gdpr_compliance`: When set to true (default value), IP addresses which are saved in the database will be
|
||||
|
|
|
|||
|
|
@ -47,6 +47,12 @@ services:
|
|||
- DATABASE_URL=sqlite:///%kernel.project_dir%/var/db/app.db
|
||||
# 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
|
||||
# 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 environment variables
|
||||
# Below you can find the most essential ones predefined
|
||||
|
|
@ -130,28 +136,18 @@ services:
|
|||
# In docker env logs will be redirected to stderr
|
||||
- APP_ENV=docker
|
||||
|
||||
# You can configure Part-DB using environment variables
|
||||
# Below you can find the most essential ones predefined
|
||||
# Uncomment this, if you want to use the automatic database migration feature. With this you have 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
|
||||
# See .env file for all available options or https://docs.part-db.de/configuration.html
|
||||
|
||||
# The language to use serverwide as default (en, de, ru, etc.)
|
||||
- DEFAULT_LANG=en
|
||||
# The default timezone to use serverwide (e.g. Europe/Berlin)
|
||||
- DEFAULT_TIMEZONE=Europe/Berlin
|
||||
# The currency that is used inside the DB (and is assumed when no currency is set). This can not be changed later, so be sure to set it the currency used in your country
|
||||
- BASE_CURRENCY=EUR
|
||||
# The name of this installation. This will be shown as title in the browser and in the header of the website
|
||||
- INSTANCE_NAME=Part-DB
|
||||
|
||||
# Allow users to download attachments to the server by providing an URL
|
||||
# This could be a potential security issue, as the user can retrieve any file the server has access to (via internet)
|
||||
- ALLOW_ATTACHMENT_DOWNLOADS=0
|
||||
# Use gravatars for user avatars, when user has no own avatar defined
|
||||
- USE_GRAVATAR=0
|
||||
|
||||
# Override value if you want to show to show a given text on homepage.
|
||||
# When this is empty the content of config/banner.md is used as banner
|
||||
# When this is outcommented the webUI can be used to configure the banner
|
||||
#- BANNER=This is a test banner<br>with a line break
|
||||
|
||||
database:
|
||||
|
|
|
|||
|
|
@ -1,13 +1,13 @@
|
|||
---
|
||||
title: Direct Installation on Debian 11
|
||||
title: Direct Installation on Debian 12
|
||||
layout: default
|
||||
parent: Installation
|
||||
nav_order: 4
|
||||
---
|
||||
|
||||
# Part-DB installation guide for Debian 11 (Bullseye)
|
||||
# Part-DB installation guide for Debian 12 (Bookworm)
|
||||
|
||||
This guide shows you how to install Part-DB directly on Debian 11 using apache2 and SQLite. This guide should work with
|
||||
This guide shows you how to install Part-DB directly on Debian 12 using apache2 and SQLite. This guide should work with
|
||||
recent Ubuntu and other Debian-based distributions with little to no changes.
|
||||
Depending on what you want to do, using the prebuilt docker images may be a better choice, as you don't need to install
|
||||
this many dependencies. See [here]({% link installation/installation_docker.md %}) for more information on the docker
|
||||
|
|
@ -28,40 +28,32 @@ It is recommended to install Part-DB on a 64-bit system, as the 32-bit version o
|
|||
For the installation of Part-DB, we need some prerequisites. They can be installed by running the following command:
|
||||
|
||||
```bash
|
||||
sudo apt install git curl zip ca-certificates software-properties-common apt-transport-https lsb-release nano wget
|
||||
sudo apt update && apt upgrade
|
||||
sudo apt install git curl zip ca-certificates software-properties-common \
|
||||
apt-transport-https lsb-release nano wget sqlite3
|
||||
```
|
||||
|
||||
Please run `sqlite3 --version` to assert that the SQLite version is 3.35 or higher.
|
||||
Otherwise some database migrations will not succeed.
|
||||
|
||||
### Install PHP and apache2
|
||||
|
||||
Part-DB is written in [PHP](https://php.net) and therefore needs a PHP interpreter to run. Part-DB needs PHP 8.1 or
|
||||
Part-DB is written in [PHP](https://php.net) and therefore needs a PHP interpreter to run. Part-DB needs PHP 8.2 or
|
||||
higher. However, it is recommended to use the most recent version of PHP for performance reasons and future
|
||||
compatibility.
|
||||
|
||||
As Debian 11 does not ship PHP 8.1 in its default repositories, we have to add a repository for it. You can skip this
|
||||
step if your distribution is shipping a recent version of PHP or you want to use the built-in PHP version. If you are
|
||||
using Debian 12, you can skip this step, as PHP 8.1 is already included in the default repositories.
|
||||
Install PHP with required extensions and apache2:
|
||||
|
||||
```bash
|
||||
# Add sury repository for PHP 8.1
|
||||
sudo curl -sSL https://packages.sury.org/php/README.txt | sudo bash -x
|
||||
|
||||
# Update package list
|
||||
sudo apt update && sudo apt upgrade
|
||||
sudo apt install apache2 php8.2 libapache2-mod-php8.2 \
|
||||
php8.2-opcache php8.2-curl php8.2-gd php8.2-mbstring \
|
||||
php8.2-xml php8.2-bcmath php8.2-intl php8.2-zip php8.2-xsl \
|
||||
php8.2-sqlite3 php8.2-mysql
|
||||
```
|
||||
|
||||
Now you can install PHP 8.1 and the required packages (change the 8.1 in the package version according to the version you
|
||||
want to use):
|
||||
|
||||
```bash
|
||||
sudo apt install php8.1 libapache2-mod-php8.1 php8.1-opcache php8.1-curl php8.1-gd php8.1-mbstring php8.1-xml php8.1-bcmath php8.1-intl php8.1-zip php8.1-xsl php8.1-sqlite3 php8.1-mysql
|
||||
```
|
||||
|
||||
The apache2 webserver should be already installed with this command and configured basically.
|
||||
|
||||
### Install composer
|
||||
|
||||
Part-DB uses [composer](https://getcomposer.org/) to install required PHP libraries. As the version shipped in the
|
||||
repositories is pretty old, we will install it manually:
|
||||
Part-DB uses [composer](https://getcomposer.org/) to install required PHP libraries. Install the latest version manually:
|
||||
|
||||
```bash
|
||||
# Download composer installer script
|
||||
|
|
@ -78,10 +70,9 @@ To build the front end (the user interface) Part-DB uses [yarn](https://yarnpkg.
|
|||
shipped versions are pretty old, we install new versions from the official Node.js repository:
|
||||
|
||||
```bash
|
||||
# Add recent node repository (nodejs 18 is supported until 2025)
|
||||
curl -sL https://deb.nodesource.com/setup_18.x | sudo -E bash -
|
||||
# Install nodejs
|
||||
sudo apt install nodejs
|
||||
curl -fsSL https://deb.nodesource.com/setup_22.x | sudo -E bash -
|
||||
sudo apt install -y nodejs
|
||||
|
||||
```
|
||||
|
||||
We can install yarn with the following commands:
|
||||
|
|
@ -117,8 +108,8 @@ Alternatively, you can check out a specific version by running (
|
|||
see [GitHub Releases page](https://github.com/Part-DB/Part-DB-server/releases) for a list of available versions):
|
||||
|
||||
```bash
|
||||
# This checks out the version 1.5.2
|
||||
git checkout v1.5.2
|
||||
# This checks out the version 2.0.0
|
||||
git checkout v2.0.0
|
||||
```
|
||||
|
||||
Change ownership of the files to the apache user:
|
||||
|
|
@ -142,11 +133,10 @@ configuration:
|
|||
cp .env .env.local
|
||||
```
|
||||
|
||||
In your `.env.local` you can configure Part-DB according to your wishes. A full list of configuration options can be
|
||||
found [here](../configuration.md).
|
||||
Other configuration options like the default language or default currency can be found in `config/parameters.yaml`.
|
||||
In your `.env.local` you can configure Part-DB according to your wishes and overwrite web interface settings.
|
||||
A full list of configuration options can be found [here](../configuration.md).
|
||||
|
||||
Please check that the `partdb.default_currency` value in `config/parameters.yaml` matches your mainly used currency, as
|
||||
Please check that the configured base currency matches your mainly used currency, as
|
||||
this can not be changed after creating price information.
|
||||
|
||||
### Install dependencies for Part-DB and build frontend
|
||||
|
|
@ -256,6 +246,7 @@ network to point to the server).
|
|||
|
||||
Navigate to the Part-DB web interface and login via the user icon in the top right corner. You can log in using the
|
||||
username `admin` and the password you have written down earlier.
|
||||
As first steps, you should check out the system settings and check if everything is correct.
|
||||
|
||||
## Update Part-DB
|
||||
|
||||
|
|
@ -291,7 +282,7 @@ sudo -u www-data php bin/console cache:clear
|
|||
## MySQL/MariaDB database
|
||||
|
||||
To use a MySQL database, follow the steps from above (except the creation of the database, we will do this later).
|
||||
Debian 11 does not ship MySQL in its repositories anymore, so we use the compatible MariaDB instead:
|
||||
Debian 12 does not ship MySQL in its repositories anymore, so we use the compatible MariaDB instead:
|
||||
|
||||
1. Install maria-db with:
|
||||
|
||||
|
|
|
|||
|
|
@ -52,6 +52,11 @@ server {
|
|||
location ~ \.php$ {
|
||||
return 404;
|
||||
}
|
||||
|
||||
# Set Content-Security-Policy for svg files, to block embedded javascript in there
|
||||
location ~* \.svg$ {
|
||||
add_header Content-Security-Policy "default-src 'self'; script-src 'none'; style-src 'self' 'unsafe-inline'; img-src 'self' data:; frame-ancestors 'none';";
|
||||
}
|
||||
|
||||
error_log /var/log/nginx/parts.error.log;
|
||||
access_log /var/log/nginx/parts.access.log;
|
||||
|
|
|
|||
89
docs/upgrade/1_to_2.md
Normal file
89
docs/upgrade/1_to_2.md
Normal file
|
|
@ -0,0 +1,89 @@
|
|||
---
|
||||
layout: default
|
||||
title: Upgrade from Part-DB 1.x to 2.x
|
||||
nav_order: 1
|
||||
has_children: false
|
||||
parent: Upgrade
|
||||
---
|
||||
|
||||
# Upgrade from Part-DB 1.x to 2.x
|
||||
|
||||
Part-DB 2.0 is a major release that changes a lot of things internally, but it is still compatible with Part-DB 1.x.
|
||||
Depending on your preferences, you will have to do some changes to your Part-DB installation, this document will guide
|
||||
you through the upgrade process.
|
||||
|
||||
## New requirements
|
||||
*If you are running Part-DB inside a docker container, you can skip this section, as the new requirements are already
|
||||
fulfilled by the official Part-DB docker image.*
|
||||
|
||||
Part-DB 2.0 requires at least PHP 8.2 (newer versions are recommended). So if your existing Part-DB installation is still
|
||||
running PHP 8.1, you will have to upgrade your PHP version first.
|
||||
The minimum required version of node.js is now 20.0 or newer, so if you are using 18.0, you will have to upgrade it too.
|
||||
|
||||
Most distributions should have the possibility to get backports for PHP 8.4 and modern nodejs, so you should be able to
|
||||
easily upgrade your system to the new requirements. Otherwise, you can use the official Part-DB docker image, which
|
||||
ships all required dependencies and is always up to date with the latest requirements, so that you do not have to worry
|
||||
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
|
||||
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
|
||||
banner text, you will have to copy it from the `config/banner.md` file to the admin interface or set the `BANNER`
|
||||
environment variable.
|
||||
* The parameters `partdb.sidebar.items`, `partdb.sidebar.root_node_enable` and `partdb.sidebar.root_expanded` in `config/parameters.yaml`,
|
||||
were removed. You can configure them now directly in the admin interface.
|
||||
* Updated icon set. As fontawesome 7 is now used, some icons have changed slightly.
|
||||
|
||||
## Upgrade installation
|
||||
|
||||
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.**
|
||||
|
||||
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.
|
||||
2. Pull the v2 version. For git installation you can do this with `git checkout v2.0.0` (or newer version)
|
||||
3. Run `composer install --no-dev -o` to update the dependencies.
|
||||
4. Run `yarn install` and `yarn build` to update the frontend assets.
|
||||
5. Rund `php bin/console doctrine:migrations:migrate` to update the database schema.
|
||||
6. Clear the cache with `php bin/console cache:clear`.
|
||||
7. Open your Part-DB instance in the browser and log in as an admin user.
|
||||
8. Go to the user or group permissions page, and give yourself (and other administrators) the right to change system settings (under "System" and "Configuration").
|
||||
9. You can now go to the settings page (under "System" and "Settings") and check if all settings are correct.
|
||||
10. Parameters which were previously set via environment variables are greyed out and cannot be changed in the web interface.
|
||||
If you want to change them, you must migrate them to the settings interface as described below.
|
||||
|
||||
### Docker installation
|
||||
1. Make a backup of your existing Part-DB installation, including the database, data directories and the configuration files and the file where you configure the docker environment variables.
|
||||
2. Stop the existing Part-DB container with `docker compose down`
|
||||
3. Ensure that your docker compose file uses the new latest images (either `latest` or `2` tag).
|
||||
4. Pull the new images with `docker compose pull` and start the container with `docker compose up -d`
|
||||
5. If you have database automigration disabled, run `docker exec --user=www-data partdb php bin/console doctrine:migrations:migrate` to update the database schema.
|
||||
6. Open your Part-DB instance in the browser and log in as an admin user.
|
||||
7. Go to the user or group permissions page, and give yourself (and other administrators)
|
||||
the right to change system settings (under "System" and "Configuration").
|
||||
8. You can now go to the settings page (under "System" and "Settings")
|
||||
9. Parameters which were previously set via environment variables are greyed out and cannot be changed in the web interface.
|
||||
If you want to change them, you must migrate them to the settings interface as described below.
|
||||
|
||||
## Migrate environment variable configuration to settings interface
|
||||
As described above, configuration can now be done via the web interface, and can be overwritten by environment variables, so
|
||||
that existing configuration should still work. However, if a parameter is set via an environment variable, it cannot be changed in the web interface.
|
||||
To change it, you must migrate your environment variable configuration to the new system.
|
||||
|
||||
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.
|
||||
|
||||
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.
|
||||
|
||||
After the migration run successfully, the contents of your environment variables are now stored in the database and you can safely remove them from your environment variable configuration.
|
||||
Go through the environment variables listed by the command and remove them from your environment variable configuration (e.g. `.env.local` file or docker compose file), or just comment them out for now.
|
||||
|
||||
If you want to keep some environment variables, just leave them as they are, they will still work as before, the migration command only affects the settings stored in the database.
|
||||
9
docs/upgrade/index.md
Normal file
9
docs/upgrade/index.md
Normal file
|
|
@ -0,0 +1,9 @@
|
|||
---
|
||||
layout: default
|
||||
title: Upgrade
|
||||
nav_order: 7
|
||||
has_children: true
|
||||
---
|
||||
|
||||
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.
|
||||
|
|
@ -2,6 +2,8 @@
|
|||
layout: default
|
||||
title: Upgrade from legacy Part-DB version (<1.0)
|
||||
nav_order: 100
|
||||
redirect_from: /upgrade_legacy
|
||||
parent: Upgrade
|
||||
---
|
||||
|
||||
# Upgrade from legacy Part-DB version
|
||||
|
|
@ -16,8 +18,8 @@ sections carefully before proceeding to upgrade.
|
|||
|
||||
## Changes
|
||||
|
||||
* 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
|
||||
* PHP 8.2 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.2
|
||||
* **Console access is highly recommended.** The installation of composer and frontend dependencies require console access,
|
||||
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.
|
||||
|
|
@ -34,3 +34,12 @@ select the BOM file you want to import and some options for the import process:
|
|||
has a different format and does not work with this type.
|
||||
You can generate this BOM file by going to "File" -> "Fabrication Outputs" -> "Bill of Materials" in Pcbnew and save
|
||||
the file to your desired location.
|
||||
* **KiCAD Schematic BOM (CSV file)**: A CSV file of the Bill of Material (BOM) generated
|
||||
by [KiCAD Eeschema](https://www.kicad.org/).
|
||||
You can generate this BOM file by going to "Tools" -> "Generate Bill of Materials" in Eeschema and save the file to your
|
||||
desired location. In the next step you can customize the mapping of the fields in Part-DB, if you have any special fields
|
||||
in your BOM to locate your fields correctly.
|
||||
* **Generic CSV file**: A generic CSV file. You can use this option if you use some different ECAD software or wanna create
|
||||
your own CSV file. You will need to specify at least the designators, quantity and value fields in the CSV. In the next
|
||||
step you can customize the mapping of the fields in Part-DB, if you have any special fields in your BOM to locate your
|
||||
parts correctly.
|
||||
|
|
|
|||
|
|
@ -66,8 +66,16 @@ docker exec --user=www-data partdb php bin/console cache:clear
|
|||
* `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
|
||||
deleted!*
|
||||
* `settings:migrate-env-to-settings`: Migrate configuration from environment variables to the settings interface.
|
||||
The value of the environment variable is copied to the settings database, so the environment variable can be removed afterwards without losing the configuration.
|
||||
|
||||
## Database commands
|
||||
|
||||
* `php bin/console doctrine:migrations:migrate`: Migrate the database to the latest version
|
||||
* `php bin/console doctrine:migrations:up-to-date`: Check if the database is up-to-date
|
||||
|
||||
## 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
|
||||
|
|
|
|||
|
|
@ -12,11 +12,19 @@ Before starting, it's useful to read a bit about the [concepts of Part-DB]({% li
|
|||
1. TOC
|
||||
{:toc}
|
||||
|
||||
## Customize config files
|
||||
## Customize system settings
|
||||
|
||||
Before you start creating data structures, you should configure Part-DB to your needs by changing possible configuration
|
||||
options.
|
||||
This is done either via changing the `.env.local` file in a direct installation or by changing the env variables in
|
||||
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`.
|
||||
|
||||
|
||||
Here you can change various settings, like the name of your Part-DB instance (which is shown in the title bar of the
|
||||
browser), the default language (which is used if no user preference is set), the default timezone (which is used to
|
||||
display times correctly), the default currency (which is used to display prices correctly), and many more.
|
||||
|
||||
Some more fundamental settings like database connection, mail server settings, SSO, etc. are configured via environment variables.
|
||||
Environment variables also allow to overwrite various settings from the web interface.
|
||||
Environment variables can be changed by editing the `.env.local` file in a direct installation or by changing the env variables in
|
||||
your `docker-compose.yaml` file.
|
||||
A list of possible configuration options can be found [here]({% link configuration.md %}).
|
||||
|
||||
|
|
@ -44,8 +52,8 @@ used.
|
|||
|
||||
## (Optional) Customize homepage banner
|
||||
|
||||
The banner which is shown on the homepage, can be customized/changed by changing the `config/banner.md` file with a text
|
||||
editor. You can use markdown and (safe) HTML here, to style and customize the banner.
|
||||
The banner which is shown on the homepage, can be customized/changed via the homepage banner setting in system settings.
|
||||
You can use markdown and (safe) HTML here, to style and customize the banner.
|
||||
You can even use LaTeX-style equations by wrapping the expressions into `$` (like `$E=mc^2$`, which is rendered inline:
|
||||
$E=mc^2$) or `$$` (like `$$E=mc^2$$`) which will be rendered as a block, like so: $$E=mc^2$$
|
||||
|
||||
|
|
@ -202,4 +210,4 @@ 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
|
||||
usage/tips_tricks.md %}) for more information.
|
||||
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_legacy.md %}).
|
||||
upgrade/upgrade_legacy.md %}).
|
||||
|
||||
### Import parts
|
||||
|
||||
|
|
@ -158,4 +158,4 @@ information, this can lead to very large export files.
|
|||
You can export parts in all part tables. Select the parts you want via the checkbox in the table line and select the
|
||||
export format and level in the appearing menu.
|
||||
|
||||
See the section about exporting data structures for more information about the export formats and levels.
|
||||
See the section about exporting data structures for more information about the export formats and levels.
|
||||
|
|
|
|||
|
|
@ -80,6 +80,11 @@ Normally the providers utilize an API of a service, and you need to create an ac
|
|||
Also, there are limits on how many requests you can do per day or month, depending on the provider and your contract
|
||||
with them.
|
||||
|
||||
Data providers can be either configured in the system settings (in the info provider tab) or on the settings page which is
|
||||
reachable via the cogwheel symbol next to the provider in the provider list. It is also possible to configure them via
|
||||
environment variables. See below for the available configuration options. API keys configured via environment variables
|
||||
are redacted in the settings interface.
|
||||
|
||||
The following providers are currently available and shipped with Part-DB:
|
||||
|
||||
(All trademarks are property of their respective owners. Part-DB is not affiliated with any of the companies.)
|
||||
|
|
@ -127,9 +132,6 @@ You must create an organization there and create a "Production app". Most settin
|
|||
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).
|
||||
|
||||
**Attention**: Currently only the "Product Information V3 (Deprecated)" is supported by Part-DB.
|
||||
Using "Product Information V4" will not work.
|
||||
|
||||
The following env configuration options are available:
|
||||
|
||||
* `PROVIDER_DIGIKEY_CLIENT_ID`: The client ID you got from Digi-Key (mandatory)
|
||||
|
|
|
|||
|
|
@ -95,4 +95,9 @@ It is only be shown to users which has the `Show available Part-DB updates` perm
|
|||
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).
|
||||
If you don't want Part-DB to query the GitHub API, or if your server can not reach the internet, you can disable the
|
||||
update notifications by setting the `CHECK_FOR_UPDATES` option to `false`.
|
||||
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
|
||||
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