Moved remaining docs from github wiki to pages

docs/configuration.md

@@ -0,0 +1,56 @@
+---
+layout: default
+title: Configuration
+nav_order: 5
+---
+
+# Configuration
+
+Part-DBs behavior can be configured to your needs. There are different kind of configuration options: Options which are user changable (changable dynamically via frontend), options which can be configured by environment variables, and options which are only configurable via symfony config files.
+
+## User changable
+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 users own setting page (where you can also change the password) or via the user admin page:
+* **Language**: The language that the users prefers, and which will be used when no language is explicitly specified. Language can still always be changed via the language selector. By default the global configured language is used.
+* **Timezone**: The timezone which the user resides in and in which all dates and times should be shown. By default the globally configured language.
+* **Theme**: The theme to use for the frontend. Allows the user to choose the frontend design, he prefers.
+* **Prefered 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
+
+## 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 full list of possible env variables.
+
+### General options
+* `DATABASE_URL`: Configures the database which Part-DB uses. For mysql 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 absolute path where it should be located `sqlite:///path/part/app.db`. You can use `%kernel.project_dir%` as placeholder for the Part-DB root folder (e.g. `sqlite:///%kernel.project_dir%/var/app.db`)
+* `DEFAULT_LANG`: The default language to use serverwide (when no language is explictly specified by a user or via language chooser). Must be something like `en`, `de`, `fr`, etc.
+* `DEFAULT_TIMEZONE`: The default timezone to use globally, when a user has not timezone specified. Must be something like `Europe/Berlin`. See [here](https://en.wikipedia.org/wiki/List_of_tz_database_time_zones) under TZ Database name for a list of available options.
+* `BASE_CURRENCY`: The currency to use internally for monetary values and when no currency is explictly specified. When migrating from a legacy Part-DB version, this should be the same as the currency in the old Part-DB instance (normally euro). This should be the currency you use the most. **Please note that you can not really change this setting after you have created data**. The value has to be a valid [ISO4217](https://en.wikipedia.org/wiki/ISO_4217) code, like `EUR` or `USD`.
+* `INSTANCE_NAME`: The name of your installation. It will be shown as a title in the navbar and other places. By default `Part-DB`, but you can customize it to something likes `ExampleCorp. Inventory`.
+* `ALLOW_ATTACHMENT_DOWNLOADS` (allowed values `0` or `1`): By setting this option to 1, users can make Part-DB directly download a file specified as an URL and create it as local file. Please not that this allows users access to all ressources publicly available to the server (so full access to other servers in the same local network), which could be a security risk.
+* `USE_GRAVATAR`: Set to `1` to use [gravatar.com](gravatar.com) images for user avatars (as long as they have not set their own picture). The users browsers have to download the pictures from a third-party (gravatars) server, so this might be a privacy risk.
+
+
+### E-Mail settings
+* `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 mail account, you can use the following syntax `MAILER_DSN=smtp://user:password@smtp.mailserver.invalid:587`
+* `EMAIL_SENDER_EMAIL`: The email address from which emails should be sent from (in most cases this has to be the same as the email address used for SMTP access)
+* `EMAIL_SENDER_NAME`: Similar to `EMAIL_SENDER_EMAIL` but this allows you to specify the name from which the mails are sent from.
+* `ALLOW_EMAIL_PW_RESET`: Set this value to true, if you wan to allow users to reset their password via an email notification. You have to configure the mailprovider first before via the MAILER_DSN setting.
+
+### History/Eventlog related settings
+The following options are used to configure, which (and how much) data is written to the system log:
+* `HISTORY_SAVE_CHANGED_FIELDS`: When this option is set to true, the name of the fields which are changed, are saved to the DB (so for example it is logged that a user has changed, that the user has changed the name and description of the field, but not the data/content of these changes)
+* `HISTORY_SAVE_CHANGED_DATA`: When this option is set to true, the changed data is saved to log (so it is logged, that a user has changed the name of a part and what the name was before). This can increase database size, when you have a lot of changes to enties.
+* `HISTORY_SAVE_REMOVED_DATA`: When this option is set to true, removed data is saved to log, meaning that you can easily undelete an entity, when it was removed accidentally.
+
+If you wanna 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_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)
+* `ERROR_PAGE_SHOW_HELP`: Set this 0, to disable the solution hints shown on an error page. These hints should not contain senstive informations, but could confuse end-users.
+
+### Other / less used options
+* `TRUSTED_PROXIES`: Set the IP addresses (or IP blocks) of trusted reverse proxies here. This is needed to get correct IP informations (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 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 instance, 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 support rewrite. In this case, all URL pathes will contain index.php/, which is needed then. Normally this setting do not need to be changed.
+* `FIXER_API_KEY`: If you want to automatically retrieve exchange rates for base currencies other than euros, you have 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 mode. (**You should not do this on a publicly accessible server, as it will leak sensitive informations!**)
+* `BANNER`: You can configure the text that should be shown as the banner on the homepage. Useful especially for docker container. In all other applications you can just change the `config/banner.md` file.

docs/index.md

@@ -1,6 +1,7 @@
 ---
 title: Home
 layout: home
+nav_order: 0
 ---
 
 # Part-DB documentation

docs/installation/index.md

@@ -1,7 +1,7 @@
 ---
 layout: default
 title: Installation
-nav_order: 2
+nav_order: 3
 has_children: true
 ---
 

docs/usage/backup_restore.md

@@ -0,0 +1,53 @@
+---
+title: Backup & Restore Data
+layout: default
+parent: Usage
+---
+
+# Backup and Restore Data
+
+When working productively you should backup the data and configuration of Part-DB regularly to prevent data loss. This is also useful, if you want to migrate your Part-DB instance from one server to another. In that case you just have to backup the data on server 1, move the backup to server 2, install Part-DB on server 2 and restore the backup.
+
+## Backup (automatic / Part-DB supported)
+Part-DB includes a command `php bin/console partdb:backup` which automatically collects all the needed data (described below) and saves them to a ZIP file.
+
+If you are using a MySQL/MariaDB database you need to have `mysqldump` installed and added to your `$PATH` env.
+
+### Usage
+To backup all possible data, run the following command: `php bin/console partdb:backup --full /path/to/backup/partdb_backup.zip`.
+
+It is possible to do only partial backups (config, attachments, or database). See `php bin/console partdb:backup --help` for more infos about these options.
+
+## Backup (manual)
+There are 3 parts which have to be backup-ed: The configuration files, which contains the instance specific options, the uploaded files of attachments, and the database containing the most data of Part-DB.
+Everything else like thumbnails and cache files, are recreated automatically when needed.
+
+### Configuration files
+You have to copy the `.env.local` file and (if you have changed it) the `config/parameters.yaml` and `config/banner.md` to your backup location.
+
+### Attachment files
+You have to recursively copy the `uploads/` folder and the `public/media` folder to your backup location.
+
+### Database
+#### Sqlite
+If you are using sqlite, it is sufficient to just copy your `app.db` from your database location (normally `var/app.db`) to your backup location.
+
+#### MySQL / MariaDB
+For MySQL / MariaDB you have to dump the database to an SQL file. You can do this manually with phpmyadmin, or you use [`mysqldump`](https://mariadb.com/kb/en/mariadb-dumpmysqldump/) to dump the database to an SQL file via command line interface (`mysqldump -uBACKUP -pPASSWORD DATABASE`)
+
+## Restore
+Install Part-DB as usual as described in the installation section, with the exception of the database creation / migration part. You have to use the same database type (sqlite or mysql) as on the back-uped server instance.
+
+### Restore configuration
+Copy configuration files `.env.local`, (and if existing) `config/parameters.yaml` and `config/banner.md` from the backup to your new Part-DB instance and overwrite the existing files there.
+
+### Restore attachment files
+Copy the `uploads/` and the `public/media/` folder from your backup into your new Part-DB folder.
+
+### Restore database
+#### Sqlite
+Copy the backup-ed `app.db` into the database folder normally `var/app.db` in Part-DB root folder.
+
+#### MySQL / MariaDB
+Recreate a database and user with the same credentials as before (or update the database credentials in the `.env.local` file).
+Import the dumped SQL file from the backup into your new database.

docs/usage/getting_started.md

@@ -0,0 +1,126 @@
+---
+layout: default
+title: Getting started with Part-DB
+nav_order: 4
+---
+
+# Getting started
+
+After Part-DB you should begin with customizing the settings, and setting up the basic structures.
+Before starting its useful to read a bit about the [concepts of Part-DB](https://github.com/Part-DB/Part-DB-symfony/wiki/Concepts).
+
+## Customize config files
+<details>
+<summary>Click to expand</summary>
+
+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 your `docker-compose.yaml` file.
+A list of possible configuration options, can be found [here](Configuration).
+
+</details>
+
+## Change password, Set up Two-Factor-Authentication & Customize User settings
+<details>
+<summary>Click to expand</summary>
+
+If you have not already done, you should change your user password. You can do this in the user settings (available in the navigation bar drop down with the user symbol).
+
+![image](https://user-images.githubusercontent.com/5410681/190141016-5539a125-3215-48bb-b61b-7c646c352d4d.png)
+
+There you can also find the option, to set up Two Factor Authentication methods like Google Authenticator. Using this is highly recommended (especially if you have admin permissions) to increase the security of your account. (Two Factor Authentication even can be enforced for all members of a user group)
+
+In the user settings panel you can change account infos like your username, your first and last name (which will be shown alongside your username to identify you better), department information and your email address. The email address is used to send password reset mails, if your system is configured to use this.
+
+![image](https://user-images.githubusercontent.com/5410681/190142624-0b4d4153-33ea-46e6-baba-5723b5ba9f52.png)
+
+In the configuration tab you can also override global settings, like your preferred UI language (which will automatically be applied after login), the timezone you are in (and in which times will be shown for you), your preferred currency (all money values will be shown converted to this to you, if possible) and the theme that should be used.
+</details>
+
+## Create groups, users and customize permissions
+<details>
+<summary>Click to expand</summary>
+
+### Users
+When logged in as administrator, you can open the users menu in the `Tools` section of the sidebar under `System -> Users`.
+At this page you can create new users, change their passwords and settings and change their permissions.
+For each user which should use Part-DB you should setup a own account, so that tracking of what user did what works properly.
+![image](https://user-images.githubusercontent.com/5410681/193269065-cf0695b9-21bd-4697-87ab-1557197ef0f6.png)
+
+
+You should check the permissions for every user and ensure that they are in the intended way, and no user has more permissions than he needs.
+For each capability you can choose between allow, forbid and inherit. In the last case, the permission is determined by the group a user has (if no group is chosen, it equals forbid)
+
+![image](https://user-images.githubusercontent.com/5410681/193269185-3a783628-44ca-4dcf-9629-fc6af2e39709.png)
+
+
+### Anonymous user
+The `anonymous` user is special, as its settings and permissions are used for everybody who is not logged in. By default the anonymous user has read capabilities for your parts. If your Part-DB instance is publicly available you maybe want to restrict the permissions.
+
+### Groups
+If you have many users which should share the same permissions, it is useful to define the permissions using user groups, which you can create and edit in the `System -> Groups` menu.
+
+By default 3 groups are defined:
+* `readonly` which users have only have read permissions (like viewing, searching parts, attachments, etc.)
+* `users` which users also have rights to edit/delete/create elements
+* `admin` which users can do administrative operations (like creating new users, show global system log, etc.)
+
+Users only use the setting of a capability from a group, if the user has a group associated and the capability on the user is set to `inherit` (which is the default if creating a new user). You can override the permissions settings of a group per user by explicitly settings the permission at the user.
+
+Groups are organized as trees, meaning a group can have parent and child permissions and child groups can inherit permissions from their parents.
+To inherit the permissions from a parent group set the capability to inherit, otherwise set it explicitly to override the parents permission.
+
+</details>
+
+## Create Attachment types
+<details>
+<summary>Click to expand</summary>
+
+Every attachment (that is an file associated with a part, data structure, etc.) must have an attachment type. They can be used to group attachments logically, like differentiating between datasheets, pictures and other documents.
+
+You can create/edit attachment types in the tools sidebar under "Edit -> Attachment types":
+
+![image](https://user-images.githubusercontent.com/5410681/206695965-60a15725-c690-456c-bbdb-d6af858ee75b.png)
+ 
+Depending on your usecase different entries here make sense. For part mananagment the following (additional) entries maybe make sense:
+
+* Datasheets (restricted to pdfs, Allowed filetypes: `application/pdf`)
+* Pictures (for generic pictures of components, storage locations, etc., Allowed filetypes: `image/*`
+
+For every attachment type a list of allowed file types, which can be uploaded to an attachment with this attachment type, can be defined. You can either pass a list of allowed file extensions (e.g. `.pdf, .zip, .docx`) and/or a list of [Mime Types](https://en.wikipedia.org/wiki/Media_type) (e.g. `application/pdf, image/jpeg`) or a combination of both here. To allow all browser supported images, you can use `image/*` wildcard here.
+
+</details>
+
+## (Optional) Create Currencies
+<details>
+<summary>Click to expand</summary>
+If you want to save priceinformations for parts in a currency different to your global currency (by default Euro), you have to define the additional currencies you want to use under `Edit -> Currencies`:
+
+![image](https://user-images.githubusercontent.com/5410681/206698733-01e22c0b-c871-438a-a98d-f09f1c03fe90.png)
+
+You create a new currency, name it however you want (it is recommended to use the official name of the currency) and select the currency ISO code from the list and save it. The currency symbol is determined automatically from chose ISO code.
+You can define a exchange rate in terms of your base currency (e.g. how much euros is one unit of your currency worth) to convert the currencies values in your preferred display currency automatically. 
+
+
+</details>
+
+## (Optional) Create Measurement Units
+<details>
+<summary>Click to expand</summary>
+
+By default Part-DB assumes that the parts in inventory can be counted by individual indivisible pieces, like LEDs in a box or books in a shelf. However if you want to manage things, that are divisible and and the instock is described by a physical quantity, like length for cables, or volumina of a liquid, you have to define additional measurement units.
+
+This is possible under `Edit -> Measurement Units`:
+![image](https://user-images.githubusercontent.com/5410681/206701450-40a5f323-21ea-4889-a68b-8fb6c3d2f46d.png)
+
+You can give the measurement unit a name and an optional unit symbol (like `m` for meters) which is shown when quantities in this unit are displayed. The option `Use SI prefix` is useful for almost all physical quantities, as big and small numbers are automatically formatted with SI-prefixes (like 1.5kg instead 1500 grams).
+
+The measurement unit can be selected for each part individually, by setting the option in the advanced tab of a part`s edit menu.
+
+</details>
+
+## (Optional) Customize homepage banner
+<details>
+<summary>Click to expand</summary>
+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.
+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$$
+</details>

docs/usage/index.md

@@ -0,0 +1,9 @@
+---
+layout: default
+title: Usage
+nav_order: 6
+has_children: true
+---
+
+# Usage
+In this section you can find information and tips and tricks how to use Part-DB.

docs/usage/labels.md

@@ -0,0 +1,81 @@
+---
+title: Backup & Restore Data
+layout: default
+parent: Usage
+---
+
+# Labels
+
+## Label placeholders
+A placeholder has the format `[[PLACEHOLDER]]` and will be filled with the concrete data by Part-DB.
+You can use the "Placeholders" dropdown in content editor, to automatically insert the placeholders.
+
+### Common
+
+| Placeholder | Description  | Example  |
+|---|---|---|
+| `[[USERNAME]]`  | The user name of the currently logged in user  | admin  |
+| `[[USERNAME_FULL]]`  | The full name of the current user  | John Doe (@admin)  |
+| `[[DATETIME]]`  | The current date and time in the selected locale  | 31.12.2017, 18:34:11  |
+| `[[DATE]]`  | The current date in the selected locale  | 31.12.2017 |
+| `[[TIME]]` | The current time in the selected locale | 18:34:11 |
+| `[[INSTALL_NAME]]` | The name of the current installation (see $config['partdb_title']) | Part-DB |
+
+### Parts
+
+| Placeholder  | Description  | Example  |
+|---|---|---|
+| `[[ID]]`  | The internal ID of the part  | 24  |
+| `[[NAME]]`  | The name of the part  | ATMega328  |
+| `[[CATEGORY]]`  | The name of the category (without path)  | AVRs  |
+| `[[CATEGORY_FULL]]`  | The full path of the category  | Aktiv->MCUs->AVRs  |
+| `[[MANUFACTURER]]`  | The name of the manufacturer  | Atmel  |
+| `[[MANUFACTURER_FULL]]`  | The full path of the manufacturer  | Halbleiterhersteller->Atmel  |
+| `[[FOOTPRINT]]`  | The name of the footprint (without path)  | DIP-32  |
+| `[[FOOTPRINT_FULL]]`  | The full path of the footprint  | Bedrahtet->DIP->DIP-32  |
+| `[[MASS]]` | The mass of the part | 123.4 g |
+| `[[MPN]]`  | The manufacturer product number | BC547ACT |
+| `[[TAGS]]` | The tags of the part | SMD, Tag1 |
+| `[[M_STATUS]]` | The manufacturing status of the part | Active |
+| `[[DESCRIPTION]]` | The rich text description of the part | *NPN* |
+| `[[DESCRIPTION_T]]` | The description as plain text | NPN |
+| `[[COMMENT]]` | The rich text comment of the part | |
+| `[[COMMENT_T]]` | The comment as plain text | |
+| `[[LAST_MODIFIED]]` | The datetime when the element was last modified |  2/26/16, 5:38 PM |
+| `[[CREATION_DATE]]` | The datetime when the element was created  | 2/26/16, 5:38 PM |
+
+### Part lot
+| Placeholder  | Description  | Example  |
+|---|---|---|
+| `[[LOT_ID]]`   | Part lot ID | 123  |
+| `[[LOT_NAME]]` | Part lot name |  |
+| `[[LOT_COMMENT]]` | Part lot comment | |
+| `[[EXPIRATION_DATE]]` | Expiration date of the part lot | |
+| `[[AMOUNT]]` | The amount of parts in this lot | 12 |
+| `[[LOCATION]]` | The storage location of this part lot | Location A |
+| `[[LOCATION_FULL]]` | The full path of the storage location | Location -> Location A |
+
+### Storelocation
+| Placeholder  | Description  | Example  |
+|---|---|---|
+| `[[ID]]` | ID of the storage location |  |
+| `[[NAME]]` | Name of the storage location | Location A |
+| `[[FULL_PATH]]` | The full path of the storage location | Location -> Location A |
+| `[[PARENT]]` | The name of the parent location | Location |
+| `[[PARENT_FULL_PATH]]` | The full path of the storage location | |
+| `[[COMMENT]]` | The comment of the storage location | |
+| `[[COMMENT_T]]` | The plain text version of the comment | 
+| `[[LAST_MODIFIED]]` | The datetime when the element was last modified |  2/26/16, 5:38 PM |
+| `[[CREATION_DATE]]` | The datetime when the element was created  | 2/26/16, 5:38 PM |
+
+## Twig mode
+If you select "Twig" in parser mode under advanced settings, you can input a twig template in the lines field (activate source mode). You can use most of the twig tags and filters listed in [offical documentation](https://twig.symfony.com/doc/3.x/).
+
+The following variables are in injected into Twig and can be accessed using `{{ variable }}` (or `{{ variable.property }}`):
+
+| Variable name | Description |
+| ------------- | ----------- |
+| `{{ element }}` | The target element, selected in label dialog |
+| `{{ user }}`   | The current logged in user. Null if you are not logged in |
+| `{{ install_title }}` | The name of the current Part-DB instance (similar to [[INSTALL_NAME]] placeholder). |
+| `{{ page }}` | The page number (the nth-element for which the label is generated |