02.09 Migrating to a new Linux host (server or VM refresh)

Why this matters

Hardware ages out, a VM needs rebuilding on a fresh image, a workload moves to a new region. When that happens, the SimpleRisk data has to come along, and the good news is that it isn't tied to the machine it's on. It lives in one MySQL database plus two directories: the generated config.php and the uploads/ folder of evidence files. Everything else is application code you can lay down again from a tarball.

Because you're staying on Linux, you get a shortcut the cross-platform migrations don't have. You can copy the whole install directory across intact, which makes a like-for-like refresh a short job. That gives two clean approaches, and the right one depends on whether the new host matches the old.

The advice that saves the most grief: a host refresh doesn't have to be a version change. Keep the same SimpleRisk version on the new host so the restore is an exact match, confirm it works, and upgrade to the current release afterward as a separate step if you want to. We've watched migrations that bundled "new host" and "new version" into one move turn a five-minute diagnosis into an afternoon, because when something looked wrong there was no way to tell which change caused it.

Before you start

Gather this from the current host first.

The current SimpleRisk version. grep APP_VERSION /var/www/simplerisk/includes/version.php, or read it in the admin area. You'll match it on the new host.
The install path and web-server user. Usually /var/www/simplerisk, served by www-data on Debian/Ubuntu or apache on the RHEL family. Confirm yours.
The database connection values in simplerisk/includes/config.php: DB_HOSTNAME, DB_PORT, DB_USERNAME, DB_PASSWORD, DB_DATABASE.
Whether the database moves too. If MySQL is on the box you're rebuilding, it moves with it. If it's a separate or managed database that isn't changing, you move only the application and re-point config.php at the unchanged database.
Active Extras — Settings cog → Settings Hub → Extras. The Encrypted Database Extra is the one that changes this procedure; see Step 5.
Approximate sizes of the database and uploads/, for transfer planning.

Keep the old host reachable and its backups intact until the new host passes verification in Step 6. That's your rollback, and holding it costs nothing.

Step-by-step

You've got two paths. Path A is faster and fits a like-for-like refresh; Path B is a little more work and is the right call when the distribution or PHP version changes.

Path A — Lift-and-shift (like-for-like refresh)

Use this when the new host runs the same, or a very close, OS and PHP version as the old one.

1. Quiesce and dump the database. Take a maintenance window so the copy is a clean point in time.

mysqldump -u {DB_USERNAME} -p --single-transaction --routines --triggers --events \
  {DB_DATABASE} > /root/simplerisk-db.sql

--single-transaction produces a consistent dump of SimpleRisk's InnoDB tables without locking users out. Confirm the file isn't empty and closes with a -- Dump completed line.

2. Copy the application directory. rsync preserves permissions, timestamps, and the whole tree, which means config.php, uploads/, and the encryption key file all travel in one move.

rsync -avz --progress /var/www/simplerisk/ {new-host}:/var/www/simplerisk/
scp /root/simplerisk-db.sql {new-host}:/root/

3. Restore the database on the new host. If the database moves with the box, set sql_mode = '' (SimpleRisk rejects the strict modes MySQL enables by default), then load the dump.

mysql -u root -p -e "CREATE DATABASE IF NOT EXISTS simplerisk;"
mysql -u root -p simplerisk < /root/simplerisk-db.sql

Recreate the SimpleRisk database user and its grants if they didn't carry over, matching the credentials in config.php: SELECT, INSERT, UPDATE, ALTER, DELETE, CREATE, DROP, INDEX, REFERENCES, and LOCK TABLES on the simplerisk database. The installer grants all of these on every install, not just encrypted ones.

4. Reconcile config.php and fix permissions. Edit the database block in simplerisk/includes/config.php only if the database's address changed. Keep DB_HOSTNAME as 127.0.0.1 for a same-box database — not localhost, which forces a Unix-socket connection with different behavior. Then hand ownership to the web-server user:

sudo chown -R www-data:www-data /var/www/simplerisk    # apache:apache on RHEL family

On RHEL-family hosts with SELinux enforcing, restore the web contexts too, or Apache won't be able to serve and write the tree:

sudo restorecon -Rv /var/www/simplerisk

5. Stand up the web server. Install the same web stack the old host ran (Apache with mod_php, or Nginx with PHP-FPM), point the document root at /var/www/simplerisk, and confirm PHP 8.1+ and the thirteen required extensions are present with php -m. Then go to Step 6.

Path B — Fresh install, then restore

Use this when the new host runs a different distribution or a newer PHP, or when you'd rather start from a clean code tree.

Install SimpleRisk at your current version on the new host and run the browser installer once against a new empty database, exactly as in Installing on Linux. That gives you a working install with a config.php correctly wired to the new environment. Then restore your data over it:

mysql -u root -p -e "DROP DATABASE IF EXISTS simplerisk; CREATE DATABASE simplerisk;"
mysql -u root -p simplerisk < /root/simplerisk-db.sql

Copy the uploads/ directory from the old host into simplerisk/uploads/ on the new one and chown it to the web-server user. Keep the new install's database credentials in config.php — the installer already wrote them correctly. If you use encryption, place the key file now (Step 5). This is the same restore pattern documented in Database Backup and Restore, so it's well-trodden ground.

5. Carry the encryption key (if the Encrypted Database Extra is active)

If encryption is on, your sensitive fields are ciphertext, readable only with the master key file at simplerisk/extras/encryption/includes/init.php. Path A copies it across automatically as part of the directory sync — confirm it landed. Path B does not recreate it, so copy it by hand to the same path on the new host. The key isn't in the database dump; migrate without it and the restored data displays as unreadable base64 with no recovery path. See Enabling Encryption for the key-handling detail and the deactivate-then-reactivate alternative that removes the key from the move entirely.

6. Verify on the new host

Reach the new host by IP or a temporary hostname, before you touch DNS, and log in with your existing admin credentials — they came across in the database. Confirm the dashboard and risk register load with matching counts, several risks open with readable text rather than base64 blobs, uploaded evidence files open, a test risk round-trips cleanly, and the active Extras still report as active. If any of that fails, the old host is still your clean rollback; fix and retry before cutting over.

7. Upgrade if you're due, then cut over

With the host move verified at your current version, upgrade to the current release now if you're overdue — lay down the current tarball (preserving config.php and uploads/), run the database upgrade from /admin/upgrade.php, and upgrade each active Extra. Keep it a separate step from the host move. Then install TLS and the HTTP-to-HTTPS redirect, recreate the cron jobs (notifications and syncs depend on them), repoint DNS, take a final delta dump if users kept working on the old host during testing, and hold the old host as a rollback for a couple of weeks before retiring it.

Common pitfalls

Moving files without the database, or the database without the files. Both have to move; the application needs the schema and the data together. A copied directory pointed at an empty database is a fresh install, not your install.
Leaving uploads/ behind on the fresh-install path. The database holds references to evidence files, not the files. Path A carries them automatically; Path B needs the directory copied explicitly.
Losing the encryption key on the fresh-install path. init.php isn't in the dump. If encryption was on and the key didn't come across, the restored data is unrecoverable. Copy it, or deactivate encryption before the move and re-activate after.
Wrong ownership or SELinux context on the new host. A tree the web-server user can't read or write produces permission errors that look like application bugs. chown -R to the web user, and on RHEL-family hosts restorecon -Rv.
localhost for a same-box database. Use 127.0.0.1 to force a TCP connection and match the install default; localhost selects a Unix socket and behaves differently.
Lift-and-shift onto a materially newer PHP. Path A carries the old code, which may not suit a much newer PHP. When the distribution or PHP version jumps, use Path B and install fresh at your version instead.
Bundling the host move with a version upgrade. Match the version first, verify, then upgrade. One change at a time keeps failures diagnosable.
Retiring the old host too soon. It's a free rollback. Keep it until the new host has run in production for a couple of weeks.