mirror/Part-DB.Part-DB-server
1
0
Fork 1
mirror of https://github.com/Part-DB/Part-DB-server.git synced 2025-07-24 21:05:03 +02:00
Code Issues Projects Releases Packages Wiki Activity Actions

Fixed some typos and grammar issues in documentation

Browse source
This commit is contained in:
Jan Böhmer 2024-02-23 13:56:23 +01:00
parent 20ee16e3c0
commit 5d68922f2e
11 changed files with 142 additions and 153 deletions
Download patch file Download diff file Expand all files Collapse all files

13
docs/installation/choosing_database.md
View file

@ -24,16 +24,15 @@ To use **MySQL/MariaDB** as database, you have to install and configure the MySQ
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 *
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. Also SQLite has limitations in comparisons and sorting of unicode characters, which might lead to unexpected
behavior when using non-ASCII characters in your data. For example `µ` (micro sign) is not seen as equal to `μ`(greek minuscle mu),
therefore searching for `µ` (micro sign) will not find parts containing `μ` (mu) and vice versa. In MySQL identical
looking characters are seen as equal, which is more intuitive in most cases.
However, SQLite does not support certain operations like regex search, which has to be emulated by PHP and therefore is
pretty slow compared to the same operation at MySQL. In the future, there might be features that may only be available, when
using MySQL. Also, SQLite has limitations in comparisons and sorting of Unicode characters, which might lead to unexpected
behavior when using non-ASCII characters in your data. For example `µ` (micro sign) is not seen as equal to `μ(greek minuscule mu),
therefore searching for `µ` (micro sign) will not find parts containing `μ` (mu) and vice versa. In MySQL identical-looking characters are seen as equal, which is more intuitive in most cases.
In general MySQL might perform better for big Part-DB instances with many entries, lots of users and high activity, than
SQLite.

22
docs/installation/installation_docker.md
View file

@ -20,7 +20,7 @@ where docker is available (especially recommended for Windows and macOS).
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/
1. Install docker and docker-compose as described under https://docs.docker.com/compose/install/
2. Create a folder where the Part-DB data should live
3. Create a file named docker-compose.yaml with the following content:
@ -74,7 +74,7 @@ services:
# - TRUSTED_PROXIES=127.0.0.0/8,::1,10.0.0.0/8,172.16.0.0/12,192.168.0.0/16
```
4. Customize the settings by changing the environment variables (or add new ones). See [Configuration]({% link
4. Customize the settings by changing the environment variables (or adding new ones). See [Configuration]({% link
configuration.md %}) for more information.
5. Inside the folder, run
@ -90,10 +90,10 @@ 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
6. Part-DB is available under `http://localhost:8080` and you can log in with the 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 image uses a SQLite database and all data (database, uploads, and other media) is put into folders relative to
the docker-compose.yml.
### MySQL
@ -183,15 +183,15 @@ 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
You can use the `jbtronics/part-db1:master` image directly. You have to expose 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
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.
You also have to create the database as described above in step 4.
## Running console commands
@ -200,8 +200,8 @@ 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"*:
*Login is 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 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.
Clear all cookies in your browser or use an incognito tab for Part-DB.
This is related to the fact that Part-DB can not set cookies via HTTP after some webpages have set cookies before under
localhost via HTTPS. This is a security mechanism of the browser and can not be bypassed by Part-DB.

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

@ -8,9 +8,9 @@ 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.
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
this many dependencies. See [here]({% link installation/installation_docker.md %}) for more information on the docker
installation.
{: .warning }
@ -30,8 +30,8 @@ sudo apt install git curl zip ca-certificates software-properties-common apt-tra
### 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
Part-DB is written in [PHP](https://php.net) and therefore needs a 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
@ -46,7 +46,7 @@ sudo curl -sSL https://packages.sury.org/php/README.txt | sudo bash -x
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
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
@ -57,8 +57,8 @@ The apache2 webserver should be already installed with this command and configur
### 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 version shipped in the
repositories is pretty old, we will install it manually:
```bash
# Download composer installer script
@ -71,8 +71,8 @@ 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 depends on Node.js and the
shipped versions are pretty old, we install new versions from official Node.js repository:
To build the front end (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 the official Node.js repository:
```bash
# Add recent node repository (nodejs 18 is supported until 2025)
@ -102,7 +102,7 @@ later.
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
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
@ -110,7 +110,7 @@ can switch to the latest stable version (tagged) by running the following comman
git checkout $(git describe --tags $(git rev-list --tags --max-count=1))
```
Alternatively you can check out a specific version by running (
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
@ -176,12 +176,12 @@ To check if everything is installed, run the following command:
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
Most things should be green, and no red ones. Yellow messages mean 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
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
@ -191,8 +191,7 @@ 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 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.
like `The initial password for the "admin" user is: f502481134`. Write down this password as you will need it later for the initial login.
### Configure apache2 to show Part-DB
@ -248,7 +247,7 @@ 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).
network to point to the server).
### Login to Part-DB
@ -288,7 +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).
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:
1. Install maria-db with:

2
docs/installation/nginx.md
View file

@ -13,7 +13,7 @@ configured.
## Setup
1. Install composer and yarn like described in the [apache guide]({% link installation/installation_guide-debian.md
1. Install composer and yarn as 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:

28
docs/installation/saml_sso.md
View file

@ -48,7 +48,7 @@ the [Keycloak Getting Started Guide](https://www.keycloak.org/docs/latest/gettin
*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.
3. Click on `Save` to create a new client.
### Configure the SAML client
@ -56,7 +56,7 @@ the [Keycloak Getting Started Guide](https://www.keycloak.org/docs/latest/gettin
* 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 post logout redirect URIs` to `+` to allow all urls from the `Valid redirect URIs`.
* 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.
* Ensure `Sign documents` is enabled.
@ -135,8 +135,8 @@ On the first login of a SAML user, Part-DB will create a new user in the databas
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
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.
@ -144,11 +144,11 @@ groups. See the next section for details.
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
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
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 on the `System->Group` page of Part-DB in the Info
tab.
The map is provided as [JSON](https://en.wikipedia.org/wiki/JSON) encoded map between the SAML role and the group ID,
@ -158,7 +158,7 @@ you can configure via the `.env.local` or `docker-compose.yml` file. Please note
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`,
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:
@ -176,9 +176,9 @@ If you want to assign users with a certain role to an empty group, provide the g
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
to configure your SAML identity provider to provide this attribute. For example, in Keycloak you can configure this
attribute on 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
@ -203,12 +203,12 @@ provide these attributes, you can use to automatically fill the corresponding fi
## Use SAML Login for existing users
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
Part-DB distinguishes between local users and SAML users. Local users are users, that can log in via the Part-DB login form
and 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
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.