SubjectPlus 4.6 on Ubuntu 22.04 : Complete Implementation Guide

SubjectPlus stands as a powerful, open-source content management solution specifically designed for libraries and educational institutions. This versatile platform enables organizations to create comprehensive subject guides, manage database collections, maintain staff directories, and build interactive FAQ systems. Originally developed by Ithaca College Library and now maintained by the University of Miami Libraries, SubjectPlus offers a robust alternative to proprietary library management tools.

Understanding SubjectPlus

Before diving into the installation process, it’s essential to understand what makes SubjectPlus valuable for modern libraries. This application operates as a comprehensive LAMP-based solution that consolidates multiple library website functions into a single, manageable platform. Its key capabilities include creating unlimited research guides through an intuitive drag-and-drop interface, maintaining organized staff listings sorted by department or specialization, and providing a centralized database management system.

The software’s multilingual support includes French and Spanish translations, making it suitable for diverse institutional environments. Additionally, its API functionality allows integration with other library systems and applications, extending its utility beyond basic content management.

System Prerequisites and Environment Setup

Successful SubjectPlus deployment requires a properly configured LAMP environment. The system demands PHP versions 5.3 through 5.6, MySQL versions 4 through 5.6, and a reliable web server, typically Apache. For optimal functionality, several PHP extensions must be enabled, including cURL for external communications, MySQL for database connectivity, mbstring for multi-byte string handling, SimpleXML for RSS feed processing, JSON for data serialization, gettext for internationalization support, and GD for image processing capabilities.

Ubuntu 22.04 LTS provides an excellent foundation for this installation, offering long-term stability and security updates that align well with library infrastructure requirements.

Initial System Preparation

Begin by ensuring your Ubuntu system is current with the latest security patches and package updates:

sudo apt update && sudo apt upgrade -y

This command sequence refreshes the package repository information and upgrades all installed packages to their latest versions.

Apache Web Server Installation and Configuration

Install the Apache web server, which will serve as the foundation for your SubjectPlus installation :

sudo apt install apache2 -y

After installation, Apache should start automatically. You can verify its status and enable it for automatic startup on system boot:

sudo systemctl status apache2
sudo systemctl enable apache2

Database System Setup

SubjectPlus requires a MySQL-compatible database system. MariaDB serves as an excellent alternative, offering enhanced performance and compatibility :

sudo apt install mariadb-server -y

Secure your database installation by running the security configuration script:

sudo mysql_secure_installation

Follow the prompts to set a root password, remove anonymous users, disable remote root login, and remove test databases. These steps significantly enhance your system’s security posture.

PHP Environment Configuration

Ubuntu 22.04’s default PHP version may not align with SubjectPlus requirements. Install PHP 7.4 and necessary extensions using the Ondřej Surý repository :

sudo apt install software-properties-common ca-certificates lsb-release apt-transport-https -y
sudo add-apt-repository ppa:ondrej/php -y
sudo add-apt-repository ppa:ondrej/apache2 -y
sudo apt update

Install PHP 7.4 with all required extensions:

sudo apt install php7.4 php7.4-cli php7.4-fpm php7.4-mysql php7.4-json php7.4-curl php7.4-mbstring php7.4-xml php7.4-zip php7.4-gd php7.4-intl php7.4-gettext libapache2-mod-php7.4 -y

Configure Apache to use PHP 7.4:

sudo a2enmod php7.4
sudo systemctl restart apache2

Database Creation and User Management

Create a dedicated database and user account for SubjectPlus. Access the MariaDB console as the root user:

sudo mysql -u root -p

Execute the following SQL commands to establish the database infrastructure:

CREATE DATABASE subjectsplus CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;
CREATE USER 'spuser'@'localhost' IDENTIFIED BY 'secure_password_here';
GRANT ALL PRIVILEGES ON subjectsplus.* TO 'spuser'@'localhost';
FLUSH PRIVILEGES;
EXIT;

Replace ‘secure_password_here’ with a strong, unique password for enhanced security.

SubjectPlus Application Deployment

Navigate to the web server’s document root and download the latest SubjectPlus release :

cd /var/www/html
sudo wget https://github.com/subjectsplus/SubjectsPlus/archive/refs/tags/v4.6.tar.gz
sudo tar -xzf v4.6.tar.gz
sudo mv SubjectsPlus-4.6 subjectplus

File Permissions and Security

Proper file permissions ensure both security and functionality. Set appropriate ownership and permissions:

sudo chown -R www-data:www-data /var/www/html/subjectplus
sudo find /var/www/html/subjectplus -type d -exec chmod 755 {} \;
sudo find /var/www/html/subjectplus -type f -exec chmod 644 {} \;

Specific directories require write permissions for proper operation:

sudo chmod 755 /var/www/html/subjectplus/assets/users/
sudo chmod 755 /var/www/html/subjectplus/assets/cache/
sudo chmod 755 /var/www/html/subjectplus/assets/images/video_thumbs/
sudo chmod 664 /var/www/html/subjectplus/subjects/.htaccess
sudo chmod 664 /var/www/html/subjectplus/api/.htaccess

Apache Virtual Host Configuration

Create a dedicated virtual host configuration for SubjectPlus:

sudo nano /etc/apache2/sites-available/subjectplus.conf

Add the following configuration, adjusting the ServerName to match your domain:

<VirtualHost *:80>
    ServerName your-domain.com
    DocumentRoot /var/www/html/subjectplus

    <Directory /var/www/html/subjectplus>
        AllowOverride All
        Require all granted
        DirectoryIndex index.php index.html
    </Directory>

    ErrorLog ${APACHE_LOG_DIR}/subjectplus_error.log
    CustomLog ${APACHE_LOG_DIR}/subjectplus_access.log combined
</VirtualHost>

Enable the new site configuration and necessary Apache modules:

sudo a2ensite subjectplus.conf
sudo a2enmod rewrite
sudo a2dissite 000-default.conf
sudo systemctl reload apache2

Web-Based Installation Process

With the server environment properly configured, complete the installation through SubjectPlus’s web-based installer. Open your web browser and navigate to http://your-domain.com/control or http://your-server-ip/subjectplus/control.

The installer will guide you through the following steps:

1. Configuration File Creation: The system will detect the absence of a configuration file and prompt you to create one.
2. Database Connection Setup: Provide the database credentials you created earlier:

• Database Host: localhost
• Database Name: subjectsplus
• Username: spuser
• Password: your_chosen_password

1. Institution Information: Enter your organization’s details, including institution name, administrator email, and other relevant information.
2. Administrator Account: Create the primary administrative account that will manage the SubjectPlus installation.

Post-Installation Configuration

After successful installation, several configuration adjustments may enhance your SubjectPlus deployment:

Base URL Configuration

Ensure the base URL is correctly set in the configuration file:

sudo nano /var/www/html/subjectplus/control/includes/config.php

Locate and verify the $BaseURL variable matches your domain configuration.

URL Rewriting Configuration

SubjectPlus relies on URL rewriting for clean URLs and proper functionality. Verify that the .htaccess files in both the subjects and api directories contain appropriate rewrite rules.

Security Considerations and Maintenance

Regular maintenance ensures optimal performance and security. Implement these best practices:

1. Regular Updates: Monitor the SubjectPlus GitHub repository for security updates and new releases.
2. Database Backups: Implement automated backup procedures for your SubjectPlus database.
3. Log Monitoring: Regularly review Apache error logs for any issues or security concerns.
4. SSL Implementation: Consider implementing SSL certificates for encrypted communications, especially if handling sensitive library data.

Troubleshooting Common Issues

Several common issues may arise during installation:

• Permission Errors: Ensure www-data has appropriate permissions on all SubjectPlus directories.
• PHP Module Missing: Verify all required PHP extensions are installed and enabled.
• Database Connection Issues: Confirm database credentials and network connectivity.
• Rewrite Rule Problems: Ensure Apache’s mod_rewrite is enabled and .htaccess files are properly configured.

Conclusion

This comprehensive guide provides the foundation for successfully deploying SubjectPlus 4.6 on Ubuntu 22.04 LTS. The resulting installation offers libraries and educational institutions a powerful platform for managing research guides, databases, and staff information. With proper configuration and maintenance, SubjectPlus can serve as a central hub for your organization’s digital library services, providing both staff and patrons with an intuitive interface for accessing and managing library resources.

The open-source nature of SubjectPlus ensures ongoing community support and the flexibility to customize the platform according to your institution’s specific requirements. Regular engagement with the SubjectPlus community through their official channels can provide additional insights and support for optimizing your installation.