mirror/Part-DB.Part-DB-server
1
0
Fork 1
mirror of https://github.com/Part-DB/Part-DB-server.git synced 2025-08-29 14:28:42 +02:00
Code Issues Projects Releases Packages Wiki Activity Actions 12

Added migration guide

Browse source
This commit is contained in:
Jan Böhmer 2025-08-28 23:49:01 +02:00
parent 6340bdd677
commit cbedb377ac
1 changed files with 57 additions and 1 deletions
Download patch file Download diff file Expand all files Collapse all files

56
docs/upgrade/1_to_2.md
View file

@ -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.