Installing the DSpace Angular Frontend
This guide walks through the complete process of installing and configuring the DSpace Angular frontend for your DSpace repository.
Step 1: Install Node.js Using NVM
Official Documentation Reference: For complete and up-to-date instructions, please refer to the Official DSpace Installation Guide.
DSpace requires Node.js version v18.19+, v20.x, or v22.x for optimal performance and compatibility. For best compatibility and stability, Node.js v22.18.0 (LTS) is recommended.
For more details, visit the official Node.js download page. When selecting from the dropdown on the Node.js website, choose:
- Version: v22.18.0 (LTS)
- Operating System: Linux (if you're installing on Ubuntu or another Linux distro)
- Installation method: nvm (Node Version Manager)
- Package manager: npm (included with Node.js)
sudo su
Purpose: Switch to root user
Explanation: This command switches the current user to the root (superuser) account, giving you full administrative privileges. Use this when you need to perform multiple administrative commands without prefixing each one with "sudo".
Explanation: This command switches the current user to the root (superuser) account, giving you full administrative privileges. Use this when you need to perform multiple administrative commands without prefixing each one with "sudo".
sudo apt update
Purpose: Updates the package lists for upgrades and new packages
Explanation: This command refreshes your local package index with the latest changes made in repositories. It's good practice to run this before installing new software.
Explanation: This command refreshes your local package index with the latest changes made in repositories. It's good practice to run this before installing new software.
sudo curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.3/install.sh | bash
Purpose: Downloads and installs NVM (Node Version Manager)
Explanation: This command uses curl to download the NVM installation script from GitHub and immediately executes it with bash. NVM allows you to easily install and manage multiple Node.js versions.
Explanation: This command uses curl to download the NVM installation script from GitHub and immediately executes it with bash. NVM allows you to easily install and manage multiple Node.js versions.
. "$HOME/.nvm/nvm.sh"
Purpose: Loads NVM into your current shell session
Explanation: This command sources the nvm.sh script, making the nvm command available in your current terminal session. After installation, you may need to restart your terminal or run this command to start using NVM.
Explanation: This command sources the nvm.sh script, making the nvm command available in your current terminal session. After installation, you may need to restart your terminal or run this command to start using NVM.
nvm install 22
Purpose: Installs Node.js version 22.x
Explanation: This command tells NVM to download and install the latest version of Node.js in the v22 series. DSpace requires this specific version for compatibility with its Angular frontend.
Explanation: This command tells NVM to download and install the latest version of Node.js in the v22 series. DSpace requires this specific version for compatibility with its Angular frontend.
# Should output: v22.18.0 (or similar)
node -v
Purpose: Checks the installed Node.js version
Explanation: This command displays the currently active Node.js version. After installation, you should see version 22.18.0 or similar, confirming that Node.js was installed correctly.
Explanation: This command displays the currently active Node.js version. After installation, you should see version 22.18.0 or similar, confirming that Node.js was installed correctly.
# Should output the npm version bundled with Node.js (e.g., 10.8.2)
npm -v
Purpose: Checks the installed npm version
Explanation: This command displays the version of npm (Node Package Manager) that came bundled with your Node.js installation. npm is used to manage JavaScript packages and dependencies for your DSpace frontend.
Explanation: This command displays the version of npm (Node Package Manager) that came bundled with your Node.js installation. npm is used to manage JavaScript packages and dependencies for your DSpace frontend.
Step 2: Install PM2 Globally
PM2 is a popular Node.js process manager that helps keep your frontend running smoothly in production.
npm install --global pm2
Purpose: Installs PM2 globally on your system
Explanation: This command installs the PM2 process manager globally, making it available system-wide. PM2 helps manage Node.js applications, ensuring they stay running and can restart automatically if they crash.
Explanation: This command installs the PM2 process manager globally, making it available system-wide. PM2 helps manage Node.js applications, ensuring they stay running and can restart automatically if they crash.
Verify the installation:
pm2 -v
Purpose: Checks the installed PM2 version
Explanation: This command displays the version of PM2 that was installed, confirming the installation was successful.
Explanation: This command displays the version of PM2 that was installed, confirming the installation was successful.
Step 3: Download and Build the DSpace Frontend
Navigate to your preferred directory and download the DSpace frontend source code:
cd /opt/
Purpose: Navigate to the /opt/ directory
Explanation: This command changes the current working directory to /opt/, which is a standard directory for installing optional software packages on Linux systems.
Explanation: This command changes the current working directory to /opt/, which is a standard directory for installing optional software packages on Linux systems.
sudo wget https://github.com/DSpace/dspace-angular/archive/refs/tags/dspace-9.1.tar.gz
Purpose: Download the DSpace Angular frontend source code
Explanation: This command uses wget to download the compressed source code archive (tar.gz) for DSpace Angular version 9.1 from GitHub. The sudo command is used to ensure proper permissions.
Explanation: This command uses wget to download the compressed source code archive (tar.gz) for DSpace Angular version 9.1 from GitHub. The sudo command is used to ensure proper permissions.
sudo tar xzf dspace-9.1.tar.gz
Purpose: Extract the downloaded archive
Explanation: This command extracts the contents of the compressed tar.gz file. The options used are: x (extract), z (uncompress gzip), and f (file).
Explanation: This command extracts the contents of the compressed tar.gz file. The options used are: x (extract), z (uncompress gzip), and f (file).
sudo mv dspace-angular-dspace-9.1/ dspace-angular
Purpose: Rename the extracted directory
Explanation: This command moves (renames) the extracted directory from "dspace-angular-dspace-9.1" to the simpler name "dspace-angular" for easier reference in subsequent commands.
Explanation: This command moves (renames) the extracted directory from "dspace-angular-dspace-9.1" to the simpler name "dspace-angular" for easier reference in subsequent commands.
sudo rm dspace-9.1.tar.gz
Purpose: Remove the downloaded archive file
Explanation: This command deletes the compressed archive file after extraction to free up disk space, as the extracted files are now available in the directory.
Explanation: This command deletes the compressed archive file after extraction to free up disk space, as the extracted files are now available in the directory.
Change into the frontend directory, install dependencies, and build the production-ready code:
cd dspace-angular
Purpose: Navigate to the DSpace Angular directory
Explanation: This command changes the current working directory to the "dspace-angular" folder where the DSpace frontend source code was extracted in the previous step.
Explanation: This command changes the current working directory to the "dspace-angular" folder where the DSpace frontend source code was extracted in the previous step.
npm install
Purpose: Install project dependencies
Explanation: This command reads the package.json file and installs all the required Node.js dependencies and libraries needed to build and run the DSpace Angular frontend. This may take several minutes to complete.
Explanation: This command reads the package.json file and installs all the required Node.js dependencies and libraries needed to build and run the DSpace Angular frontend. This may take several minutes to complete.
npm run build:prod
Purpose: Build the production version of the frontend
Explanation: This command compiles and builds the DSpace Angular frontend optimized for production use. It creates minified JavaScript files, optimizes assets, and prepares the application for deployment in a production environment.
Explanation: This command compiles and builds the DSpace Angular frontend optimized for production use. It creates minified JavaScript files, optimizes assets, and prepares the application for deployment in a production environment.
Step 4: Configure the Frontend
Change into the frontend directory
cd /opt/dspace-angular
Purpose: Navigate to the DSpace Angular directory
Explanation: This command changes the current working directory to the "dspace-angular" folder where the DSpace frontend source code was extracted.
Explanation: This command changes the current working directory to the "dspace-angular" folder where the DSpace frontend source code was extracted.
Copy the example configuration file and modify it for your environment:
cd config
Purpose: Navigate to the config directory
Explanation: This command changes the current working directory to the "config" folder where the DSpace configuration files are located.
Explanation: This command changes the current working directory to the "config" folder where the DSpace configuration files are located.
cp config.example.yml config.prod.yml
Purpose: Create production configuration file
Explanation: This command copies the example configuration file (config.example.yml) to create a production configuration file (config.prod.yml) that will be used for your specific environment.
Explanation: This command copies the example configuration file (config.example.yml) to create a production configuration file (config.prod.yml) that will be used for your specific environment.
Open config.prod.yml and update the REST API server settings:
ui:
ssl: false
host: localhost
port: 4000
nameSpace: /
rest:
ssl: false
host: localhost
port: 8080
Purpose: Configures the connection to the DSpace backend REST API. update the rest: section part from true to false
Explanation: These settings configure how the frontend connects to the backend. "ssl: false" indicates no encryption, "host: localhost" means the backend is on the same server, and "port: 8080" specifies the port where the backend is running.
Explanation: These settings configure how the frontend connects to the backend. "ssl: false" indicates no encryption, "host: localhost" means the backend is on the same server, and "port: 8080" specifies the port where the backend is running.
Step 5: Deploy the Frontend
Create a deployment directory and set proper permissions:
sudo mkdir -p /opt/dspace-ui
Purpose: Create deployment directory
Explanation: This command creates the directory "/opt/dspace-ui" where the DSpace frontend will be deployed. The "-p" flag ensures that parent directories are created if they don't exist.
Explanation: This command creates the directory "/opt/dspace-ui" where the DSpace frontend will be deployed. The "-p" flag ensures that parent directories are created if they don't exist.
sudo chown $tomcat:$tomcat /opt/dspace-ui
Purpose: Set directory ownership
Explanation: This command changes the ownership of the deployment directory to the Tomcat user and group. Replace "$tomcat" with your actual Tomcat username (typically "tomcat" or "dspace").
Explanation: This command changes the ownership of the deployment directory to the Tomcat user and group. Replace "$tomcat" with your actual Tomcat username (typically "tomcat" or "dspace").
Change into the frontend directory
cd /opt/dspace-angular
Purpose: Navigate to the DSpace Angular directory
Explanation: This command changes the current working directory to the "dspace-angular" folder where the DSpace frontend source code was extracted.
Explanation: This command changes the current working directory to the "dspace-angular" folder where the DSpace frontend source code was extracted.
cp -r dist /opt/dspace-ui/
Purpose: Copy built files to deployment directory
Explanation: This command copies the entire "dist" directory (which contains the built frontend files) to the deployment directory. The "-r" flag ensures recursive copying of all files and subdirectories.
Explanation: This command copies the entire "dist" directory (which contains the built frontend files) to the deployment directory. The "-r" flag ensures recursive copying of all files and subdirectories.
Create a PM2 configuration file to manage the frontend process:
sudo nano /opt/dspace-ui/dspace-ui.json
Purpose: Creates a PM2 configuration file for the DSpace frontend
Explanation: This command opens the nano text editor to create a JSON configuration file for PM2. This file will tell PM2 how to run and manage the DSpace frontend process.
Explanation: This command opens the nano text editor to create a JSON configuration file for PM2. This file will tell PM2 how to run and manage the DSpace frontend process.
Add the following content:
{
"apps": [
{
"name": "dspace-ui",
"cwd": "/opt/dspace-ui",
"script": "dist/server/main.js",
"instances": "max",
"exec_mode": "cluster",
"env": {
"NODE_ENV": "production"
}
}
]
}
Purpose: PM2 configuration for running the DSpace frontend
Explanation: This JSON configuration tells PM2 to run the DSpace UI application from the specified directory, using the cluster mode to maximize performance across CPU cores, with production environment settings.
Explanation: This JSON configuration tells PM2 to run the DSpace UI application from the specified directory, using the cluster mode to maximize performance across CPU cores, with production environment settings.
Start the frontend using PM2:
cd /opt/dspace-ui
Purpose: Navigate to deployment directory
Explanation: This command changes the current working directory to "/opt/dspace-ui" where the DSpace frontend files are deployed and where the PM2 configuration file is located.
Explanation: This command changes the current working directory to "/opt/dspace-ui" where the DSpace frontend files are deployed and where the PM2 configuration file is located.
pm2 start dspace-ui.json
Purpose: Start DSpace UI with PM2
Explanation: This command starts the DSpace frontend application using PM2 and the configuration specified in the "dspace-ui.json" file. PM2 will manage the application process.
Explanation: This command starts the DSpace frontend application using PM2 and the configuration specified in the "dspace-ui.json" file. PM2 will manage the application process.
pm2 startup
Purpose: Configure PM2 to start on system boot
Explanation: This command generates and configures a startup script to automatically launch PM2 and its managed processes when the system boots up.
Explanation: This command generates and configures a startup script to automatically launch PM2 and its managed processes when the system boots up.
pm2 save
Purpose: Save current PM2 process list
Explanation: This command saves the current list of managed processes to PM2's persistent storage, ensuring that all running applications will be restored automatically after system reboot.
Explanation: This command saves the current list of managed processes to PM2's persistent storage, ensuring that all running applications will be restored automatically after system reboot.
Step 6: Set Up Apache Reverse Proxy
To allow users to access the frontend via standard HTTP ports, set up an Apache reverse proxy:
sudo apt install apache2
Purpose: Install Apache web server
Explanation: This command installs the Apache HTTP server, which will act as a reverse proxy to forward requests to the DSpace frontend and backend services.
Explanation: This command installs the Apache HTTP server, which will act as a reverse proxy to forward requests to the DSpace frontend and backend services.
sudo a2enmod proxy
Purpose: Enable Apache proxy module
Explanation: This command enables the main proxy module for Apache, which provides the core functionality for forwarding requests to other servers (reverse proxy).
Explanation: This command enables the main proxy module for Apache, which provides the core functionality for forwarding requests to other servers (reverse proxy).
sudo a2enmod proxy_http
Purpose: Enable HTTP proxy module
Explanation: This command enables the HTTP proxy module, which extends the proxy functionality to handle HTTP and HTTPS requests specifically.
Explanation: This command enables the HTTP proxy module, which extends the proxy functionality to handle HTTP and HTTPS requests specifically.
sudo a2enmod ssl
Purpose: Enable SSL module
Explanation: This command enables the SSL module, which provides support for HTTPS encrypted connections. This is necessary even if you're initially using HTTP, as it may be needed for future SSL configuration.
Explanation: This command enables the SSL module, which provides support for HTTPS encrypted connections. This is necessary even if you're initially using HTTP, as it may be needed for future SSL configuration.
Create a new Apache site configuration:
sudo nano /etc/apache2/sites-available/dspace.conf
Purpose: Creates an Apache configuration file for DSpace
Explanation: This command opens the nano text editor to create a new Apache virtual host configuration file specifically for DSpace.
Explanation: This command opens the nano text editor to create a new Apache virtual host configuration file specifically for DSpace.
Paste this configuration:
<VirtualHost *:80>
ServerName localhost
ProxyPreserveHost On
RequestHeader set X-Forwarded-Proto "http"
RequestHeader set X-Forwarded-Port "80"
ProxyPass / http://localhost:4000/
ProxyPassReverse / http://localhost:4000/
ProxyPass /server http://localhost:8080/server
ProxyPassReverse /server http://localhost:8080/server
ErrorLog ${APACHE_LOG_DIR}/dspace-error.log
CustomLog ${APACHE_LOG_DIR}/dspace-access.log combined
</VirtualHost>
Purpose: Apache reverse proxy configuration for DSpace
Explanation: This Apache configuration sets up a reverse proxy that forwards requests to the appropriate services: frontend requests (/) to port 4000 (where the Angular app runs) and backend API requests (/server) to port 8080 (where the DSpace REST API runs).
Explanation: This Apache configuration sets up a reverse proxy that forwards requests to the appropriate services: frontend requests (/) to port 4000 (where the Angular app runs) and backend API requests (/server) to port 8080 (where the DSpace REST API runs).
Enable the site and restart Apache:
sudo a2dissite 000-default.conf
Purpose: Disable default Apache site
Explanation: This command disables the default Apache website that shows the "It works!" page, making way for the DSpace site to be the primary website served by Apache.
Explanation: This command disables the default Apache website that shows the "It works!" page, making way for the DSpace site to be the primary website served by Apache.
sudo a2ensite dspace
Purpose: Enable DSpace site configuration
Explanation: This command enables the DSpace site configuration that you created earlier. It creates a symbolic link from sites-available to sites-enabled, telling Apache to serve the DSpace application.
Explanation: This command enables the DSpace site configuration that you created earlier. It creates a symbolic link from sites-available to sites-enabled, telling Apache to serve the DSpace application.
sudo systemctl restart apache2
Purpose: Restart Apache web server
Explanation: This command restarts the Apache service to apply all the configuration changes made, including enabling the DSpace site and disabling the default site.
Explanation: This command restarts the Apache service to apply all the configuration changes made, including enabling the DSpace site and disabling the default site.
Step 7: Verify the Frontend Installation
Check PM2 process status and logs:
pm2 status
Purpose: Check PM2 process status
Explanation: This command displays the status of all applications managed by PM2, showing whether the DSpace UI process is running, stopped, or experiencing issues.
Explanation: This command displays the status of all applications managed by PM2, showing whether the DSpace UI process is running, stopped, or experiencing issues.
pm2 logs dspace-ui
Purpose: View DSpace UI application logs
Explanation: This command displays the real-time logs for the DSpace UI application, which is useful for troubleshooting any errors or issues with the frontend.
Explanation: This command displays the real-time logs for the DSpace UI application, which is useful for troubleshooting any errors or issues with the frontend.
Test the REST API connection:
cd /opt/dspace-angular
Purpose: Navigate to DSpace Angular directory
Explanation: This command changes to the DSpace Angular source directory where the test scripts are located.
Explanation: This command changes to the DSpace Angular source directory where the test scripts are located.
npm run test:rest
Purpose: Test REST API connection
Explanation: This command runs a script that tests the connection between the DSpace frontend and backend REST API, verifying that they can communicate properly.
Explanation: This command runs a script that tests the connection between the DSpace frontend and backend REST API, verifying that they can communicate properly.
Note: Make sure your DSpace backend is running before testing the frontend. The frontend needs to connect to the REST API on port 8080.
Important: If you're installing on a production server, replace "localhost" with your actual domain name in the configuration files and Apache virtual host.
No comments:
Post a Comment