02.08 Migrating from Windows to a supported platform (Linux or Docker)

Why this matters

Windows and macOS are not supported host operating systems for SimpleRisk. PHP and MySQL run on both, but SimpleRisk isn't tested or supported against either, and an in-place update of a Windows install to a current release fails on the incompatibilities that removal introduced. If you're on Windows and your update stopped working, this is why — and the fix isn't to force the update, it's to move the data to a host we support.

The move is less daunting than it sounds. Your SimpleRisk data isn't entangled with Windows in any way. It lives almost entirely in one MySQL database, plus two directories on disk: the generated config.php and the uploads/ folder of evidence files. The application code is disposable — you redeploy it from an official image or tarball on the new host. So this is a backup-and-restore onto a supported platform, followed by an ordinary upgrade, not a conversion of anything.

One piece of advice up front, because it's the difference between a calm migration and a confusing one: deploy the new platform at the same SimpleRisk version you run today, restore into it, and confirm it works before you upgrade to the current release. Customers who change platform and version in one move can't tell, when something looks off, whether the platform or the version jump caused it. Two smaller steps you can each verify beat one big step you can't.

Before you start

Gather this from the Windows install first. It determines the exact commands and flags the one scenario that needs real care.

Your current SimpleRisk version. Read APP_VERSION in simplerisk\includes\version.php, or check the admin area. You'll pin the new platform to this version.
Which Extras are active. Settings cog → Settings Hub → Extras. Extras carry their own data and upgrade separately from Core. The Encrypted Database Extra is the one that changes this procedure — see Step 5 and the pitfalls.
The database connection values from simplerisk\includes\config.php: DB_HOSTNAME, DB_PORT, DB_USERNAME, DB_PASSWORD, DB_DATABASE.
The database engine. Older Windows bundles shipped MariaDB. Current SimpleRisk supports MySQL only, so target MySQL 8.x on the new host. A standard dump restores cleanly into MySQL whether the source was MySQL or MariaDB.
A target platform. Docker (the common choice for teams that already run containers), native Linux (Ubuntu LTS, Debian, or an RHEL-family distribution on a VM or bare metal), or SimpleRisk Hosted if you'd rather not maintain a host at all. See Installing via Docker and Installing on Linux.
Off-host storage for the backup files, reachable from both machines.
A maintenance window if the program is in active daily use, so the data you migrate is a clean point-in-time copy.

Keep the Windows server and its backups untouched until the new install passes verification in Step 6. That's your rollback, and it costs nothing to hold.

Step-by-step

1. Read the database credentials on Windows

Open simplerisk\includes\config.php in a text editor and note the database block:

define('DB_HOSTNAME', '127.0.0.1');   // may read 'localhost' on your install
define('DB_PORT', '3306');
define('DB_USERNAME', 'simplerisk');
define('DB_PASSWORD', '{your-db-password}');
define('DB_DATABASE', 'simplerisk');

2. Dump the database

Find mysqldump.exe in the bin folder of the bundled MySQL/MariaDB (search the SimpleRisk program folder). From a Command Prompt:

"{path-to-mysql-bin}\mysqldump.exe" -u {DB_USERNAME} -p ^
  --single-transaction --routines --triggers --events ^
  {DB_DATABASE} > C:\srk-backup\simplerisk-db.sql

-p with no value prompts for the password rather than leaving it in your shell history. --single-transaction gives a consistent dump of SimpleRisk's InnoDB tables without locking users out. If the command line isn't your preference, HeidiSQL, MySQL Workbench, and phpMyAdmin all export a database to a single .sql file — include both structure and data.

Before you trust the file, open it and confirm it isn't zero-length or truncated. A dump that ends cleanly closes with a -- Dump completed line.

3. Copy config.php and the uploads directory

Copy two more things to your backup folder:

simplerisk\includes\config.php — your record of the install's settings. You won't reuse its database credentials verbatim, but you'll want to reconcile a couple of values against it in Step 5.
The entire simplerisk\uploads\ directory — every uploaded evidence file, document attachment, and signed-off form. The database stores references to these files, not the files themselves. Skip this folder and every evidence link in the restored install points at nothing.

4. Move the backups off the Windows box

Copy the .sql dump, config.php, and the uploads\ contents to storage that isn't the Windows server. You'll pull them onto the new host from there. The full backup discipline — off-host storage, retention, test restores — is in Database Backup and Restore.

5. If you use the Encrypted Database Extra, copy the master key

Read this whether or not you think encryption is on. If the Encrypted Database Extra is active, your sensitive fields are stored as ciphertext, decryptable only with the install's master key file:

simplerisk\extras\encryption\includes\init.php

Copy that file with the rest of your backup and treat it as a secret in transit. It defines ENCODED_KEY, it's the only copy, and it does not travel inside the database dump — encryption keys are configuration, not data. Migrate the database without it and your restored data displays as unreadable base64 blobs, with no recovery path. If you're not sure whether the Extra is active, check the Extras tile before you start; when in doubt, back the file up anyway.

There's a way to sidestep the key dependency entirely: deactivate the Encrypted Database Extra on the Windows install first, which decrypts the data in place, migrate the now-plaintext database, and re-activate encryption on the new host afterward. It costs a maintenance window on each side but removes the single riskiest artifact from the move. See Enabling Encryption for the activation and deactivation flows.

6. Stand up the new platform at your current version

Deploy a fresh SimpleRisk on the target platform, pinned to the version you run today, and complete the installer wizard against a new empty database. This gives you a working install at your current version with a config.php correctly wired to the new database — you'll overwrite the data next, but keep that correct connection.

For Docker, use the multi-container pattern (SimpleRisk container plus a separate MySQL container). Pin the image tag to your version rather than latest, and pass the empty --sql-mode= to MySQL so the strict modes SimpleRisk rejects stay off. The canonical Compose files live in the simplerisk/docker repository; Installing via Docker walks the pattern.

services:
  simplerisk:
    image: simplerisk/simplerisk:{your-current-version}
    ports: ["80:80"]
    volumes:
      - simplerisk-config:/var/www/simplerisk/includes/config.php
      - simplerisk-uploads:/var/www/simplerisk/uploads
    depends_on: [mysql]
  mysql:
    image: mysql:8.4
    environment:
      - MYSQL_ROOT_PASSWORD={root-secret}
      - MYSQL_DATABASE=simplerisk
      - MYSQL_USER=simplerisk
      - MYSQL_PASSWORD={app-secret}
    command: ["--sql-mode="]
    volumes: ["mysql-data:/var/lib/mysql"]
volumes: { simplerisk-config: , simplerisk-uploads: , mysql-data: }

For native Linux, install PHP 8.1+ and the thirteen required extensions, MySQL 8.x with sql_mode = '', and Apache or Nginx, then place the release tarball for your current version from the SimpleRisk releases page. The prerequisites are in System Requirements; the full sequence is in Installing on Linux.

If your exact version tag isn't published, deploy the closest available one and let the upgrade in Step 8 bring the schema forward. Don't run production on latest.

7. Restore your data

Copy simplerisk-db.sql onto the new host and replace the freshly-installed schema with your data. On native Linux:

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

On Docker, copy the file into the MySQL container and run the same two statements through it:

docker cp simplerisk-db.sql {mysql-container}:/tmp/db.sql
docker exec {mysql-container} sh -c 'mysql -uroot -p"$MYSQL_ROOT_PASSWORD" -e "DROP DATABASE IF EXISTS simplerisk; CREATE DATABASE simplerisk;"'
docker exec {mysql-container} sh -c 'mysql -uroot -p"$MYSQL_ROOT_PASSWORD" simplerisk < /tmp/db.sql'

Confirm the SimpleRisk database user exists with the privileges SimpleRisk needs — 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. The installer or the Compose MYSQL_USER created it.

Then reconcile config.php on the new host so its database block points at the new environment, not the old Windows values:

define('DB_HOSTNAME', '127.0.0.1');   // Docker: the MySQL service name, e.g. 'mysql'
define('DB_USERNAME', 'simplerisk');  // the user on the NEW database
define('DB_PASSWORD', '{new-db-password}');

If your Windows config.php used localhost for DB_HOSTNAME, do not carry that over. On Linux and in Docker, localhost forces a Unix-socket connection that fails; use 127.0.0.1 or the container's service name. The install template ships with 127.0.0.1 for exactly this reason.

Finally, restore the uploaded files into simplerisk/uploads/ on the new host and fix ownership so the web server user can read and write them:

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

If you use encryption, place your backed-up init.php at simplerisk/extras/encryption/includes/init.php on the new host now.

8. Verify at the same version, then upgrade

Log in with your existing admin credentials — they came across in the database. Before changing anything else, confirm the platform move alone succeeded:

The dashboard and risk register load, and the risk counts match the old system.
Several risks open with readable descriptions, mitigations, and comments. If you see long base64 blobs instead of text, the encryption key isn't in place; fix that before continuing.
Uploaded evidence files open, which proves the uploads/ restore.
A test risk submits, re-opens, and deletes cleanly.

If any of that fails, you still have a clean rollback: the Windows box is untouched. Fix the restore and retry.

Once it passes, upgrade to the current release the normal way — swap the Docker image tag (or extract the current tarball over the files, preserving config.php and uploads/), then run the database upgrade from /admin/upgrade.php, which walks the schema forward one release at a time. Upgrade each active Extra afterward; Core upgrades don't bring Extras along. The mechanics are in The Upgrade Process, Upgrading via Docker, and Upgrading on Bare Metal.

9. Cut over and decommission

With the new install verified and upgraded, finish the transition: put TLS and an HTTP-to-HTTPS redirect in front of it (web-server config on native Linux, a reverse proxy or cloud load balancer for Docker), set up the cron jobs so notifications and syncs keep running, and repoint DNS to the new host. If users kept working on Windows during your testing, take one final dump at cutover and re-import it so nothing is lost in the gap. Keep the Windows server and its backups on a retention hold for a couple of weeks before you decommission them.

Common pitfalls

Leaving the uploads directory behind. The single most common migration miss. The database references evidence files it doesn't contain; without simplerisk/uploads/, every attachment link breaks. Copy the folder explicitly.
Migrating an encrypted install without the master key. The second most common, and the more painful of the two. init.php isn't in the database dump. If encryption was on and the key didn't come along, the restored data is unrecoverable — support can't decrypt it either. Copy the key, or deactivate encryption before migrating and re-activate after.
Carrying localhost into the new config.php. It works on the old Windows box and fails silently on Linux and Docker, where localhost means a Unix socket. Use 127.0.0.1 or the MySQL service name.
Leaving MySQL's strict SQL modes on. A fresh MySQL 8.x defaults to modes SimpleRisk rejects. Set sql_mode = '' on native installs, or pass --sql-mode= to the MySQL container.
Changing platform and version at once. Deploy the new host at your current version, verify, then upgrade. Collapsing the two steps saves an hour and costs a day when something looks wrong and you can't localize the cause.
Trusting an untested dump. Confirm the .sql isn't truncated, and let Step 8's verification stand as your restore test before you decommission Windows.
Decommissioning Windows too early. The old install is a free rollback. Hold it until the new one has run in production for a couple of weeks.