mirror/Part-DB.Part-DB-server
1
0
Fork 1
mirror of https://github.com/Part-DB/Part-DB-server.git synced 2025-07-15 04:44:36 +02:00
Code Issues Projects Releases Packages Wiki Activity Actions 5

Fixed formatting and typos in documentation

Browse source
This commit is contained in:
Jan Böhmer 2023-10-15 13:21:14 +02:00
parent 47fc7db953
commit f32c0f52b6
24 changed files with 1512 additions and 730 deletions
Download patch file Download diff file Expand all files Collapse all files

34
docs/installation/choosing_database.md
View file

@ -7,24 +7,38 @@ nav_order: 1
# Choosing database: SQLite or MySQL
Part-DB saves its data in a [relational (SQL) database](https://en.wikipedia.org/wiki/Relational_database). Part-DB supports either the use of [SQLite](https://www.sqlite.org/index.html) or [MySQL](https://www.mysql.com/) / [MariaDB](https://mariadb.org/) (which are mostly the same, except for some minor differences).
Part-DB saves its data in a [relational (SQL) database](https://en.wikipedia.org/wiki/Relational_database). Part-DB
supports either the use of [SQLite](https://www.sqlite.org/index.html)
or [MySQL](https://www.mysql.com/) / [MariaDB](https://mariadb.org/) (which are mostly the same, except for some minor
differences).
{: .important }
You have to choose between the database types before you start using Part-DB and **you can not change it (easily) after you have started creating data**. So you should choose the database type for your usecase (and possible future uses).
You have to choose between the database types before you start using Part-DB and **you can not change it (easily) after
you have started creating data**. So you should choose the database type for your use case (and possible future uses).
## Comparison
**SQLite** is the default database type which is configured out of the box. All data is saved in a single file (normally `var/app.db` in the Part-DB folder) and no additional installation or configuration besides Part-DB is needed.
To use **MySQL/MariaDB** as database, you have to install and configure the MySQL server, configure it and create a database and user for Part-DB, which needs some additional work. When using docker you need an additional docker container, and volume for the data
**SQLite** is the default database type which is configured out of the box. All data is saved in a single file (
normally `var/app.db` in the Part-DB folder) and no additional installation or configuration besides Part-DB is needed.
To use **MySQL/MariaDB** as database, you have to install and configure the MySQL server, configure it and create a
database and user for Part-DB, which needs some additional work. When using docker you need an additional docker
container, and volume for the data
When using **SQLite** The database can be backuped easily by just copying the SQLite file to a safe place. Ideally the **MySQL** database has to be dumped to a SQL file (using `mysqldump`). The `console partdb:backup` command can do this automatically
However SQLite does not support certain operations like regex search, which has to be emulated by PHP and therefore are pretty slow compared to the same operation at MySQL. In future there might be features that may only be available, when using MySQL.
When using **SQLite** The database can be backuped easily by just copying the SQLite file to a safe place. Ideally the *
*MySQL** database has to be dumped to a SQL file (using `mysqldump`). The `console partdb:backup` command can do this
automatically
In general MySQL might perform better for big Part-DB instances with many entries, lots of users and high activity, than SQLite.
However, SQLite does not support certain operations like regex search, which has to be emulated by PHP and therefore are
pretty slow compared to the same operation at MySQL. In future there might be features that may only be available, when
using MySQL.
In general MySQL might perform better for big Part-DB instances with many entries, lots of users and high activity, than
SQLite.
## Conclusion and Suggestion
When you are a hobbyist and use Part-DB for your own small inventory managment with only you as user (or maybe sometimes a few other people), then the easy to use SQLite database will be fine.
When you are a hobbyist and use Part-DB for your own small inventory management with only you as user (or maybe sometimes
a few other people), then the easy-to-use SQLite database will be fine.
When you are planning to have a very big database, with a lot of entries and many users which regulary (and concurrently) using Part-DB you should maybe use MySQL as this will scale better.
When you are planning to have a very big database, with a lot of entries and many users which regularly (and
concurrently) using Part-DB you should maybe use MySQL as this will scale better.

23
docs/installation/email.md
View file

@ -7,31 +7,34 @@ nav_order: 12
# Email
Part-DB can communicate with its users via email.
Part-DB can communicate with its users via email.
At the moment this is only used to send password reset links, but in future this will be used for other things too.
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 Mailer documentation for more information.
We will only cover the configuration of a SMTP provider here, which is sufficient for most usecases.
You will need an email account, which you can use send emails from via password-bases SMTP authentication, this account
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
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
should be dedicated to Part-DB.
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 the following:
`smtp://<username>:<password>@<smtp-server-address>:<port>`. In most cases the username is the email address of the account, and the port is 587.
`MAILER_DSN`: You have to provide the SMTP server address and the credentials for the email account here. The format is
the following:
`smtp://<username>:<password>@<smtp-server-address>:<port>`. In most cases the username is the email address of the
account, and the port is 587.
So the resulting DSN could look like this: `smtp://j.doe@mail.invalid:SUPER_SECRET_PA$$WORD@smtp.mail.invalid:587`.
`EMAIL_SENDER_EMAIL`: This is the email address which will be used as sender address for all emails sent by Part-DB.
This should be the same email address as the one used in the `MAILER_DSN` (the email adress of your email account):
This should be the same email address as the one used in the `MAILER_DSN` (the email address of your email account):
e.g. `j.doe@mail.invalid`.
`EMAIL_SENDER_NAME`: This is the name which will be used as sender name for all emails sent by Part-DB.
`EMAIL_SENDER_NAME`: This is the name which will be used as sender name for all emails sent by Part-DB.
This can be anything you want, e.g. `My Part-DB Mailer`.
Now you can enable the possibility to reset password by setting the `ALLOW_EMAIL_PW_RESET` env to `1` (or `true`).

51
docs/installation/installation_docker.md
View file

@ -7,17 +7,18 @@ nav_order: 2
# Installation of Part-DB via docker
Part-DB can be installed containerized via docker. This is the easiest way to get Part-DB up and running and works on all platforms,
where docker is available (especially recommended for Windows and MacOS).
Part-DB can be installed containerized via docker. This is the easiest way to get Part-DB up and running and works on
all platforms,
where docker is available (especially recommended for Windows and macOS).
{: .warning }
> The methods described here, configure PHP without HTTPS and therefore should only be used locally in a trusted network.
> The methods described here, configure PHP without HTTPS and therefore should only be used locally in a trusted
> network.
> If you want to expose Part-DB to the internet, you have to configure a reverse proxy with an SSL certificate!
## Docker-compose
Docker-compose configures the needed images and automatically creates the needed containers and volumes.
Docker-compose configures the needed images and automatically creates the needed containers and volumes.
1. Install docker and docker-compose like described under https://docs.docker.com/compose/install/
2. Create a folder where the Part-DB data should live
@ -68,19 +69,28 @@ services:
# When this is empty the content of config/banner.md is used as banner
#- BANNER=This is a test banner<br>with a line break
```
4. Customize the settings by changing the environment variables (or add new ones). See [Configuration]({% link configuration.md %}) for more information.
4. Customize the settings by changing the environment variables (or add new ones). See [Configuration]({% link
configuration.md %}) for more information.
5. Inside the folder, run
```bash
docker-compose up -d
```
6. Create the inital database with
6. Create the initial database with
```bash
docker exec --user=www-data partdb php bin/console doctrine:migrations:migrate
```
and watch for the password output
6. Part-DB is available under `http://localhost:8080` and you can log in with username `admin` and the password shown before
The docker image uses a SQLite database and all data (database, uploads and other media) is put into folders relative to the docker-compose.yml.
and watch for the password output
6. Part-DB is available under `http://localhost:8080` and you can log in with username `admin` and the password shown
before
The docker image uses a SQLite database and all data (database, uploads and other media) is put into folders relative to
the docker-compose.yml.
### MySQL
@ -156,8 +166,10 @@ services:
```
### Update Part-DB
You can update Part-DB by pulling the latest image and restarting the container.
Then you have to run the database migrations again
```bash
docker-compose pull
docker-compose up -d
@ -165,19 +177,26 @@ docker exec --user=www-data partdb php bin/console doctrine:migrations:migrate
```
## Direct use of docker image
You can use the `jbtronics/part-db1:master` image directly. You have to expose the port 80 to a host port and configure volumes for `/var/www/html/uploads` and `/var/www/html/public/media`.
If you want to use SQLite database (which is default), you have to configure Part-DB to put the database file in a mapped volume via the `DATABASE_URL` environment variable.
For example if you set `DATABASE_URL=sqlite:///%kernel.project_dir%/var/db/app.db` then you will have to map the `/var/www/html/var/db/` folder to the docker container (see docker-compose.yaml for example).
You can use the `jbtronics/part-db1:master` image directly. You have to expose the port 80 to a host port and configure
volumes for `/var/www/html/uploads` and `/var/www/html/public/media`.
If you want to use SQLite database (which is default), you have to configure Part-DB to put the database file in a
mapped volume via the `DATABASE_URL` environment variable.
For example if you set `DATABASE_URL=sqlite:///%kernel.project_dir%/var/db/app.db` then you will have to map
the `/var/www/html/var/db/` folder to the docker container (see docker-compose.yaml for example).
You also have to create the database like described above in step 4.
## Running console commands
You can run the console commands described in README by executing `docker exec --user=www-data -it partdb bin/console [command]`
You can run the console commands described in README by
executing `docker exec --user=www-data -it partdb bin/console [command]`
## Troubleshooting
*Login not possible. Login page is just reloading and no error message is shown or something like "CSFR token invalid"*:
Clear all cookies in your browser or use a inkognito tab for Part-DB.
This related to the fact that Part-DB can not set cookies via HTTP, after some webpage has set cookies before under localhost via https. This is a security mechanism of the browser and can not be bypassed by Part-DB.
Clear all cookies in your browser or use an inkognito tab for Part-DB.
This related to the fact that Part-DB can not set cookies via HTTP, after some webpage has set cookies before under
localhost via https. This is a security mechanism of the browser and can not be bypassed by Part-DB.

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

@ -6,25 +6,38 @@ nav_order: 4
---
# Part-DB installation guide for Debian 11 (Bullseye)
This guide shows you how to install Part-DB directly on Debian 11 using apache2 and SQLite. This guide should work with recent Ubuntu and other Debian based distributions with little to no changes.
Depending on what you want to do, using the prebuilt docker images may be a better choice, as you dont need to install this much dependencies. See **TODO** for more information of the docker installation.
This guide shows you how to install Part-DB directly on Debian 11 using apache2 and SQLite. This guide should work with
recent Ubuntu and other Debian based distributions with little to no changes.
Depending on what you want to do, using the prebuilt docker images may be a better choice, as you don't need to install
this many dependencies. See [here]({% link installation/installation_docker.md %}) for more information of the docker
installation.
{: .warning }
> The methods described here, configure PHP without HTTPS and therefore should only be used locally in a trusted network.
> The methods described here, configure PHP without HTTPS and therefore should only be used locally in a trusted
> network.
> If you want to expose Part-DB to the internet, you HAVE to configure an SSL connection!
## Installation with SQLite database
### Install prerequisites
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
```
### Install PHP and apache2
Part-DB is written in [PHP](https://php.net) and therefore needs an PHP interpreter to run. Part-DB needs PHP 8.1 or higher, however it is recommended to use the most recent version of PHP for performance reasons and future compatibility.
As Debian 11 does not ship PHP 8.1 in it's 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.
Part-DB is written in [PHP](https://php.net) and therefore needs an PHP interpreter to run. Part-DB needs PHP 8.1 or
higher, however it is recommended to use the most recent version of PHP for performance reasons and future
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.
```bash
# Add sury repository for PHP 8.1
sudo curl -sSL https://packages.sury.org/php/README.txt | sudo bash -x
@ -32,14 +45,21 @@ sudo curl -sSL https://packages.sury.org/php/README.txt | sudo bash -x
# Update package list
sudo apt update && sudo apt upgrade
```
Now you can install PHP 8.1 and required packages (change the 8.1 in the package version according to the version you want to use):
Now you can install PHP 8.1 and 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 versions shipped in the repositories is pretty old we install it manually:
Part-DB uses [composer](https://getcomposer.org/) to install required PHP libraries. As the versions shipped in the
repositories is pretty old we install it manually:
```bash
# Download composer installer script
wget -O /tmp/composer-setup.php https://getcomposer.org/installer
@ -50,7 +70,10 @@ chmod +x /usr/local/bin/composer
```
### Install yarn and nodejs
To build the frontend (the user interface) Part-DB uses [yarn](https://yarnpkg.com/). As it dependens on nodejs and the shipped versions are pretty old, we install new versions from offical nodejs repository:
To build the frontend (the user interface) Part-DB uses [yarn](https://yarnpkg.com/). As it depends on Node.js and the
shipped versions are pretty old, we install new versions from official Node.js repository:
```bash
# Add recent node repository (nodejs 18 is supported until 2025)
curl -sL https://deb.nodesource.com/setup_18.x | sudo -E bash -
@ -59,6 +82,7 @@ sudo apt install nodejs
```
We can install yarn with the following commands:
```bash
# Add yarn repository
curl -sL https://dl.yarnpkg.com/debian/pubkey.gpg | gpg --dearmor | sudo tee /usr/share/keyrings/yarnkey.gpg >/dev/null
@ -68,46 +92,64 @@ sudo apt update && sudo apt install yarn
```
### Create a folder for Part-DB and download it
We now have all prerequisites installed and can start to install Part-DB. We will create a folder for Part-DB in a webfolder of apache2 and download it to this folder. The downloading is done via git, which allows you to update easily later.
We now have all prerequisites installed and can start to install Part-DB. We will create a folder for Part-DB in the
webroot of apache2 and download it to this folder. The downloading is done via git, which allows you to update easily
later.
```bash
# Download Part-DB into the new folder /var/www/partdb
git clone https://github.com/Part-DB/Part-DB-symfony.git /var/www/partdb
```
By default you are now on the latest development version. In most cases you want to use the latest stable version. You can switch to the latest stable version (tagged) by running the following command:
By default, you are now on the latest development version. In most cases you want to use the latest stable version. You
can switch to the latest stable version (tagged) by running the following command:
```bash
# This finds the latest release/tag and checks it out
git checkout $(git describe --tags $(git rev-list --tags --max-count=1))
```
Alternatively you can checkout a specific version by running (see [GitHub Relases page](https://github.com/Part-DB/Part-DB-server/releases) for a list of available versions):
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
```
Change ownership of the files to the apache user:
```bash
chown -R www-data:www-data /var/www/partdb
```
For the next steps we should be in the Part-DB folder, so move into it:
```bash
cd /var/www/partdb
```
### Create configuration for Part-DB
The basic configuration of Part-DB is done by a `.env.local` file in the main directory. Create on by from the default configuration:
The basic configuration of Part-DB is done by a `.env.local` file in the main directory. Create on by from the default
configuration:
```bash
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).
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`.
Please check that the `partdb.default_currency` value in `config/parameters.yaml` matches your mainly used currency, as this can not be changed after creating price informations.
Please check that the `partdb.default_currency` value in `config/parameters.yaml` matches your mainly used currency, as
this can not be changed after creating price information.
### Install dependencies for Part-DB and build frontend
Part-DB depends on several other libraries and components. Install them by running the following commands:
```bash
# Install composer dependencies (please note the sudo command, to run it under the web server user)
sudo -u www-data composer install --no-dev -o
@ -121,32 +163,48 @@ sudo yarn build
### Clear cache
To ensure everything is working, clear the cache:
```bash
sudo -u www-data php bin/console cache:clear
```
### Check if everything is installed
To check if everything is installed, run the following command:
```bash
sudo -u www-data php bin/console partdb:check-requirements
```
The most things should be green, and no red ones. Yellow messages means optional dependencies which are not important but can improve performance and functionality.
The most things should be green, and no red ones. Yellow messages means optional dependencies which are not important
but can improve performance and functionality.
### Create a database for Part-DB
Part-DB by default uses a file based sqlite database to store the data. Use the following command to create the database. The database will normally created at `/var/www/partdb/var/app.db`.
Part-DB by default uses a file based sqlite database to store the data. Use the following command to create the
database. The database will normally be created at `/var/www/partdb/var/app.db`.
```bash
sudo -u www-data php bin/console doctrine:migrations:migrate
```
The command will warn you about schema changes and potential data loss. Continue with typing `yes`.
The command will output several lines of informations. Somewhere should be a a yellow background message like `The initial password for the "admin" user is: f502481134`. Write down this password as you will need it later for inital login.
The command will output several lines of information. Somewhere should be a yellow background message
like `The initial password for the "admin" user is: f502481134`. Write down this password as you will need it later for
initial login.
### Configure apache2 to show Part-DB
Part-DB is now configured, but we have to say apache2 to serve Part-DB as web application. This is done by creating a new apache site:
Part-DB is now configured, but we have to say apache2 to serve Part-DB as web application. This is done by creating a
new apache site:
```bash
sudo nano /etc/apache2/sites-available/partdb.conf
```
and add the following content (change ServerName and ServerAlias to your needs):
```
<VirtualHost *:80>
ServerName partdb.lan
@ -163,33 +221,44 @@ and add the following content (change ServerName and ServerAlias to your needs):
CustomLog /var/log/apache2/partdb_access.log combined
</VirtualHost>
```
Activate the new site by:
```bash
sudo ln -s /etc/apache2/sites-available/partdb.conf /etc/apache2/sites-enabled/partdb.conf
```
Configure apache to show pretty URL pathes for Part-DB (`/label/dialog` instead of `/index.php/label/dialog`):
Configure apache to show pretty URL paths for Part-DB (`/label/dialog` instead of `/index.php/label/dialog`):
```bash
sudo a2enmod rewrite
```
If you want to access Part-DB via the IP-Address of the server, instead of the domain name, you have to remove the apache2 default configuration with:
If you want to access Part-DB via the IP-Address of the server, instead of the domain name, you have to remove the
apache2 default configuration with:
```bash
sudo rm /etc/apache2/sites-enabled/000-default.conf
```
Restart the apache2 webserver with:
```bash
sudo service apache2 restart
```
and Part-DB should now be available under `http://YourServerIP` (or `http://partdb.lan` if you configured DNS in your network to point on the server).
and Part-DB should now be available under `http://YourServerIP` (or `http://partdb.lan` if you configured DNS in your
network to point on the server).
### Login to Part-DB
Navigate to the Part-DB web interface and login via the user icon in the top right corner. You can login using the username `admin` and the password you have written down earlier.
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.
## Update Part-DB
If you want to update your existing Part-DB installation, you just have to run the following commands:
```bash
# Move into Part-DB folder
cd /var/www/partdb
@ -218,6 +287,7 @@ sudo -u www-data php bin/console cache:clear
```
## MySQL/MariaDB database
To use a MySQL database, follow the steps from above (except the creation of database, we will do this later).
Debian 11 does not ship MySQL in its repositories anymore, so we use the compatible MariaDB instead:
@ -228,9 +298,11 @@ sudo apt update && sudo apt install mariadb-server
```
2. Configure maria-db with:
```bash
sudo mysql_secure_installation
```
When asked for the root password, just press enter, as we have not set a root password yet.
In the next steps you are asked if you want to switch to unix_socket authentication, answer with `n` and press enter.
Then you are asked if you want to remove anonymous users, answer with `y` and press enter.
@ -239,33 +311,42 @@ Then you are asked if you want to remove the test database and access to it, ans
Then you are asked if you want to reload the privilege tables now, answer with `y` and press enter.
3. Create a new database and user for Part-DB: Run the following commands:
```bash
sudo mariadb
```
A SQL shell will open, in which you can run the following commands to create a new database and user for Part-DB.
Replace 'YOUR_SECRET_PASSWORD' with a secure password.
```sql
CREATE DATABASE partdb;
GRANT ALL PRIVILEGES ON partdb.* TO 'partdb'@'localhost' IDENTIFIED BY 'YOUR_SECRET_PASSWORD';
```
Finally save the changes with:
Finally, save the changes with:
```sql
FLUSH PRIVILEGES;
```
and exit the SQL shell with:
```sql
exit
```
4. Configure Part-DB to use the new database. Open your `.env.local` file and search the line `DATABASE_URL`.
Change it to the following (you have to replace `YOUR_SECRET_PASSWORD` with the password you have choosen in step 3):
Change it to the following (you have to replace `YOUR_SECRET_PASSWORD` with the password you have chosen in step 3):
```
DATABASE_URL=DATABASE_URL=mysql://partdb:YOUR_SECRET_PASSWORD@127.0.0.1:3306/partdb
```
5. Create the database schema with:
```bash
sudo -u www-data php bin/console doctrine:migrations:migrate
```
6. The migration step should have shown you a password for the admin user, which you can use now to login to Part-DB.
6. The migration step should have shown you a password for the admin user, which you can use now to log in to Part-DB.

10
docs/installation/nginx.md
View file

@ -6,14 +6,18 @@ 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
this is the method shown in the guides. This guide assumes that you already have a working nginx installation with PHP
configured.
## Setup
1. Install composer and yarn like described in the [apache guide]({% link installation/installation_guide-debian.md %}#install-composer).
1. Install composer and yarn like described in the [apache guide]({% link installation/installation_guide-debian.md
%}#install-composer).
2. Create a folder for Part-DB and install and configure it as described
3. Instead of creating the config for apache, add the following snippet to your nginx config:
```nginx
server {
# Redirect all HTTP requests to HTTPS
@ -64,4 +68,6 @@ server {
ssl_prefer_server_ciphers on;
}
```
4. Restart nginx with `sudo systemctl restart nginx` and you should be able to access Part-DB under your configured domain.
4. Restart nginx with `sudo systemctl restart nginx` and you should be able to access Part-DB under your configured
domain.

10
docs/installation/reverse-proxy.md
View file

@ -9,13 +9,15 @@ nav_order: 11
If you want to put Part-DB behind a reverse proxy, you have to configure Part-DB correctly to make it work properly.
You have to set the `TRUSTED_PROXIES` environment variable to the IP address of your reverse proxy
(either in your `docker-compose.yaml` in the case of docker, or `.env.local` in case of direct installation).
You have to set the `TRUSTED_PROXIES` environment variable to the IP address of your reverse proxy
(either in your `docker-compose.yaml` in the case of docker, or `.env.local` in case of direct installation).
If you have multiple reverse proxies, you can set multiple IP addresses separated by a comma (or specify a range).
For example, if your reverse proxy has the IP address `192.168.2.10`, your value should be:
For example, if your reverse proxy has the IP address `192.168.2.10`, your value should be:
```
TRUSTED_PROXIES=192.168.2.10
```
Set the `DEFAULT_URI` environment variable to the URL of your Part-DB installation, available from the outside (so via the reverse proxy).
Set the `DEFAULT_URI` environment variable to the URL of your Part-DB installation, available from the outside (so via
the reverse proxy).

198
docs/installation/saml_sso.md
View file

@ -7,42 +7,55 @@ nav_order: 12
# Single Sign-On via SAML
Part-DB supports Single Sign-On via SAML. This means that you can use your existing SAML identity provider to log in to Part-DB.
Using an intermediate SAML server like [Keycloak](https://www.keycloak.org/), also allows you to connect Part-DB to a LDAP or Active Directory server.
Part-DB supports Single Sign-On via SAML. This means that you can use your existing SAML identity provider to log in to
Part-DB.
Using an intermediate SAML server like [Keycloak](https://www.keycloak.org/), also allows you to connect Part-DB to an
LDAP or Active Directory server.
{: .important }
> This feature is for advanced users only. Single Sign-On is useful for large organizations with many users, which are already using SAML for other services.
> This feature is for advanced users only. Single Sign-On is useful for large organizations with many users, which are
> already using SAML for other services.
> If you have only one or a few users, you should use the built-in authentication system of Part-DB.
> This guide assumes that you already have an SAML identity provider set up and working, and have a basic understanding of how SAML works.
> This guide assumes that you already have an SAML identity provider set up and working, and have a basic understanding
> of how SAML works.
{: .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.
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.
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.
This guide assumes that you have a working Keycloak installation with some users. If you don't, you can follow the [Keycloak Getting Started Guide](https://www.keycloak.org/docs/latest/getting_started/index.html).
This guide assumes that you have a working Keycloak installation with some users. If you don't, you can follow
the [Keycloak Getting Started Guide](https://www.keycloak.org/docs/latest/getting_started/index.html).
{: .important }
> Part-DB associates local users with SAML users by their username. That means if the username of a SAML user changes, a new local user will be created (and the old account can not be accessed).
> You should make sure that the username of a SAML user does not change. If you use Keycloak make sure that the possibility to change the username is disabled (which is by default).
> If you really have to rename a SAML user, a Part-DB admin can rename the local user in the Part-DB in the admin panel, to match the new username of the SAML user.
> Part-DB associates local users with SAML users by their username. That means if the username of a SAML user changes, a
> new local user will be created (and the old account can not be accessed).
> You should make sure that the username of a SAML user does not change. If you use Keycloak make sure that the
> possibility to change the username is disabled (which is by default).
> If you really have to rename a SAML user, a Part-DB admin can rename the local user in the Part-DB in the admin panel,
> to match the new username of the SAML user.
## Configure basic SAML connection
### Create a new SAML client
1. First, you need to configure a new SAML client in Keycloak. Login in to your Keycloak admin console and go to the `Clients` page.
2. Click on `Create client` and select `SAML` as type from the dropdown menu. For the client ID, you can use anything you want, but it should be unique.
*It is recommended to set this value to the domain name of your Part-DB installation, with an attached `/sp` (e.g. `https://partdb.yourdomain.invalid/sp`)*.
The name field should be set to something human-readable, like `Part-DB`.
1. First, you need to configure a new SAML client in Keycloak. Login in to your Keycloak admin console and go to
the `Clients` page.
2. Click on `Create client` and select `SAML` as type from the dropdown menu. For the client ID, you can use anything
you want, but it should be unique.
*It is recommended to set this value to the domain name of your Part-DB installation, with an attached `/sp` (
e.g. `https://partdb.yourdomain.invalid/sp`)*.
The name field should be set to something human-readable, like `Part-DB`.
3. Click on `Save` to create the new client.
### Configure the SAML client
1. Now you need to configure the SAML client. Go to the `Settings` tab and set the following values:
* Set `Home URL` to the homepage of your Part-DB installation (e.g. `https://partdb.yourdomain.invalid/`).
* Set `Valid redirect URIs` to your homepage with a wildcard at the end (e.g. `https://partdb.yourdomain.invalid/*`).
* Set `Valid redirect URIs` to your homepage with a wildcard at the end (
e.g. `https://partdb.yourdomain.invalid/*`).
* Set `Valid post logout redirect URIs` to `+` to allow all urls from the `Valid redirect URIs`.
* Set `Name ID format` to `username`
* Ensure `Force POST binding` is enabled.
@ -52,30 +65,47 @@ The name field should be set to something human-readable, like `Part-DB`.
Click on `Save` to save the changes.
2. Go to the `Advanced` tab and set the following values:
* Assertion Consumer Service POST Binding URL to your homepage with `/saml/acs` at the end (e.g. `https://partdb.yourdomain.invalid/saml/acs`).
* Logout Service POST Binding URL to your homepage with `/logout` at the end (e.g. `https://partdb.yourdomain.invalid/logout`).
* Assertion Consumer Service POST Binding URL to your homepage with `/saml/acs` at the end (
e.g. `https://partdb.yourdomain.invalid/saml/acs`).
* Logout Service POST Binding URL to your homepage with `/logout` at the end (
e.g. `https://partdb.yourdomain.invalid/logout`).
3. Go to Keys tab and ensure `Client Signature Required` is enabled.
4. In the Keys tab click on `Generate new keys`. This will generate a new key pair for the SAML client. The private key will be downloaded to your computer.
4. In the Keys tab click on `Generate new keys`. This will generate a new key pair for the SAML client. The private key
will be downloaded to your computer.
### 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 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 `=`.
4. Set the `SAML_SP_ENTITY_ID` environment variable to the entityID of the SAML client in Keycloak (e.g. `https://partdb.yourdomain.invalid/sp`).
5. In Keycloak navigate to `Realm Settings` -> `SAML 2.0 Identity Provider` (by default something like `https://idp.yourdomain.invalid/realms/master/protocol/saml/descriptor) to show the SAML metadata.
6. Copy the `entityID` value from the metadata to the `SAML_IDP_ENTITY_ID` configuration variable of Part-DB (by default something like `https://idp.yourdomain.invalid/realms/master`).
7. Copy the `Single Sign-On Service` value from the metadata to the `SAML_IDP_SINGLE_SIGN_ON_SERVICE` configuration variable of Part-DB (by default something like `https://idp.yourdomain.invalid/realms/master/protocol/saml`).
8. Copy the `Single Logout Service` value from the metadata to the `SAML_IDP_SINGLE_LOGOUT_SERVICE` configuration variable of Part-DB (by default something like `https://idp.yourdomain.invalid/realms/master/protocol/saml/logout`).
9. Copy the `X.509 Certificate` value from the metadata to the `SAML_IDP_X509_CERT` configuration variable of Part-DB (it should start with `MIIC` and should be pretty long).
10. Set the `DEFAULT_URI` to the homepage (on the publicly available domain) of your Part-DB installation (e.g. `https://partdb.yourdomain.invalid/`). It must end with a slash.
2. Set the `SAMLP_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 `=`.
4. Set the `SAML_SP_ENTITY_ID` environment variable to the entityID of the SAML client in Keycloak (
e.g. `https://partdb.yourdomain.invalid/sp`).
5. In Keycloak navigate to `Realm Settings` -> `SAML 2.0 Identity Provider` (by default something
like `https://idp.yourdomain.invalid/realms/master/protocol/saml/descriptor) to show the SAML metadata.
6. Copy the `entityID` value from the metadata to the `SAML_IDP_ENTITY_ID` configuration variable of Part-DB (by default
something like `https://idp.yourdomain.invalid/realms/master`).
7. Copy the `Single Sign-On Service` value from the metadata to the `SAML_IDP_SINGLE_SIGN_ON_SERVICE` configuration
variable of Part-DB (by default something like `https://idp.yourdomain.invalid/realms/master/protocol/saml`).
8. Copy the `Single Logout Service` value from the metadata to the `SAML_IDP_SINGLE_LOGOUT_SERVICE` configuration
variable of Part-DB (by default something like `https://idp.yourdomain.invalid/realms/master/protocol/saml/logout`).
9. Copy the `X.509 Certificate` value from the metadata to the `SAML_IDP_X509_CERT` configuration variable of Part-DB (
it should start with `MIIC` and should be pretty long).
10. Set the `DEFAULT_URI` to the homepage (on the publicly available domain) of your Part-DB installation (
e.g. `https://partdb.yourdomain.invalid/`). It must end with a slash.
11. Set the `SAML_ENABLED` configuration in Part-DB to 1 to enable SAML authentication.
When you access the Part-DB login form now, you should see a new button to log in via SSO. Click on it to be redirected to the SAML identity provider and log in.
When you access the Part-DB login form now, you should see a new button to log in via SSO. Click on it to be redirected
to the SAML identity provider and log in.
In the following sections, you will learn how to configure that Part-DB uses the data provided by the SAML identity provider to fill out user informations.
In the following sections, you will learn how to configure that Part-DB uses the data provided by the SAML identity
provider to fill out user information.
### Set user information based on SAML attributes
Part-DB can set basic user information like the username, the real name and the email address based on the SAML attributes provided by the SAML identity provider.
Part-DB can set basic user information like the username, the real name and the email address based on the SAML
attributes provided by the SAML identity provider.
To do this, you need to configure your SAML identity provider to provide the following attributes:
* `email` or `urn:oid:1.2.840.113549.1.9.1` for the email address
@ -83,68 +113,120 @@ To do this, you need to configure your SAML identity provider to provide the fol
* `lastName` or `urn:oid:2.5.4.4` for the last name
* `department` for the department field of the user
You can omit any of these attributes, but then the corresponding field will be empty (but can be overriden by an administrator).
These values are written to Part-DB database, whenever the user logs in via SAML (the user is created on the first login, and updated on every login).
You can omit any of these attributes, but then the corresponding field will be empty (but can be overwritten by an
administrator).
These values are written to Part-DB database, whenever the user logs in via SAML (the user is created on the first
login, and updated on every login).
To configure Keycloak to provide these attributes, you need to go to the `Client scopes` page and select the `sp-dedicatd` client scope (or create a new one).
To configure Keycloak to provide these attributes, you need to go to the `Client scopes` page and select
the `sp-dedicatd` client scope (or create a new one).
In the scope configuration page, click on `Add mappers` and `From predefined mappers`. Select the following mappers:
* `X500 email`
* `X500 givenName`
* `X500 surname`
and click `Add`. Now Part-DB will be provided with the email, first name and last name of the user based on the Keycloak user database.
and click `Add`. Now Part-DB will be provided with the email, first name and last name of the user based on the Keycloak
user database.
### Configure permissions for SAML users
On the first login of a SAML user, Part-DB will create a new user in the database. This user will have the same username as the SAML user, but no password set. The user will be marked as a SAML user, so he can only login via SAML in the future. However in other aspects the user is a normal user, so Part-DB admins can set permissions for SAML users like for any other user and override permissions assigned via groups.
However for large organizations you maybe want to automatically assign permissions to SAML users based on the roles or groups configured in the identity provider. For this purpose Part-DB allows you to map SAML roles or groups to Part-DB groups. See the next section for details.
On the first login of a SAML user, Part-DB will create a new user in the database. This user will have the same username
as the SAML user, but no password set. The user will be marked as a SAML user, so he can only log in via SAML in the
future. However, in other aspects the user is a normal user, so Part-DB admins can set permissions for SAML users like
for any other user and override permissions assigned via groups.
For large organizations you maybe want to automatically assign permissions to SAML users based on the roles or
groups configured in the identity provider. For this purpose Part-DB allows you to map SAML roles or groups to Part-DB
groups. See the next section for details.
### Map SAML roles to Part-DB groups
Part-DB allows you to configure a mapping between SAML roles or groups and Part-DB groups. This allows you to automatically assign permissions to SAML users based on the roles or groups configured in the identity provider. For example if a user at your SAML provider has the role `admin`, you can configure Part-DB to assign the `admin` group to this user. This will give the user all permissions of the `admin` group.
For this you need first have to create the groups in Part-DB, to which you want to assign the users and configure their permissions. You will need the IDs of the groups, which you can find in the `System->Group` page of Part-DB in the Info tab.
Part-DB allows you to configure a mapping between SAML roles or groups and Part-DB groups. This allows you to
automatically assign permissions to SAML users based on the roles or groups configured in the identity provider. For
example if a user at your SAML provider has the role `admin`, you can configure Part-DB to assign the `admin` group to
this user. This will give the user all permissions of the `admin` group.
The map is provided as [JSON](https://en.wikipedia.org/wiki/JSON) encoded map between the SAML role and the group ID, which has the form `{"saml_role": group_id, "*": group_id, ...}`. You can use the `*` key to assign a group to all users, which are not in any other group. The map is configured via the `SAML_ROLE_MAPPING` environment variable, which you can configure via the `.env.local` or `docker-compose.yml` file. Please note that you have to enclose the JSON string in single quotes here, as JSON itself uses double quotes (e.g. `SAML_ROLE_MAPPING='{ "*": 2, "editor": 3, "admin": 1 }`).
For this you need first have to create the groups in Part-DB, to which you want to assign the users and configure their
permissions. You will need the IDs of the groups, which you can find in the `System->Group` page of Part-DB in the Info
tab.
For example if you want to assign the group with ID 1 (by default admin) to every SAML user which has the role `admin`, the role with ID 3 (by default editor) to every SAML user with the role `editor` and everybody else to the group with ID 2 (by default readonly), you can configure the following map:
The map is provided as [JSON](https://en.wikipedia.org/wiki/JSON) encoded map between the SAML role and the group ID,
which has the form `{"saml_role": group_id, "*": group_id, ...}`. You can use the `*` key to assign a group to all
users, which are not in any other group. The map is configured via the `SAML_ROLE_MAPPING` environment variable, which
you can configure via the `.env.local` or `docker-compose.yml` file. Please note that you have to enclose the JSON
string in single quotes here, as JSON itself uses double quotes (
e.g. `SAML_ROLE_MAPPING='{ "*": 2, "editor": 3, "admin": 1 }`).
For example if you want to assign the group with ID 1 (by default admin) to every SAML user which has the role `admin`,
the role with ID 3 (by default editor) to every SAML user with the role `editor` and everybody else to the group with ID
2 (by default readonly), you can configure the following map:
```
SAML_ROLE_MAPPING='{"admin": 1, "editor": 3, "*": 2}'
```
Please not that the order of the mapping is important. The first matching role will be assigned to the user. So if you have a user with the roles `admin` and `editor`, he will be assigned to the group with ID 1 (admin) and not to the group with ID 3 (editor), as the `admin` role comes first in the JSON map.
This mean that you should always put the most specific roles (e.g. admins) first of the map and the most general roles (e.g. normal users) later.
Please note that the order of the mapping is important. The first matching role will be assigned to the user. So if you
have a user with the roles `admin` and `editor`, he will be assigned to the group with ID 1 (admin) and not to the group
with ID 3 (editor), as the `admin` role comes first in the JSON map.
This mean that you should always put the most specific roles (e.g. admins) first of the map and the most general roles (
e.g. normal users) later.
If you want to assign users with a certain role to a empty group, provide the group ID -1 as the value. This is not a valid group ID, so the user will not be assigned to any group.
If you want to assign users with a certain role to an empty group, provide the group ID -1 as the value. This is not a
valid group ID, so the user will not be assigned to any group.
The SAML roles (or groups depending on your configuration), have to be supplied via a SAML attribute `group`. You have to configure your SAML identity provider to provide this attribute. For example in Keycloak you can configure this attribute in the `Client scopes` page. Select the `sp-dedicated` client scope (or create a new one) and click on `Add mappers`. Select `Role mapping` or `Group membership`, change the field name and click `Add`. Now Part-DB will be provided with the groups of the user based on the Keycloak user database.
The SAML roles (or groups depending on your configuration), have to be supplied via a SAML attribute `group`. You have
to configure your SAML identity provider to provide this attribute. For example in Keycloak you can configure this
attribute in the `Client scopes` page. Select the `sp-dedicated` client scope (or create a new one) and click
on `Add mappers`. Select `Role mapping` or `Group membership`, change the field name and click `Add`. Now Part-DB will
be provided with the groups of the user based on the Keycloak user database.
By default, the group is assigned to the user on the first login and updated on every login based on the SAML attributes. This allows you to configure the groups in the SAML identity provider and the users will automatically stay up to date with their permissions. However, if you want to disable this behavior (and let the Part-DB admins configure the groups manually, after the first login), you can set the `SAML_UPDATE_GROUP_ON_LOGIN` environment variable to `false`. If you want to disable the automatic group assignment completly (so not even on the first login of a user), set the `SAML_ROLE_MAPPING` to `{}` (empty JSON object).
By default, the group is assigned to the user on the first login and updated on every login based on the SAML
attributes. This allows you to configure the groups in the SAML identity provider and the users will automatically stay
up to date with their permissions. However, if you want to disable this behavior (and let the Part-DB admins configure
the groups manually, after the first login), you can set the `SAML_UPDATE_GROUP_ON_LOGIN` environment variable
to `false`. If you want to disable the automatic group assignment completely (so not even on the first login of a user),
set the `SAML_ROLE_MAPPING` to `{}` (empty JSON object).
## Overview of possible SAML attributes used by Part-DB
The following table shows all SAML attributes, which can be usedby Part-DB. If your identity provider is configured to provide these attributes, you can use to automatically fill the corresponding fields of the user in Part-DB.
The following table shows all SAML attributes, which can be used by Part-DB. If your identity provider is configured to
provide these attributes, you can use to automatically fill the corresponding fields of the user in Part-DB.
| SAML attribute | Part-DB user field | Description |
|-------------------------------------------|-------------------|-------------------------------------------------------------------|
| `urn:oid:1.2.840.113549.1.9.1` or `email` | email | The email address of the user. |
| `urn:oid:2.5.4.42` or `firstName` | firstName | The first name of the user. |
| `urn:oid:2.5.4.4` or `lastName` | lastName | The last name of the user. |
| `department` | department | The department of the user. |
| `group` | group | The group of the user (determined by `SAML_ROLE_MAPPING` option). |
|-------------------------------------------|--------------------|-------------------------------------------------------------------|
| `urn:oid:1.2.840.113549.1.9.1` or `email` | email | The email address of the user. |
| `urn:oid:2.5.4.42` or `firstName` | firstName | The first name of the user. |
| `urn:oid:2.5.4.4` or `lastName` | lastName | The last name of the user. |
| `department` | department | The department of the user. |
| `group` | group | The group of the user (determined by `SAML_ROLE_MAPPING` option). |
## Use SAML Login for existing users
Part-DB distinguishes between local users and SAML users. Local users are users, which can login via Part-DB login form and which use the password (hash) saved in the Part-DB database. SAML users are stored in the database too (they are created on the first login of the user via SAML), but they use the SAML identity provider to authenticate the user and have no password stored in the database. When you try you will get an error message.
For security reasons it is not possible to authenticate via SAML as a local user (and vice versa). So if you have existing users in your Part-DB database and want them to be able to login via SAML in the future, you can use the `php bin/console partdb:user:convert-to-saml-user username` command to convert them to SAML users. This will remove the password hash from the database and mark them as SAML users, so they can login via SAML in the future.
Part-DB distinguishes between local users and SAML users. Local users are users, which can log in via Part-DB login form
and which use the password (hash) saved in the Part-DB database. SAML users are stored in the database too (they are
created on the first login of the user via SAML), but they use the SAML identity provider to authenticate the user and
have no password stored in the database. When you try you will get an error message.
The reverse is also possible: If you have existing SAML users and want them to be able to login via the Part-DB login form, you can use the `php bin/console partdb:user:convert-to-saml-user --to-local username` command to convert them to local users. You have to set an password for the user afterwards.
For security reasons it is not possible to authenticate via SAML as a local user (and vice versa). So if you have
existing users in your Part-DB database and want them to be able to log in via SAML in the future, you can use
the `php bin/console partdb:user:convert-to-saml-user username` command to convert them to SAML users. This will remove
the password hash from the database and mark them as SAML users, so they can log in via SAML in the future.
The reverse is also possible: If you have existing SAML users and want them to be able to log in via the Part-DB login
form, you can use the `php bin/console partdb:user:convert-to-saml-user --to-local username` command to convert them to
local users. You have to set a password for the user afterward.
{: .important }
> It is recommended that you let the original admin user (ID: 2) be a local user, so you can still login to Part-DB if the SAML identity provider is not available.
> It is recommended that you let the original admin user (ID: 2) be a local user, so you can still login to Part-DB if
> the SAML identity provider is not available.
## Advanced SAML configuration
You can find some more advanced SAML configuration options in the `config/packages/nbgrp_onelogin_saml.yaml` file. Refer to the file for more information.
You can find some more advanced SAML configuration options in the `config/packages/nbgrp_onelogin_saml.yaml` file. Refer
to the file for more information.
Normally you don't have to change anything here.
Please note that this file is not saved by the Part-DB backup tool, so you have to save it manually if you want to keep your changes. On docker containers you have to configure a volume mapping for it.
Please note that this file is not saved by the Part-DB backup tool, so you have to save it manually if you want to keep
your changes. On docker containers you have to configure a volume mapping for it.