Versions Compared

Old Version 6

changes.mady.by.user Giuseppe Digilio (4Science)

Saved on

compared with

New Version Current

changes.mady.by.user Tim Donohue

Saved on

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.

...

  1. If upgrading from 6.x or below, install the new User Interface per the Installing DSpace guide. The JSPUI and XMLUI are no longer supported and cannot work with the DSpace 7 backend. You will need to install the new (Angular.io) User Interface.
    1. JSPUI or XMLUI based themes cannot be migrated.  That said, since the new Angular UI also uses Bootstrap, you may be able to borrow some basic CSS from your old themes.  But any HTML-level changes will need to be reimplemented in the new UI.
  2. If upgrading from 7.x or a prior version of 8.x, upgrading requires installing the latest version of the User Interface code
    1. Upgrade Node.js if necessary
    2. Download the latest dspace-angular release from the DSpace GitHub repository. You can choose to either download the zip or tar.gz file provided by GitHub, or you can use "git" to checkout the appropriate tag (e.g. dspace-8.0) or branch.
      1. If you've cloned or copied this code into your own GitHub or GitLab repository, you may wish to simply pull the latest tagged code into your codebase using Git. That will allow you to more easily address any "code conflicts" between your local changes and the new version of DSpace (if any are found).
      2. NOTE: For the rest of these instructions, we'll refer to the source code location as [dspace-angular].

    3. Install any updated local dependencies using Yarn in the [dspace-angular] source code directory:

      Code Block
      # change directory to our repo
cd [dspace-angular]
 
# install/update the local dependencies
yarn install


    4. Build the latest User Interface code for Production:  This rebuilds the latest code into the [dspace-angular]/dist directory

      Code Block
      yarn build:prod


    5. If upgrading from 7.0 or 7.1, read the updated version 7 Installation documentation. We now recommend deploying the compiled User Interface (in [dspace-angular]/dist) to a different directory (which we refer to as [dspace-ui-deploy]) in order to keep your running UI separate from the source code.  While it's still possible to run the UI using "yarn start" or "yarn run serve:ssr" (both of which use [dspace-angular]/dist),that older approach will mean that your site goes down / becomes unavailable anytime you rebuild (yarn build:prod).  To solve this issue:
      1. Create a separate [dspace-ui-deploy] location as described in the Installation documentation.
      2. Copy the [dspace-angular]/dist folder to that location, as described in the Installation documentation.
      3. Update your PM2 configuration or local startup scripts to use Node.js instead of Yarn.  Again, see the Installation documentation.

    6. If upgrading from 7.0 or 7.1, migrate your UI Configurations to YAML. In 7.2, the format of the UI configuration file changed from Typescript to YAML to support runtime configuration.  This means that customization of the older ./src/environment/environment.*.ts build-time configuration files has been superseded by corresponding ./config/config.*.yml configuration files (e.g. environment.prod.ts → config.prod.yml). 

      1. Either, manually convert your "environment.prod.ts" configurations to a new "./config/config.prod.yml" file, using the "./config/config.example.yml" as a guide, along with the User Interface Configuration documentation.
      2. OR, you can migrate your configurations using the provided "yarn env:yaml" migration script.  For detailed instructions, see the Migrate environment file to YAML second of the User Interface Configuration documentation.
    7. (Optional) Review Configuration changes to see if you wish to update any new configurations
      1. See the Release Notes
    8. Update your theme (if necessary), if you've created a custom theme in "src/themes" (or modified the existing "custom" or "dspace" themes in that location).  Pay close attention to the following...

      1. As of 7.3, a new "eager-theme.module.ts" and "lazy-theme.module.ts" has been added to both the "custom" and "dspace" themes to improve performance. Make sure to copy those to your custom theme.  Additionally, this new "eager-theme.module.ts" for your theme MUST be imported/enabled in "src/themes/eager-themes.module.ts". For example, for a local theme under "src/theme/my-theme":

        Code Block
        titlesrc/themes/eager-themes.module.ts
        import { EagerThemeModule as MyThemeEagerThemeModule } from './my-theme/eager-theme.module';
...
@NgModule({
  imports: [
    MyThemeEagerThemeModule,
  ],
})


      2. As of 8.0, you must migrate to standalone components. To migrate your theme to DSpace 8, you need to convert its components to the standalone architecture. To do so, simply follow the following steps:
        1. Fix any errors in all "<...>.module.ts" files in your theme folder. These errors may be mostly caused by importing old modules that are now deleted: simply delete any lines that refer to such modules;
        2. Run the command "ng generate @angular/core:standalone --path src/themes/<theme-folder>" to migrate the theme components to the standalone architecture, replacing <theme-folder> as necessary. WARNING: running the command while there are still errors on any <...>.module.ts will not produce the correct result, so make sure you have remedied those errors as mentioned in the previous step.
      3. Additional minor changes may have been made. It's usually best to look for changes to whichever theme you started from.  If you started your theme from the "custom" theme, look for any new changes made under "/src/themes/custom".  If you started your theme from the "dspace" theme, look for any new changes made under "/src/themes/dspace". 

        1. Using a tool like "git diff" from the commandline is often an easy way to see changes that occurred only in that directory.

          Code Block
          # Example which will show all the changes to "src/themes/dspace"
        Additional minor changes may have been made. It's usually best to look for changes to whichever theme you started from.  If you started your theme from the "custom" theme, look for any new changes made under "/src/themes/custom".  If you started your theme from the "dspace" theme, look for any new changes made under "/src/themes/dspace". 

        1. Using a tool like "git diff" from the commandline is often an easy way to see changes that occurred only in that directory.

          Code Block
          # Example which will show all the changes to "src/themes/dspace" (and all subfolders)
# between dspace-7.4 (tag) and dspace-8.0 (tag)
git diff dspace-7.4 dspace-8.0 -- src/themes/dspace/


      4. For the "custom" theme, the largest changes are often:
        1. New themeable components (subdirectories) may be added under "src/themes/custom/app", allowing you the ability to now change the look & feel of those components.
        2. The "src/themes/custom/theme.module.ts" file will likely have minor updates. This file registers any new themeable components (in the "const DECLARATIONS" section), and also registers new Modules, i.e. new UI features, (in the "@NgModule" → "imports" section).  Make sure those sections are updated in your copy of this file!
        3. Sometimes, new styles may be added in the "styles" folder, or new imports to "styles/theme.scss"
        4. If you have locally customized the styles or look & feel of any component, you should also verify that the component itself (in src/app) hasn't had updates.
      5. For the "dspace" theme, the largest changes are often:
        1. Existing customized components (subdirectories) under "src/themes/dspace/app/" may have minor updates, if improvements were made to that component.
        2. The "src/themes/custom/theme.module.ts" file will likely have minor updates. This file registers any new themeable components (in the "const DECLARATIONS" section), and also registers new Modules, i.e. new UI features, (in the "@NgModule" → "imports" section).  Make sure those sections are updated in your copy of this file!
        3. Sometimes, new styles may be added in the "styles" folder, or new imports to "styles/theme.scss"
        4. If you have locally customized the styles or look & feel of any additional component, you should also verify that the component itself (in src/app) hasn't had updates.
        Migrate to standalone components. To migrate your theme to DSpace 8, you need to convert its components to the standalone architecture. To do so, simply follow the following steps:
        1. Fix any errors in all "<...>.module.ts" files in your theme folder. These errors may be mostly caused by importing old modules that are now deleted: simply delete any lines that refer to such modules;
        2. Run the command "ng generate @angular/core:standalone --path src/themes/<theme-folder>" to migrate the theme components to the standalone architecture, replacing <theme-folder> as necessary. WARNING: running the command while there are still errors on any <...>.module.ts will not produce the correct result, so make sure you have remedied those errors as mentioned in the previous step.
    9. Restart the User Interface.  

      1. If you are using PM2 as described in the Installing DSpace instructions, you'd stop it and then start it back up as follows

        Code Block
        # Stop the running UI
pm2 stop dspace-ui.json

# If you had to update your PM2 configs, you may need to delete your old configuration from PM2
# pm2 delete dspace-ui.json

# Start it back up
pm2 start dspace-ui.json


      2. If you are using a different approach, you simply need to stop the running UI, and re-run:

        Code Block
        # First stop the running UI process by killing it (or similar)

# You MUST restart the UI from within the deployment directory
# See Installation Instructions for more info on this directory
cd [dspace-ui-deploy]
 
# Then restart the UI via Node.js
node ./dist/server/main.js


    10. Verify the UI and REST API are both working properly.


      1. If you hit errors, see the "Troubleshooting Upgrade Issues" section below.  Additionally, check the "Common Installation Issues" section of the Installing DSpace documentation for other common misconfiguration or setup issues.

Troubleshooting Upgrade Issues

...