Page History

...

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 a prior version of 7.x, upgrading just requires installing the latest version of the User Interface code
   1. Upgrade Node.js if necessary
      1. If upgrading to 7.5, we highly recommend using either Node.js 16 or 18 as Node.js 14 will enter EOL (end of life) as of 30 April 2023.
   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-7.2) 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 Installation documentation. As of 7.2, 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 the older ./src/environment/environment.*.ts configuration files have all been replaced by corresponding ./config/config.*.yml configuration files (e.g. environment.prod.ts → config.prod.yml). 

      1. Either, manually move your "environment.prod.ts" configurations into 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. In 7.1, we added the ability to "extend" themes in the "themes" section. See the User Interface Configuration documentation for details.
      2. In 7.2, themes now support optional "headTags" which can be used to customize favicons per theme (see User Interface Customization).  Additionally, "browseBy > types" configurations were removed, as they are now dynamically retrieved from the REST API (see User Interface Configuration).
      3. In 7.3, you can optionally enable Item Access labels in the UI to display the status of an Item as a badge (e.g. "open access", "restricted", "metadata only" or "embargoed").  See User Interface Configuration
      4. In 7.4, many new user interface configurations were added. See Release Notes and User Interface Configuration for details.
      5. In 7.5, a new "Server Side Rendering" page caching option was added which can drastically speed up the initial response of your site. Other new settings also were added. See Release Notes and User Interface Configuration for details.
   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. In 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
         title src/themes/eager-themes.module.ts
         import { EagerThemeModule as MyThemeEagerThemeModule } from './my-theme/eager-theme.module'; ... @NgModule({ imports: [ MyThemeEagerThemeModule, ], })

         
         

      2. 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.14 (tag) and dspace-7.25 (tag) git diff dspace-7.14 dspace-7.25 -- src/themes/dspace/

            
            

      3. 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.
      4. 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.
   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.

...