Merge remote-tracking branch 'origin/master'

docs/_config.yaml

@@ -0,0 +1,20 @@
+title: Part-DB
+description: A starter template for a Jeykll site using the Just the Docs theme!
+remote_theme: just-the-docs/just-the-docs
+
+url: "https://part-db.github.io"
+baseurl: "/Part-DB-symfony" # the subpath of your site, e.g. /blog
+
+aux_links:
+  Part-DB Repository: https://github.com/Part-DB/Part-DB-symfony
+
+
+search_enabled: true
+
+# Footer "Edit this page on GitHub" link text
+gh_edit_link: true # show or hide edit this page link
+gh_edit_link_text: "Edit this page on GitHub."
+gh_edit_repository: "https://github.com/Part-DB/Part-DB-symfony" # the github URL for your repo
+gh_edit_branch: "master" # the branch that your docs is served from
+gh_edit_source: docs # the source that your files originate from
+gh_edit_view_mode: "tree" # "tree" or "edit" if you want the user to jump into the editor immediately

docs/concepts.md

@@ -0,0 +1,153 @@
+---
+layout: default
+title: Concepts
+nav_order: 2
+---
+
+# Concepts
+This page explains the different concepts of Part-DB and what their intended use is
+
+## Part managment
+
+### Part
+A part is the central concept of Part-DB. A part represents a single kind (or type) of a thing, like an electronic component, an device, an book or similar (depending on what you use Part-DB for). A part entity just represents a certain type of a thing, so if you have 1000 times an BC547 transistor you would create ONE part with the name BC547 and set its quantity to 1000. The individual quantities (so a single BC547 transistor) of a part, should be indistinguishable from each other, so that it does not matter which one of your 1000 things of Part you use.
+A part entity have many fields, which can be used to describe it better. Most of the fields are optional:
+* **Name** (Required): The name of the part or how you wanna call it. This could be an manufacturer provided name, or a name you thought of your self. The name have to be unique in a single category.
+* **Description**: A short (single-line) description of what this part is/does. For longer informations you should use the comment field or the specifications
+* **Category** (Required): The category (see there) to which this part belongs to.
+* **Tags**: The list of tags this part belong to. Tags can be used to group parts logically (similar to the category), but tags are much less strict and formal (they dont have to be defined forehands) and you can assign multiple tags to a part. When clicking on a tag, a list with all parts which have the same tag, is shown.
+* **Min Instock**: *Not really implemented yet*. Parts where the total instock is below this value, will show up for ordering.
+* **Footprint**: See there. Useful especially for electronic parts, which have one of the common electronic footprints (like DIP8, SMD0805 or similar). If a part has no explicit defined preview picture, the preview picture of its footprint will be shown instead in tables.
+* **Manufacturer**: The manufacturer which has manufactured (not sold) this part. See Manufacturer entity for more info.
+* **Manufacturer part number** (MPN): If you have used your own name for a part, you can put the part number the manufacturer uses in this field, so that you can find a part also under its manufacturer number.
+* **Link to product page**: If you want to link to the manufacturer website of a part, and it is not possible to determine it automatically from the part name, set in the manufacturer entity (or no manfacturer is set), you can set the link here for each part individually.
+* **Manufacturing Status**: The manufacturing status of this part, meaning the information about where the part is in its manufacturing lifecycle.
+* **Needs review**: If you think parts informations maybe are inaccurate or incomplete and needs some later review/checking, you can set this flag. A part with this flag is marked, so that users know the informations are not completly trustworthy.
+* **Favorite**: Parts with this flag are highlighted in parts lists
+* **Mass**: The mass of a single piece of this part (so of a single transistor). Given in grams.
+* **Internal Part number** (IPN): Each part is automatically assigned an numerical ID which identifies a part in the database. This ID depends on when a part was created and can not be changed. If you want to assign your own unique identifiers, or sync parts identifiers with the identifiers of another database you can use this field.
+
+### Stock / Part lot
+A part can have many stock at multiple different locations. This is represented by part lots / stocks, which consists basically of a storelocation (so where are the parts of this lot are stored) and an amount (how many parts are there).
+
+### Purchase Informations
+The purchase informations describe where the part can be bought (at which vendors) and to which prices.
+The first part (the order information) describes at which supplier the part can be bought and which is the name of the part under which you can order the part there.
+An order information can contain multiple price informations, which describes the prices for the part at the supplier including bulk discount, etc.
+
+### Parameters
+Parameters represents various specifications / parameters of a part, like the the maximum current of a diode, etc. The advantage of using parameters instead of just putting the data in the comment field or so, is that you can filter for parameters values (including ranges and more) later on. 
+Parameters describe can describe numeric values and/or text values for which they can be filtered. This basically allows you to define custom fields on a part.
+
+Using the group field a parameter allows you to group parameters together in the info page later (all parameters with the same group value will be shown under the same group title).
+
+## Core data
+### Category
+
+A category is used to group parts logically by their function (e.g. all NPN transistors would be put in a "NPN-Transistors" category).
+Categories are hierarchical structures meaning that you can create logical trees to group categories together. A possible category tree could look like this:
+
+* Active Components
+    * Transistors
+        * BJTs
+            * NPN
+            * PNP
+    * ICs
+        * Logic ICs
+        * MCUs
+* Passive Components
+    * Capacitors
+    * Resitors
+
+### Supplier
+A Supplier is a vendor / distributor where you can buy/order parts. Price informations of parts are associated with a supplier. 
+
+### Manufacturer
+A manufacturer represents the company that manufacturer / build various parts (not necessary sell them). If the manufacturer also sell the parts, you have to create a supplier for that.
+
+### Storelocation
+A storelocation represents a place where parts can be stored. This could be a box, a shelf or other things (like the SMD feeder of a machine or so).
+
+Storelocations are hierarchical to represent storelocations contained in each other. 
+An example tree could look like this:
+* Shelf 1
+   * Box 1
+   * Box 2
+      * Box shelf A1
+      * Box shelf A2
+      * Box shelf B1
+      * Box shelf B2
+* Shelf 2
+* Cupboard
+
+Storelocations should be defined down to the smallest possible location, to make finding the part again easy.
+
+### Footprint
+In electronics many components have one of the common components cases / footprints. The footprint entity describes such common footprints, which can be assigned to parts.
+You can assign an image (and an 3D model) as an attachment to a footprint, which will be used as preview for parts with this footprint, even if the parts do not have an explicitly assigned preview image.
+
+Footprints are a hierachically which allows you to build logical sorted trees. An example tree could look like this:
+
+* Through-Hole components
+    * DIP
+       * DIP-8
+       * DIP-28
+       * DIP-28W
+    * TO
+       * TO-92
+* SMD components
+    * SOIC
+       * SO-8
+    * Resistors
+       * 0805
+       * 0603
+
+### Measurement Unit
+By default part instock is counted in number of individual parts, which is fine for things like electronic components, which exists only in integer quantities. However if you have things with fractional units like the length of a wire or the volume of a liquid, you have to define a measurement unit.
+The measurement unit represents a physical quantity like mass, volume or length.
+
+You can define a short unit for it (like m for Meters, or g for gramms) which will be shown, when a quantity of a part with this unit is shown. 
+
+### Currency
+By default all prices are set in the base currency configured for the instance (by default euros). If you want to use multiple currencies together (as e.g. vendors use foreign currencies for their price and you do not want to update the prices for every exchange rate change), you have to define these currencies here.
+
+You can set an exchange rate here in terms of the base currency (or fetch it from the internet if configured). The exchange rate will be used to show users the prices in their preferred currency.
+
+## Attachments
+### Attachment
+An attachment is an file that can be associated with another entity (like a Part, Storelocation, User, etc.). This could for example be a datasheet in a Part, the logo of a vendor or some CAD drawing of a footprint.
+
+An attachment has an attachment type (see below), which groups the attachments logically (and optionally restricts the allowed file types), a name describing the attachment and a file. The file can either be uploaded to the server and stored there, or given as a link to a file on another webpath. If configured in the settings, it is also possible that the webserver downloads the file from the supplied website and stores it locally on the server.
+
+By default all uploaded files, are accessible for everyone (even non logged in users), if the link is known. If your Part-DB instance is publicly available and you want to store private/sensitve files on it, you should mark the attachment as "Private attachment". Private attachments are only accessible to users, which has the permission to access private attachments.
+Please not, that no thumbnails are generated for private attachments, which can have an performance impact.
+
+Part-DB ships some preview images for various common footprints like DIP-8 and others, as internal ressources. These can be accessed/searched by typing the keyword in the URL field of a part and choosing one of the choices from the dropdown.
+
+### Preview image / attachment
+Most entities with attachments allow you to select one of the defined attachments as "Preview image". You can select an image attachment here, that previews the entity, this could be a picture of a Part, the logo of a manufacturer or supplier, the schematic symbol of a category or the image of an footprint.
+The preview image will be shown in various locations together with the entities name.
+
+Please note that as long as the picture is not secret, it should be stored on the Part-DB instance (by upload, or letting Part-DB download the file) and *not* be marked as a private attachments, so that thumbnails can be generated for the picture (which improves performance). 
+
+
+### Attachment types
+Attachment types define logical groups of attachments. For example you could define an attachment group "Datasheets" where all datasheets of Parts, Footprints, etc. belong in, "Pictures" for preview images and more.
+You can define file type restrictions, which file types and extensions are allowed for files with that attachment type.
+
+## User System
+### User
+Each person which should be able to use Part-DB (by logging in) is represented by an user entity, which defines things like access rights, the password, and other things. For security reasons, every person which will use Part-DB should use its own personal account with an secret password. This allows to track activity of the users via the log.
+
+There is a special user called `anonymous`, whose access rights are used to determine what an non-logged in user can do. Normally the anonymous user should be the most restricted user.
+
+For simplification of access management users can be assigned to groups.
+
+### Group
+A group is entity, to which users can be assigned to. This can be used to logically group users by for example organisational structures and to simplify permissions managment, as you can define groups with access rights for common use cases and then just assign users to them, without the need to change every permission on the users individually.
+
+## Labels
+### Label profiles
+A label profile represents an template for a label (for a storelocation, a part or part lot). It consists of a size, an barcode type and the content. There are various placeholders which can be inserted in the text content and which will be used replaced with data for the actual thing.
+
+You do not have to define a label profile to generate labels (you can just set the settings on the fly in the label dialog), however if you want to generate many labels, it is recommended to save the settings as label profile, to save it for later usage. This ensures that all generated labels look the same.

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/docker/.gitignore

@@ -1,3 +0,0 @@
-db/
-public_media/
-uploads/

docs/index.md

@@ -0,0 +1,65 @@
+---
+title: Home
+layout: home
+nav_order: 0
+---
+
+# Part-DB
+Part-DB is an Open-Source inventory managment system for your electronic components.
+It is installed on a web server and so can be accessed with any browser without the need to install additional software.
+
+## Demo
+If you want to test Part-DB without installing it, you can use [this](https://part-db.herokuapp.com) Heroku instance. 
+(Or this link for the [German Version](https://part-db.herokuapp.com/de/)). 
+
+You can log in with username: *user* and password: *user*.
+
+Every change to the master branch gets automatically deployed, so it represents the currenct development progress and is
+maybe not completly stable. Please mind, that the free Heroku instance is used, so it can take some time when loading the page
+for the first time.
+
+## Features
+* Inventory managment of your electronic parts. Each part can be assigned to a category, footprint, manufacturer 
+and multiple store locations and price informations. Parts can be grouped using tags. You can associate various files like datasheets or pictures with the parts.
+* Multi-Language support (currently German, English, Russian, Japanese and French (experimental))
+* Barcodes/Labels generator for parts and storage locations, scan barcodes via webcam using the builtin barcode scanner
+* User system with groups and detailed (fine granular) permissions. 
+Two-factor authentication is supported (Google Authenticator and Webauthn/U2F keys) and can be enforced for groups. Password reset via email can be setuped.
+* Import/Export system (partial working)
+* Project managment: Create projects and assign parts to the bill of material (BOM), to show how often you could build this project and directly withdraw all components needed from DB
+* Event log: Track what changes happens to your inventory, track which user does what. Revert your parts to older versions.
+* Responsive design: You can use Part-DB on your PC, your tablet and your smartphone using the same interface.
+* MySQL and SQLite (experimental) supported as database backends
+* Support for rich text descriptions and comments in parts
+* Support for multiple currencies and automatic update of exchange rates supported
+* Powerful search and filter function, including parametric search (search for parts according to some specifications)
+
+
+With this features Part-DB is useful to hobbyists, who want to keep track of their private electronic parts inventory,
+or makerspaces, where many users have should have (controlled) access to the shared inventory.
+
+Part-DB is also used by small companies and universities for managing their inventory.
+
+## License
+Part-DB is licensed under the GNU Affero General Public License v3.0 (or at your opinion any later).
+This mostly means that you can use Part-DB for whatever you want (even use it commercially)
+as long as you publish the source code for every change you make under the AGPL, too.
+
+See [LICENSE](https://github.com/Part-DB/Part-DB-symfony/blob/master/LICENSE) for more informations.
+
+## Donate for development
+If you want to donate to the Part-DB developer, see the sponsor button in the top bar (next to the repo name).
+There you will find various methods to support development on a monthly or a one time base.
+
+## Built with
+* [Symfony 5](https://symfony.com/): The main framework used for the serverside PHP
+* [Bootstrap 5](https://getbootstrap.com/) and [Bootswatch](https://bootswatch.com/): Used as website theme
+* [Fontawesome](https://fontawesome.com/: Used as icon set
+* [Hotwire Stimulus](https://stimulus.hotwired.dev/) and [Hotwire Turbo](https://turbo.hotwired.dev/): Frontend Javascript
+
+## Authors
+* **Jan Böhmer** - *Inital work and Maintainer* - [Github](https://github.com/jbtronics/)
+
+See also the list of [contributors](https://github.com/Part-DB/Part-DB-symfony/graphs/contributors) who participated in this project.
+
+Based on the original Part-DB by Christoph Lechner and K. Jacobs

docs/installation/choosing_database.md

@@ -0,0 +1,29 @@
+---
+title: "Choosing database: SQLite or MySQL"
+layout: default
+parent: Installation
+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).
+
+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).
+
+## 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
+
+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. 
+
+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 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.

docs/installation/index.md

@@ -0,0 +1,9 @@
+---
+layout: default
+title: Installation
+nav_order: 3
+has_children: true
+---
+
+# Installation
+Below you can find some guides to install Part-DB.

docs/installation/installation_docker.md

@@ -1,3 +1,9 @@
+---
+title: Installation using Docker
+layout: default
+parent: Installation
+---
+
 # Installation of Part-DB via docker
 
 **Warning: The methods described here, configure PHP without HTTPS and therefore should only be used locally. If you want to expose Part-DB to the internet, you have to configure a reverse proxy!**

docs/installation/installation_guide-debian.md

@@ -1,3 +1,9 @@
+---
+title: Direct Installation on Debian 11
+layout: default
+parent: Installation
+---
+
 # 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.

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,136 @@
+---
+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 |