Page History

...

1. Upgrade Node.js if necessary based on the version of Node.js listed in the Installing the Frontend (User Interface) documentation
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-9.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 NPM in the [dspace-angular] source code directory:

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

   
   

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

   Code Block
   npm run build:prod

   
   

5. (Optional) Review Configuration changes to see if you wish to update any new configurations
   1. See the Release Notes
6. 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. If you are upgrading from 7.0, 7.1 or 7.2, 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
      title src/themes/eager-themes.module.ts
      import { EagerThemeModule as MyThemeEagerThemeModule } from './my-theme/eager-theme.module'; ... @NgModule({ imports: [ MyThemeEagerThemeModule, ], })

      
      

   2. If you are upgrading from 7.x, you must migrate to standalone components.  To migrate your theme, 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. If you are upgrading from 8.x, you must migrate to using Angular Control Flow syntax in all HTML templates (*.component.html file). This means that all usages of "ngIf" and "ngFor" are now replaced with their equivalent "control flow" syntax (e.g. "@if" and "@for"). If your theme has any custom HTML templates, they may require updates. Angular provides an automated migration tool which can be used to perform this migration (this is the same tool that was used to migrate all DSpace code in #3997).
   4. As of 9.0, all SASS/CSS styles use Bootstrap 5. This means that some CSS and SASS styles have changed slightly.  This may also impact your themes, as they may need to migrate Bootstrap 4 styles into Bootstrap 5 styles.  See the Bootstrap 5 migration guide for details.  For additional examples, see #3506 which updated DSpace to use Bootstrap 5.
   5. 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-8.1 (tag) and dspace-9.0 (tag) git diff dspace-8.1 dspace-9.0 -- src/themes/dspace/

         
         

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

      
      

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

...