High-complexity migration: preparing invision community 5 at large scale

Upgrading a large Invision Community from v4 to v5 is not linear work. In this DirectAdmin scenario, the documented path required practical contingencies to deliver a safe and testable rollout.

1) The starting point: mandatory pre-migration backup#

In large-scale production environments, performing structural modifications to the Invision Community database and code without a tested rollback plan is an unacceptable risk. The first step of any migration is to secure consistent backups of all system components.

1.1) Physical and logical backups#

Execute the complete dump routine of the MySQL/MariaDB database and compress the web directory:

# Logical backup of the database (all databases or specific database)
mysqldump -u root -p --single-transaction --routines --triggers --all-databases > /root/all-databases-$(date +%Y%m%d).sql

# Backup of the code directory (excluding heavy uploads to save space and time)
tar czf /root/invision-code-backup-$(date +%Y%m%d).tar.gz \
  --exclude='uploads' \
  /home/user/public_html/

# Quick backup of Invision configuration files
cp -r /home/user/public_html/conf/ /root/conf-backup-$(date +%Y%m%d)/

1.2) Hypervisor (VM) snapshots#

If your infrastructure runs on virtualization, generate a complete state snapshot in the hypervisor before proceeding:

# Proxmox VE CLI: Create virtual machine snapshot (Replace VMID)
qm snapshot <VMID> pre-upgrade-ic5 --description "Before Invision Community v5 migration"

# VMware ESXi CLI: Create snapshot via vim-cmd (Replace VMID)
vim-cmd vmsvc/snapshot.create <VMID> pre-upgrade-ic5 "Before v5 upgrade" 1 0

2) The storage challenge: 350 GB without duplication#

In robust scenarios, data is typically distributed as follows:

• Application core: < 1 GB
• Media (uploads/photos/attachments): ~310 GB
• Database: tens of GB

Duplicating the entire media folder for a staging environment requires massive secondary storage provisioning, in addition to introducing unacceptable synchronization latency.

2.1) Symlinks strategy in staging#

To mitigate this, we structure the staging environment by cloning only the code and creating symbolic links (symlinks) pointing to the production media data. Since staging will operate in read-only mode on uploads during code upgrade testing, this technique prevents unnecessary duplication:

# Synchronize only the code and directory structure
rsync -avz --progress \
  --exclude='uploads' \
  /home/user/public_html/ /home/user/staging_html/

# Create the symlink to production uploads
ln -s /home/user/public_html/uploads /home/user/staging_html/uploads

Outcome: full staging usability with minimal extra storage.

3) Isolation via hosts and system requirements verification#

To test Invision Community 5 reliably, it is necessary to isolate the environment so that it believes it is running under the official domain, without however exposing staging to public DNS.

3.1) Forced resolution via hosts file#

Although the official recommendation is to use the -TESTINSTALL suffix, this may fail in environments with strict licensing checks. The secure workaround was to replicate the environment on a secondary server and adjust the local hosts file of the test machines:

# In /etc/hosts (Linux/macOS) or C:\Windows\System32\drivers\etc\hosts (Windows):
192.168.100.50   comunidade.seusite.com

3.2) PHP version and extension auditing#

Invision Community 5 requires stable and updated PHP versions. Before running the migration, ensure that the PHP CLI and web interpreter meet the minimum requirements:

# Verify active PHP version
php --version

# Validate that mandatory extensions are compiled and active
php -m | grep -E -i "curl|gd|mbstring|mysql|xml|zip"

Adjust the directives in the php.ini or .user.ini file to support heavy processing volumes without suffering timeouts:

# Recommended settings for the upgrade
memory_limit = 512M
upload_max_filesize = 128M
post_max_size = 128M
max_execution_time = 300

4) Database import and integrity verification via CLI#

Large-scale community databases cannot be imported via web managers (like phpMyAdmin) due to timeout limits and HTTP buffer constraints in Nginx/Apache.

4.1) Import with throughput monitoring#

The import procedure must occur entirely through the terminal, using pv (Pipe Viewer) to monitor transfer rate and progress:

# Import with real-time progress monitoring
pv backup_producao.sql | mysql -u user_staging -p banco_staging

4.2) Integrity auditing and record validation#

Immediately after the import finishes, it is imperative to validate the structural integrity of the tables before submitting them to the Invision Community 5 upgrade script:

# Check all tables for corruption
mysqlcheck -u user_staging -p banco_staging --check

# Optimize and repair database tables if necessary
mysqlcheck -u user_staging -p banco_staging --auto-repair

# Validate record consistency in critical tables comparing Staging vs Production
mysql -u user_staging -p banco_staging -e "SELECT COUNT(*) FROM core_members"
mysql -u user_staging -p banco_staging -e "SELECT COUNT(*) FROM core_posts"

Compare the results obtained with production data to ensure no records were truncated during load.

5) Hands-on upgrade and post-upgrade verification#

Although the official documentation guides running the upgrade via CLI (php cli.php), migration in large-scale environments may fail due to heavy transactions on historical tables.

5.1) Assisted upgrade with active monitoring#

The contingency applied was to run the installer via web browser, but monitoring the queries in real time directly on the database to intervene if necessary:

# Monitor database processes in real time searching for locked queries
mysql -u user_staging -p -e "SHOW PROCESSLIST"

If any heavy query for index creation (e.g. ALTER TABLE core_posts ADD INDEX ...) freezes in a Waiting for table metadata lock state, manual intervention to kill concurrent processes or run the query in isolation is mandatory.

5.2) Version verification and post-upgrade status#

After the process is complete, validate the status of the application in the files and in the database:

# Verify version registered in the Invision version file
cat /home/user/public_html/conf/version.php

# Verify if the database version reflects the upgrade
mysql -u user_staging -p banco_staging -e "SELECT * FROM core_config_data WHERE path LIKE '%version%'"

# Test HTTP connection and return code of the administrative panel
curl -I https://staging.seusite.com/admin/

5.3) Plugin and theme compatibility auditing#

Incompatible plugins and themes are the main causes of post-upgrade white screens. Disable or validate all of them:

# List physical plugins installed
ls -la /home/user/public_html/plugins/

# List active applications directly in the database
mysql -u user_staging -p banco_staging -e "SELECT app_directory, app_version FROM core_applications WHERE app_enabled=1"

# Verify permissions and presence of the default theme
ls -la /home/user/public_html/themes/default/

6) Permissions, security audits, and error logs#

A classic DirectAdmin staging issue is the 500 Access Denied or HTTP 500 Internal Server Error due to incorrectly mapped ownership.

6.1) Correcting and auditing permissions#

In Invision Community 5, the conf_global.php file and dynamic directories must have restricted permissions, but readable by the PHP-FPM pool (e.g., site1:site1):

# Adjust ownership recursively to match the site user
chown -R site1:site1 /home/user/public_html/

# Ensure write permissions on cache and uploads
find /home/user/public_html/ -type d -name "cache" -exec chmod 755 {} \;
find /home/user/public_html/ -type d -name "uploads" -exec chmod 755 {} \;

# Protect conf_global.php against accidental writing
chmod 644 /home/user/public_html/conf/conf_global.php

6.2) Error logs and security inspection#

Actively monitor logs for silent failures or attempts to access configuration files:

# Tailing application PHP errors
tail -100 /home/user/public_html/error_log

# Web server logs (Nginx or Apache)
tail -100 /var/log/nginx/error.log
tail -100 /usr/local/apache/logs/error_log

# Search for 500 or fatal errors in Nginx logs
grep -E -i "500|error|fatal" /var/log/nginx/error.log | tail -20

6.3) Verification of file exposure#

Ensure sensitive configuration files are not accessible publicly:

# Test external access to global configuration file
curl -I https://staging.seusite.com/conf/conf_global.php
# Must return 403 Forbidden or 200 with content hidden by PHP interpreter

7) Performance verification and resource monitoring#

Before declaring the upgrade complete, ensure that server resource utilization and page loading speed are within acceptable limits.

7.1) Response timing and connections#

Monitor dynamic page load time and system daemon behavior:

# Measure staging HTTP response time
time curl -o /dev/null -s https://staging.seusite.com/

# Monitor CPU and memory usage of active PHP-FPM processes
ps aux | grep php-fpm

# Verify if slow query logs are configured in MySQL
mysql -u user_staging -p -e "SHOW VARIABLES LIKE 'slow_query_log'"

Checklist: migrating invision v4 → v5#

1. Pre-migration#

• [ ] Create complete backups: database + code + configurations.
• [ ] Generate VM state snapshot on the hypervisor.
• [ ] Validate PHP version and active extensions.
• [ ] Identify and list outdated plugins and applications.
• [ ] Document visual and logic custom modifications.

2. Staging and isolation#

• [ ] Provision a staging server isolated from production.
• [ ] Configure local host mapping in the hosts file.
• [ ] Perform code synchronization using rsync and create symlinks for media.
• [ ] Import database via CLI using the pv utility.
• [ ] Audit logical integrity and corrupted tables using mysqlcheck.

3. Upgrade execution#

• [ ] Start upgrade script (CLI or browser monitored).
• [ ] Actively monitor MySQL processlist to avoid deadlocks.
• [ ] Monitor PHP and web server error logs in real time.
• [ ] Correct file ownership and permissions for the PHP-FPM runtime user.

4. Post-upgrade validation#

• [ ] Test access to Admin Control Panel (ACP).
• [ ] Verify application compatibility and disable orphan plugins.
• [ ] Verify theme compatibility and default theme directory presence.
• [ ] Check media file uploads and display (uploads).
• [ ] Test dynamic routes, friendly URLs, and post publishing workflows.

Risk matrix and troubleshooting#

Lições de SRE para o seu playbook#

• Staging Isolation: Never use the same physical or database server for high-complexity tests without isolated networks.
• Upload Storage Footprint: For multi-gigabyte communities, symlinks save storage and enable replication test cycles in under 10 minutes.
• Dependency Management: Upgrading production forums at large scale requires disabling all third-party hooks and plugins before running the installer.

Upgrading a large Invision Community from v4 to v5 is not linear. When automation fails, success comes from isolation, active monitoring, and controlled execution inside the database and shell, step by step.

See also

Infrastructure Migrating from cPanel to DirectAdmin: how to generate backups via CLI

Infrastructure The master guide to legacy migration: from domino effects to architecture mismatch

Infrastructure How to test a website on a new IP without DNS changes using `curl --resolve` with full validation

This post is licensed under CC BY-NC.