From cbedb377acc5f063ba8cf431d4fdbbc97c70457b Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Jan=20B=C3=B6hmer?= Date: Thu, 28 Aug 2025 23:49:01 +0200 Subject: [PATCH] Added migration guide --- docs/upgrade/1_to_2.md | 58 +++++++++++++++++++++++++++++++++++++++++- 1 file changed, 57 insertions(+), 1 deletion(-) diff --git a/docs/upgrade/1_to_2.md b/docs/upgrade/1_to_2.md index 799e9ec6..e063c49d 100644 --- a/docs/upgrade/1_to_2.md +++ b/docs/upgrade/1_to_2.md @@ -25,8 +25,64 @@ ships all required dependencies and is always up to date with the latest require about the requirements at all. ## Changes +* Configuration is now preferably done via a web settings interface. You can still use environment variables, these overwrite +the settings in the web interface. Existing configuration will still work, but you should consider migriting them to the +web interface as described below. * The `config/banner.md` file that could been used to customize the banner text, was removed. You can now set the banner text directly in the admin interface, or by setting the `BANNER` environment variable. If you want to keep your existing banner text, you will have to copy it from the `config/banner.md` file to the admin interface or set the `BANNER` environment variable. - +* The parameters `partdb.sidebar.items`, `partdb.sidebar.root_node_enable` and `partdb.sidebar.root_expanded` in `config/parameters.yaml`, +were removed. You can configure them now directly in the admin interface. +* Updated icon set. As fontawesome 7 is now used, some icons have changed slightly. + +## Upgrade installation + +The upgrade process works very similar to a normal (minor release) upgrade. + +### Direct installation + +**Be sure to execute the following steps as the user that owns the Part-DB files (e.g. `www-data`, or your webserver user). So prepend a `sudo -u wwww-data` where necessary.** + +1. Make a backup of your existing Part-DB installation, including the database, data directories and the configuration files and `.env.local` file. +The `php bin/console partdb:backup` command can help you with this. +2. Pull the v2 version. For git installation you can do this with `git checkout v2.0.0` (or newer version) +3. Run `composer install --no-dev -o` to update the dependencies. +4. Run `yarn install` and `yarn build` to update the frontend assets. +5. Rund `php bin/console doctrine:migrations:migrate` to update the database schema. +6. Clear the cache with `php bin/console cache:clear`. +7. Open your Part-DB instance in the browser and log in as an admin user. +8. Go to the user or group permissions page, and give yourself (and other administrators) the right to change system settings (under "System" and "Configuration"). +9. You can now go to the settings page (under "System" and "Settings") and check if all settings are correct. +10. Parameters which were previously set via environment variables are greyed out and cannot be changed in the web interface. +If you want to change them, you must migrate them to the settings interface as described below. + +### Docker installation +1. Make a backup of your existing Part-DB installation, including the database, data directories and the configuration files and the file where you configure the docker environment variables. +2. Stop the existing Part-DB container with `docker compose down` +3. Ensure that your docker compose file uses the new latest images (either `latest` or `2` tag). +4. Pull the new images with `docker compose pull` and start the container with `docker compose up -d` +5. If you have database automigration disabled, run `docker exec --user=www-data partdb php bin/console doctrine:migrations:migrate` to update the database schema. +6. Open your Part-DB instance in the browser and log in as an admin user. +7. Go to the user or group permissions page, and give yourself (and other administrators) +the right to change system settings (under "System" and "Configuration"). +8. You can now go to the settings page (under "System" and "Settings") +9. Parameters which were previously set via environment variables are greyed out and cannot be changed in the web interface. +If you want to change them, you must migrate them to the settings interface as described below. + +## Migrate environment variable configuration to settings interface +As described above, configuration can now be done via the web interface, and can be overwritten by environment variables, so +that existing configuration should still work. However, if a parameter is set via an environment variable, it cannot be changed in the web interface. +To change it, you must migrate your environment variable configuration to the new system. + +For this there is the new console command `settings:migrate-env-to-settings`, which reads in all environment variables used to overwrite +settings and write them to the database, so that you can safely delete them from your environment variable configuration afterwards, without +loosing your configuration. + +To run the command, execute `php bin/console settings:migrate-env-to-settings --all` as webserver user (or run `docker exec --user=www-data -it partdb php bin/console settings:migrate-env-to-settings --all` for docker containers). +It will list you all environment variables, it found and ask you for confirmation to migrate them. Answer with `yes` to migrate them and hit enter. + +After the migration run successfully, the contents of your environment variables are now stored in the database and you can safely remove them from your environment variable configuration. +Go through the environment variables listed by the command and remove them from your environment variable configuration (e.g. `.env.local` file or docker compose file), or just comment them out for now. + +If you want to keep some environment variables, just leave them as they are, they will still work as before, the migration command only affects the settings stored in the database.