diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index eda4f2c9..d31c904e 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -4,21 +4,19 @@ Thank you for consider to contribute to Part-DB! Please read the text below, so your contributed content can be contributed easily to Part-DB. You can contribute to Part-DB in various ways: -* Report bugs and request new features via [issues](https://github.com/Part-DB/Part-DB-symfony/issues) +* Report bugs and request new features via [issues](https://github.com/Part-DB/Part-DB-server/issues) * Improve translations (via https://part-db.crowdin.com/part-db) -* Improve code (either PHP, Javascript or HTML templates) by creating a [pull request](https://github.com/Part-DB/Part-DB-symfony/pulls) +* Improve code (either PHP, Javascript or HTML templates) by creating a [pull request](https://github.com/Part-DB/Part-DB-server/pulls) ## Translations The recommended way to create/improve translations is to use the online platform [Crowdin](https://part-db.crowdin.com/part-db). Register an account there and join the Part-DB team. -If you want to start translation for a new language that does not have an entry on Crowdin yet, send an message to `@jbtronics`. +If you want to start translation for a new language that does not have an entry on Crowdin yet, send a message to `@jbtronics`. Part-DB uses translation keys (e.g. part.info.title) that are sorted by their usage, so you will most likely have to lookup, how the key was translated in other languages (this is possible via the "Other languages" dropdown in the translation editor). -Translation keys can be extracted from templates and PHP codes by running `bin/console translation:extract`. - ## Project structure Part-DB uses symfony's recommended [project structure](https://symfony.com/doc/current/best_practices.html). Interesting folders are: @@ -45,8 +43,8 @@ Part-DB uses [Easy Coding Standard](https://github.com/symplify/easy-coding-stan * To check your code for valid code style run `vendor/bin/ecs check src/` * To fix violations run `vendor/bin/ecs check src/` (please checks afterwards if the code is valid afterwards) -## TravisCI -Part-DB has a [Travis-CI](https://travis-ci.com/Part-DB/Part-DB-symfony) instance running, that checks for every commit and contribute if the following things are working: +## GitHub actions +Part-DB uses GitHub actions to run various tests and checks on the code: * Yarn dependencies can compile * PHPunit tests run successful * Config files, translations and templates has valid syntax @@ -54,4 +52,4 @@ Part-DB has a [Travis-CI](https://travis-ci.com/Part-DB/Part-DB-symfony) instanc * No known vulnerable dependecies are used * Static analysis successful (phpstan with `--level=2`) -Further the code coverage of the PHPunit tests is determined. +Further the code coverage of the PHPunit tests is determined and uploaded to [CodeCov](https://codecov.io/gh/Part-DB/Part-DB-server). diff --git a/README.md b/README.md index 50980ab5..d9adeb87 100644 --- a/README.md +++ b/README.md @@ -1,7 +1,7 @@ [![Scrutinizer Code Quality](https://scrutinizer-ci.com/g/Part-DB/Part-DB-symfony/badges/quality-score.png?b=master)](https://scrutinizer-ci.com/g/Part-DB/Part-DB-symfony/?branch=master) ![PHPUnit Tests](https://github.com/Part-DB/Part-DB-symfony/workflows/PHPUnit%20Tests/badge.svg) ![Static analysis](https://github.com/Part-DB/Part-DB-symfony/workflows/Static%20analysis/badge.svg) -[![codecov](https://codecov.io/gh/Part-DB/Part-DB-symfony/branch/master/graph/badge.svg)](https://codecov.io/gh/Part-DB/Part-DB-symfony) +[![codecov](https://codecov.io/gh/Part-DB/Part-DB-symfony/branch/master/graph/badge.svg)](https://codecov.io/gh/Part-DB/Part-DB-server) ![GitHub License](https://img.shields.io/github/license/Part-DB/Part-DB-symfony) ![PHP Version](https://img.shields.io/badge/PHP-%3E%3D%207.4-green) @@ -9,17 +9,17 @@ ![Docker Build Status](https://github.com/Part-DB/Part-DB-symfony/workflows/Docker%20Image%20Build/badge.svg) [![Crowdin](https://badges.crowdin.net/e/8325196085d4bee8c04b75f7c915452a/localized.svg)](https://part-db.crowdin.com/part-db) -*When updgrading from a version from before 2022-11-27, please read [this](https://github.com/Part-DB/Part-DB-symfony/discussions/193) before upgrading!* - **[Documentation](https://docs.part-db.de/)** # 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. -The version in this Repository is a complete rewrite of the legacy [Part-DB](https://github.com/Part-DB/Part-DB) (Version < 1.0) based on a modern framework. Currently it is still missing some (less) features from the old version (see [UPGRADE.md](./UPGRADE.md)) for more details, but also many huge improvements and advantages compared to the old version. If you start completly new with Part-DB it is recommended that you use the version from this repository, as it is actively developed. +The version in this Repository is a complete rewrite of the legacy [Part-DB](https://github.com/Part-DB/Part-DB) (Version < 1.0) based on a modern framework. +Currently, it is still missing some (minor) features from the old version (see [UPGRADE.md](https://docs.part-db.de/upgrade_legacy.html)) for more details, but also many huge improvements and advantages compared to the old version. +If you start completely new with Part-DB it is recommended that you use the version from this repository, as it is actively developed. -If you find a bug, please open an [Issue on Github](https://github.com/Part-DB/Part-DB-symfony/issues) so it can be fixed for everybody. +If you find a bug, please open an [Issue on Github](https://github.com/Part-DB/Part-DB-server/issues) so it can be fixed for everybody. ## Demo If you want to test Part-DB without installing it, you can use [this](https://part-db.herokuapp.com) Heroku instance. @@ -27,28 +27,28 @@ If you want to test Part-DB without installing it, you can use [this](https://pa 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 +Every change to the master branch gets automatically deployed, so it represents the current development progress and is +maybe not completely 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. +* Inventory management of your electronic parts. Each part can be assigned to a category, footprint, manufacturer +and multiple store locations and price information. 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 +* Project management: 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 +* MySQL and SQLite 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, +With these 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. @@ -61,18 +61,15 @@ Part-DB is also used by small companies and universities for managing their inve * For building the client side assets **yarn** and **nodejs** is needed. ## Installation -**Caution:** It is possible to upgrade the old Part-DB databases. -Anyhow, the migrations that will be made, are not compatible with the old Part-DB versions, so you must not use the old Part-DB versions with the new database, or the DB could become corrupted. -Also after the migration it is not possible to go back to the old database scheme, so make sure to make a backup of your database beforehand. -See [UPGRADE](UPGRADE.md) for more infos. +If you want to upgrade your legacy (< 1.0.0) version of Part-DB to this version, please read [this](https://docs.part-db.de/upgrade_legacy.html) first. -*Hint:* A docker image is available under [jbtronics/part-db1](https://hub.docker.com/r/jbtronics/part-db1). How to setup Part-DB via docker is described [here](https://docs.part-db.de/installation/installation_docker.html). +*Hint:* A docker image is available under [jbtronics/part-db1](https://hub.docker.com/r/jbtronics/part-db1). How to set up Part-DB via docker is described [here](https://docs.part-db.de/installation/installation_docker.html). -**Below you find some general hints for installation, see [here](https://docs.part-db.de/installation/installation_guide-debian.html) for a detailed guide how to install Part-DB on Debian/Ubuntu.** +**Below you find some very rough outline of the installation process, see [here](https://docs.part-db.de/installation/) for a detailed guide how to install Part-DB.** 1. Copy or clone this repository into a folder on your server. 2. Configure your webserver to serve from the `public/` folder. See [here](https://symfony.com/doc/current/setup/web_server_configuration.html) -for additional informations. +for additional information. 3. Copy the global config file `cp .env .env.local` and edit `.env.local`: * Change the line `APP_ENV=dev` to `APP_ENV=prod` * If you do not want to use SQLite, change the value of `DATABASE_URL=` to your needs (see [here](http://docs.doctrine-project.org/projects/doctrine-dbal/en/latest/reference/configuration.html#connecting-using-a-url)) for the format. @@ -95,6 +92,9 @@ and repeat the steps 4. to 7. Normally a random password is generated when the admin user is created during inital database creation, however you can set the inital admin password, by setting the `INITIAL_ADMIN_PW` env var. +You can configure Part-DB to your needs by changing environment variables in the `.env.local` file. +See [here](https://docs.part-db.de/configuration.html) for more information. + ### Reverse proxy If you are using a reverse proxy, you have to ensure that the proxies sets the `X-Forwarded-*` headers correctly, or you will get HTTP/HTTPS mixup and wrong hostnames. If the reverse proxy is on a different server (or it cannot access Part-DB via localhost) you have to set the `TRUSTED_PROXIES` env variable to match your reverse proxies IP-address (or IP block). You can do this in your `.env.local` or (when using docker) in your `docker-compose.yml` file. @@ -106,13 +106,13 @@ There you will find various methods to support development on a monthly or a one ## 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 +* [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* - [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. +See also the list of [contributors](https://github.com/Part-DB/Part-DB-server/graphs/contributors) who participated in this project. Based on the original Part-DB by Christoph Lechner and K. Jacobs @@ -121,4 +121,4 @@ Part-DB is licensed under the GNU Affero General Public License v3.0 (or at your 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. +See [LICENSE](https://github.com/Part-DB/Part-DB-server/blob/master/LICENSE) for more information. diff --git a/SECURITY.md b/SECURITY.md index 87224069..02775f95 100644 --- a/SECURITY.md +++ b/SECURITY.md @@ -2,8 +2,11 @@ ## Supported Versions -This is an alpha version without releases yet. Only the newest version from the master branch is supported. +Only the most recent release of Part-DB is supported. + +(Unreleased) development versions are not supported and might contain security vulnerabilities, which might not be +fixed before the next release. However, if you find a security vulnerability in a development version, please report it ## Reporting a Vulnerability -If you find an vulnerability contact the maintainer directly (Email: security@part-db.de). +If you find a security vulnerability, contact the maintainer directly (Email: security@part-db.de). diff --git a/UPGRADE.md b/UPGRADE.md deleted file mode 100644 index c498120f..00000000 --- a/UPGRADE.md +++ /dev/null @@ -1,35 +0,0 @@ -# Upgrade from legacy Versions (Part-DB 0.5/0.6) - -This document describes how to upgrade from an old Part-DB version (Part-DB 0.6 or older) to Part-DB 1.0. -The instructions on how to install the new version or upgrade from Part-DB 1.0 to a newer version, see -[README](README.md). - -## Breaking Changes -Please note that there are some breaking changes with the new version. -It is tried to keep the breaking changes as small as possible, so they should not have much impact for the most users: - * PHP 7.2.5 is required now (Part-DB 0.5 required PHP 5.4+, Part-DB 0.6 PHP 7.0). - PHP 7.2.5 (or newer) is shipped by all current major Linux distros now (and can be installed by third party sources on others), - Releases are available for Windows too, so almost everybody should be able to use PHP 7.2.5 - * Console access highly required. The installation of composer and frontend dependencies require console access, also - the managment commands are using CLI, so you should have console access on your server. - * Markdown/HTML is now used instead of BBCode for rich text in description and command fields. - It is possible to migrate your existing BBCode to Markdown via `php bin/console php bin/console partdb:migrations:convert-bbcode`. - * Server exceptions are not logged to Event log anymore. For security reasons (exceptions can contain sensitive informations) - exceptions are only logged to server log (by default under './var/log'), so only the server admins can access it. - * Profile labels are now saved in Database (before they were saved in a seperate JSON file). The profiles of legacy Part-DB versions can not be imported into new Part-DB 1.0 - * Label placeholders now use the `[[PLACEHOLDER]]` format instead of `%PLACEHOLDER%`. Also some placeholders has changed. - - ## Upgrade process - 1. Upgrade your existing Part-DB version the newest Part-DB 0.5.* version (in the moment Part-DB 0.5.8), like - described in the old Part-DB's repository. - 2. Make a backup of your database. If somethings goes wrong during migration, you can use this backup to start over. - 3. Setup the new Part-DB like described on [README](README.md) in section Installation. In `.env.local` enter the URL - to your old Part-DB database. - 4. Run `php bin/console partdb:migrations:convert-bbcode` to convert the BBCode used in comments and part description to the newly used markdown. - 5. Copy the content of `data/media` from the old Part-DB version into `public/media` in the new version. - 6. Run 'php bin/console cache:clear' - -You should now be able to access Part-DB and log in using your old credentials. - -**It is not possible to access the database using the old Part-DB version. -If you do so, this could damage your database.** Therefore it is recommended to remove the old Part-DB version. diff --git a/docs/index.md b/docs/index.md index 2d2c31b4..c2f561cf 100644 --- a/docs/index.md +++ b/docs/index.md @@ -21,23 +21,23 @@ It is installed on a web server and so can be accessed with any browser without > 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. +* Inventory management of your electronic parts. Each part can be assigned to a category, footprint, manufacturer + and multiple store locations and price information. 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. +* 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 +* Project management: 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 +* MySQL and SQLite 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, +With these 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.