From a4e68ea2d6d1d6743611a2dcb00fb89d34e270e8 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Jan=20B=C3=B6hmer?= Date: Sun, 26 Mar 2023 00:32:03 +0100 Subject: [PATCH] Added documentation about PartKeepr migration process --- docs/index.md | 4 +-- docs/partkeepr_migration.md | 51 ++++++++++++++++++++++++++++++++++ docs/upgrade_legacy.md | 1 + docs/usage/console_commands.md | 1 + docs/usage/import_export.md | 2 ++ 5 files changed, 57 insertions(+), 2 deletions(-) create mode 100644 docs/partkeepr_migration.md diff --git a/docs/index.md b/docs/index.md index 9bc5b1a4..42d5c516 100644 --- a/docs/index.md +++ b/docs/index.md @@ -28,7 +28,7 @@ It is installed on a web server and so can be accessed with any browser without * 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. * Optional support for single sign-on (SSO) via SAML (using an intermediate service like [Keycloak](https://www.keycloak.org/) you can connect Part-DB to an existing LDAP or Active Directory server) -* Import/Export system (partial working) +* Import/Export system * 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. @@ -36,7 +36,7 @@ It is installed on a web server and so can be accessed with any browser without * 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) - +* Easy migration from an existing PartKeepr instance (see [here]({%link partkeepr_migration.md %})) 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. diff --git a/docs/partkeepr_migration.md b/docs/partkeepr_migration.md new file mode 100644 index 00000000..41a1ff40 --- /dev/null +++ b/docs/partkeepr_migration.md @@ -0,0 +1,51 @@ +--- +layout: default +title: Migrate from PartKeepr to Part-DB +nav_order: 101 +--- + +# Migrate from PartKeepr to Part-DB + +{: .warning } +> This feature is currently in beta. Please report any bugs you find. + +This guide describes how to migrate from [PartKeepr](https://partkeepr.org/) to Part-DB. + +Part-DB has a built-in migration tool, which can be used to migrate the data from an existing PartKeepr instance to +a new Part-DB instance. Most of the data can be migrated, however there are some limitations, you can find below. + +## What can be imported +* Datastructures (Categories, Footprints, Storage Locations, Manufacturers, Distributors, Part Measurement Units) +* Basic part informations (Name, Description, Comment, etc.) +* Attachments and images of parts, projects, footprints, manufacturers and storage locations +* Part prices (distributor infos) +* Part parameters +* Projects (including parts and attachments) +* Users (optional): Passwords however will be not migrated, and need to be reset later + +## What can't be imported +* Metaparts (A dummy version of the metapart will be created in Part-DB, however it will not function as metapart) +* Multiple manufacturers per part (only the last manufacturer of a part will be migrated) +* Overage information for project parts (the overage info will be set as comment in the project BOM, but will have no effect) +* Batch Jobs +* Parameter Units (the units will be written into the parameters) +* Project Reports and Project Runs +* Stock history +* Any kind of PartKeepr preferences + +## How to migrate +1. Install Part-DB like described in the installation guide. You can use any database backend you want (mysql or sqlite). Run the database migration, but do not create any new data yet. +2. Export your PartKeepr database as XML file using [mysqldump](https://dev.mysql.com/doc/refman/8.0/en/mysqldump.html): +When the MySQL database is running on the local computer and you are root you can just run the command `mysqldump --xml PARTKEEPR_DATABASE --result-file pk.xml`. +If your server is remote or your MySQL authentication is different, you need to run `mysqldump --xml -h PARTKEEPR_HOST -u PARTKEEPR_USER -p PARTKEEPR_DATABASE`, where you replace `PARTKEEPR_HOST` +with the hostname of your MySQL database and `PARTKEEPR_USER` with the username of MySQL user which has access to the PartKeepr database. You will be asked for the MySQL user password. +3. Go the Part-DB main folder and run the command `php bin/console partdb:migrations:import-partkeepr path/to/pk.xml`. This step will delete all existing data in the Part-DB database and import the contents of PartKeepr. +4. Copy the contents of `data/files/` from your PartKeepr installation to the `uploads/` folder of your Part-DB installation and the contents of `data/images` from PartKeepr to `public/media/` of Part-DB. +5. Clear the cache of Part-DB by running: `php bin/console cache:clear` +6. Go to the Part-DB web interface. You can login with the username `admin` and the password, which is shown during the installation process of Part-DB (step 1). You should be able to see all the data from PartKeepr. + +## Import users +If you want to import the users (mostly the username and email address) from PartKeepr, you can add the `--import-users` option on the database import command (step 3): `php bin/console partdb:migrations:import-partkeepr --import-users path/to/pk.xml`. + +All imported users of PartKeepr will be assigned to a new group "PartKeepr Users", which has normal user permissions (so editing data, but no administrative tasks). You can change the group and permissions later in Part-DB users managment. +Passwords can not be imported from PartKeepr and all imported users get marked as disabled user. So to allow users to login, you need to enable them in the user management and assign a password. \ No newline at end of file diff --git a/docs/upgrade_legacy.md b/docs/upgrade_legacy.md index ca9ee053..d43fa2ed 100644 --- a/docs/upgrade_legacy.md +++ b/docs/upgrade_legacy.md @@ -1,6 +1,7 @@ --- layout: default title: Upgrade from legacy Part-DB version (<1.0) +nav_order: 100 --- # Upgrade from legacy Part-DB version diff --git a/docs/usage/console_commands.md b/docs/usage/console_commands.md index f762f614..7a23483a 100644 --- a/docs/usage/console_commands.md +++ b/docs/usage/console_commands.md @@ -31,6 +31,7 @@ You can get help for every command with the parameter `--help`. See `php bin/con * `partdb:migrations:convert-bbcode`: Migrate the old BBCode markup codes used in legacy Part-DB versions (< 1.0.0) to the new markdown syntax * `partdb:attachments:clean-unused`: Remove all attachments which are not used by any database entry (e.g. orphaned attachments) * `partdb:cache:clear`: Clears all caches, so the next page load will be slower, but the cache will be rebuild. This can maybe fix some issues, when the cache were corrupted. This command is also needed after changing things in the `parameters.yaml` file or upgrading Part-DB. +* `partdb:migrations:import-partkeepr`: Imports an mysqldump XML dump of a PartKeepr database into Part-DB. This is only needed for users, which want to migrate from PartKeepr to Part-DB. *All existing data in the Part-DB database is deleted!* ## Database commands * `php bin/console doctrine:migrations:migrate`: Migrate the database to the latest version diff --git a/docs/usage/import_export.md b/docs/usage/import_export.md index c16f5767..09e4b163 100644 --- a/docs/usage/import_export.md +++ b/docs/usage/import_export.md @@ -16,6 +16,8 @@ Part-DB offers the possibility to import existing data (parts, datastructures, e > administrators. If you want to allow other users to import data, or can not import data, check the permissions of the user. You can enable import for each data structure > individually in the permissions settings. +If you want to import data from PartKeepr you might want to look into the [PartKeepr migration guide]({% link upgrade_legacy.md %}). + ### Import parts Part-DB supports the import of parts from CSV files and other formats. This can be used to import existing parts from other databases or datasources into Part-DB. The import can be done via the "Tools -> Import parts" page, which you can find in the "Tools" sidebar panel.