forked from mirror/Part-DB.Part-DB-server
Improved README and docs
This commit is contained in:
Jan Böhmer
parent
421f2682d6
commit
b8171f99ba
5 changed files with 40 additions and 74 deletions
|
|
@ -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).
|
||||
|
|
|
|||
44
README.md
44
README.md
|
|
@ -1,7 +1,7 @@
|
|||
[](https://scrutinizer-ci.com/g/Part-DB/Part-DB-symfony/?branch=master)
|
||||
|
||||
|
||||
[](https://codecov.io/gh/Part-DB/Part-DB-symfony)
|
||||
[](https://codecov.io/gh/Part-DB/Part-DB-server)
|
||||
|
||||
|
||||
|
||||
|
|
@ -9,17 +9,17 @@
|
|||
|
||||
[](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.
|
||||
|
|
|
|||
|
|
@ -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).
|
||||
|
|
|
|||
35
UPGRADE.md
35
UPGRADE.md
|
|
@ -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.
|
||||
|
|
@ -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.
|
||||
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.
|
||||
|
|
|
|||
Loading…
Add table
Add a link
Reference in a new issue