ioChem-BD

Appearance

Migration Guide ​

This guide describes how to migrate an existing ioChem-BD installation to a new clean machine. Follow these steps to ensure a smooth migration with minimal downtime.

WARNING

Schedule the migration during a maintenance window or low-usage period to minimize disruption to users.

Overview ​

The migration process involves:

  1. Preparing the new machine
  2. Backing up data from the old machine
  3. Restoring data on the new machine
  4. Updating configuration for the new environment
  5. Verifying the installation

Phase 1: Prepare the New Machine ​

System Setup ​

Install all required software on the new machine:

Operating System Requirements:

  • Linux OS 2.6.24 or greater (64 bit)
  • Tested on Ubuntu, CentOS, Fedora, and Debian distributions

Software Packages:

bash
# Install Java JDK 17
root# dnf install java-17-openjdk.x86_64 # For CentOS/Fedora/Rocky
# or
root# apt install openjdk-17-jdk         # For Debian/Ubuntu

# Install PostgreSQL (version 11 or newer)
root# yum install postgresql-server postgresql  # For CentOS/Fedora/Rocky
# or
root# apt-get install postgresql               # For Debian/Ubuntu

# Install libcap for privileged port access
root# yum install libcap                        # For CentOS/Fedora/Rocky
# or
root# apt-get install libcap2-bin               # For Debian/Ubuntu

Hardware Verification:

  • Minimum 4 CPU cores (2GHz or better)
  • Minimum 16 GB RAM
  • Free disk space: At least 500 GB + current iochembd folder size

Create System User ​

Create the iochembd user account that will own the application files:

bash
root# useradd -m iochembd

INFO

You can use a different username, but ensure it matches throughout the migration process.

DANGER

When you migrate the program to the new machine it must be placed on the same parent folder structure (same folder names), otherwise the already defined configuration files will fail to find the content.

Phase 2: Backup Data from Old Machine ​

Database Backup ​

Export both PostgreSQL databases from the old machine:

bash
# Run as the iochembd database user
# The password is stored inside configuration files such as 
# create/resource.properties then on create.database.pwd field

iochembd$ pg_dump -U iochembd iochemCreate > iochemCreate_backup.sql
iochembd$ pg_dump -U iochembd iochemBrowse > iochemBrowse_backup.sql

# Compress the backups to save space and transfer time
iochembd$ gzip iochemCreate_backup.sql
iochembd$ gzip iochemBrowse_backup.sql

File System Backup ​

Identify and backup the following directory from the old installation:

Application Files:

bash
# Backup the entire ioChem-BD installation folder, 
# Usually it is called iochembd, but we will refer to it as BASE_PATH
iochembd$ cd /home/iochembd
iochembd$ tar -czf iochembd_application.tar.gz iochembd/

WARNING

The assetstore directories contained inside BASE_PATH contain all uploaded calculation files in both modules.

Assetstore directories can be very large. Ensure you have sufficient disk space and time for the backup.

An alternative is to copy the entire BASE_PATH folder to the new machine using scp command or mounting the remote destination folder with sshfs and then use rsync to migrate it.

Transfer Backups:

Copy all backup files to the new machine using your preferred method:

bash
# Example using scp
iochembd$ scp *.tar.gz *.sql.gz iochembd@new-machine:/home/iochembd/backup/

Phase 3: Restore on New Machine ​

Setup PostgreSQL ​

Initialize and configure PostgreSQL on the new machine:

bash
# Initialize PostgreSQL databases (if not already done), only necessary on CentOS/Fedora/Rocky/RHEL
root# postgresql-setup initdb

# Configure PostgreSQL to start on boot
root# systemctl enable postgresql

# Edit pg_hba.conf to allow password authentication, folder names can vary depending on your version and OS
# If file doesn't exist, just create it.
root# vi /var/lib/postgresql/16/main/pg_hba.conf

Add these lines to pg_hba.conf:

bash
# TYPE DATABASE USER ADDRESS METHOD
# IPv4 local connections:
host all iochembd 127.0.0.1/32 md5

Start PostgreSQL service:

bash
root# systemctl restart postgresql

Create PostgreSQL User and Databases ​

Create the database user with the same database password as the old installation:

bash
# Switch to postgres user
postgres$ createuser -s -d -l -P iochembd

   Enter password for new role: XXXXXXX
   Enter it again:  XXXXXXX

Create the two databases with UTF-8 encoding:

bash
postgres$ createdb --encoding=UTF8 --template=template0 --owner=iochembd "iochemCreate"
postgres$ createdb --encoding=UTF8 --template=template0 --owner=iochembd "iochemBrowse"

Restore Database Content ​

Import the database backups:

bash
# Decompress the backup files
iochembd$ gunzip iochemCreate_backup.sql.gz
iochembd$ gunzip iochemBrowse_backup.sql.gz

# Restore the databases
iochembd$ psql -U iochembd -h 127.0.0.1 iochemCreate < iochemCreate_backup.sql
iochembd$ psql -U iochembd -h 127.0.0.1 iochemBrowse < iochemBrowse_backup.sql

INFO

Database restoration can take several minutes to hours depending on the size of your data.

Install ioChem-BD Software ​

Once the databases are recovered, we will focus on the platform software + data.

Extract the application backup to the desired location:

bash
iochembd$ cd /home/iochembd/
iochembd$ tar -xzf iochembd_application.tar.gz

WARNING

Remember again that this action requires the new machine to use the same directory paths as the old machine. If paths differ, you must update configuration files manually.

Phase 4: Configuration Updates ​

Update Network Configuration ​

If the hostname or IP address has changed, update the following:

1. Edit /etc/hosts:

bash
root# vi /etc/hosts

Add or update the entry:

bash
127.0.0.1     your-new-hostname.domain.com

2. SSL Certificate:

If the hostname changed:

  • The certificate generated during fresh installation will be correct
  • Or manually replace the certificate (see Replace HTTPS Certificate)

If using direct restoration with changed hostname:

Set Port Privileges ​

When using privileged ports (below 1024, typically port 443 for HTTPS) you must run the following script as root user to allow java command to run on privileged ports:

bash
root# cd BASE_PATH
root# ./postinstall.sh

You must run the previous command each time you update the Java JDK package because the permissions are removed with the update process.

In order to avoid this situation, you can freeze your java package from updating with the following command:

bash
root#  yum versionlock add java-17-openjdk.x86_64   # For CentOS/Fedora/Rocky

root#  apt-mark hold openjdk-17-jdk                 # For Debian/Ubuntu

Phase 5: Start and Verify ​

First verify all migrated files in BASE_PATH belong to iochembd user, otherwise use this command:

bash
root# chown -R iochembd:iochembd BASE_PATH

Start Services ​

Start the ioChem-BD web service as iochembd user:

bash
iochembd$ BASE_PATH/apache-tomcat/bin/startup.sh

Monitor Startup ​

Watch the log file for any startup errors:

bash
iochembd$ tail -f BASE_PATH/apache-tomcat/logs/catalina.out

Wait until you see messages indicating successful startup (typically "Server startup in X ms").

Verify Installation ​

If the old and new servers are running in parallel, you can edit your local machine /etc/hosts to point the new machine IP and test following functionalities, remember to undo this operation once testing is over.

Perform these verification steps:

1. Access Web Interface:

Open your web browser and navigate to:

  • Main page: https://your-hostname/
  • Create module: https://your-hostname/create
  • Browse module: https://your-hostname/browse

2. Test Administrator Login:

  • Go to Browse module
  • Login with administrator credentials
  • Verify you can see all users on "Administer-> Access Control-> E-people"

3. Test User Access:

  • Go to Create module
  • Login as a regular user
  • Verify access to their projects
  • Check file viewing and download functionality

4. Verify Published Data:

  • Browse the public repository
  • Search for published items
  • Verify molecular visualizations load correctly

5. Test File Operations:

  • Upload a small test calculation file
  • Verify conversion completes successfully
  • Check file is properly stored and viewable

6. Test Email Notifications:

  • Trigger an email notification (e.g., password reset request)
  • Verify email is received correctly

7. Check Search Functionality:

  • Perform searches in Create module
  • Verify search results are accurate and complete

Update DNS (if applicable) ​

If you're replacing the production server:

  1. Update DNS records to point to the new server's IP address
  2. Wait for DNS propagation (can take up to 48 hours)
  3. Monitor old server logs to ensure traffic has shifted to new server

TIP

Consider using a lower TTL value for your DNS records before migration to speed up propagation.

Migration Checklist ​

Use this checklist to track your migration progress:

  • [ ] New machine meets all system requirements
  • [ ] Java JDK 17 installed
  • [ ] PostgreSQL installed and configured
  • [ ] System user (iochembd) created
  • [ ] Databases backed up from old machine
  • [ ] Application folder backed up from old machine
  • [ ] All backups transferred to new machine
  • [ ] PostgreSQL databases restored
  • [ ] Database credentials match old installation
  • [ ] ioChem-BD software installed
  • [ ] SSL certificate configured correctly
  • [ ] /etc/hosts file updated
  • [ ] Port privileges set (postinstall.sh executed)
  • [ ] Web service started successfully
  • [ ] No errors in catalina.out log
  • [ ] Administrator can login to Browse module
  • [ ] Regular users can access their data
  • [ ] All projects and calculations visible
  • [ ] File upload and conversion working
  • [ ] Search functionality operational
  • [ ] Browse module shows published content
  • [ ] Email notifications sending correctly
  • [ ] DNS updated (if replacing production server)
  • [ ] Old server kept running until verification complete

Rollback Plan ​

Keep the old server operational and accessible until you've completed all verification steps. If you encounter critical issues:

  1. Keep users on the old server by not updating DNS or reverting DNS changes
  2. Investigate and resolve issues on the new server
  3. Re-attempt migration when ready

DANGER

Do not decommission the old server until the new installation has been verified and running successfully for at least several days.

Post-Migration ​

After successful migration:

  1. Monitor the new server closely for the first few days
  2. Check log files regularly for any errors or warnings
  3. Verify backups are running correctly on the new system
  4. Update any documentation with new server details
  5. Notify users of any changes (new hostname, IP address, etc.)
  6. Schedule the decommissioning of the old server

Troubleshooting ​

Database Connection Errors ​

If you see database connection errors in the logs:

  • Verify PostgreSQL is running: service postgresql status
  • Check database credentials in configuration files
  • Verify pg_hba.conf entries are correct
  • Test database connection manually: psql -U iochembd -h 127.0.0.1 iochemCreate

Certificate Issues ​

If you see SSL certificate errors:

  • Verify certificate was generated for correct hostname
  • Check certificate file permissions (should be readable by iochembd user)
  • See Replace HTTPS Certificate for detailed troubleshooting

File Permission Errors ​

If you see permission denied errors:

  • Verify all files in BASE_PATH belong to iochembd user: chown -R iochembd:iochembd BASE_PATH
  • Check assetstore directory permissions
  • Verify postinstall.sh was run as root for privileged ports

Missing Data ​

If calculations or files are missing:

  • Verify old backup did not fill disk or data migration did not fill the new machine disk
  • Verify database restoration completed successfully
  • Check assetstore directories were restored to correct locations
  • Verify assetstore paths in configuration match actual directory locations

Getting Help ​

If you encounter issues during migration:

TIP

When contacting support, include relevant log file excerpts and details about your migration steps.