Part-DB.Part-DB-server/docs/upgrade/1_to_2.md

---
layout: default
title: Upgrade from Part-DB 1.x to 2.x
nav_order: 1
has_children: false
---

# Upgrade from Part-DB 1.x to 2.x

Part-DB 2.0 is a major release that changes a lot of things internally, but it is still compatible with Part-DB 1.x.
Depending on your preferences, you will have to do some changes to your Part-DB installation, this document will guide
you through the upgrade process.

## New requirements
*If you are running Part-DB inside a docker container, you can skip this section, as the new requirements are already
fulfilled by the official Part-DB docker image.*

Part-DB 2.0 requires at least PHP 8.2 (newer versions are recommended). So if your existing Part-DB installation is still
running PHP 8.1, you will have to upgrade your PHP version first.
The minimum required version of node.js is now 20.0 or newer, so if you are using 18.0, you will have to upgrade it too.

Most distributions should have the possibility to get backports for PHP 8.4 and modern nodejs, so you should be able to
easily upgrade your system to the new requirements. Otherwise, you can use the official Part-DB docker image, which
ships all required dependencies and is always up to date with the latest requirements, so that you do not have to worry
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.