Skip to content
English
Customer portal
Contact us
  • There are no suggestions because the search field is empty.

01.05 The Initial Configuration Wizard

The 6-step browser-based installer that runs on a fresh SimpleRisk install — Welcome, Health Check, Database Credentials, SimpleRisk Configuration, Admin Account Creation, Installation Execution. Per-step walk-through with the validation rules each step enforces and what gets written where.

Why this matters

The initial configuration wizard is the operator-facing surface for SimpleRisk's first-time install. It runs once, on first browser request to a fresh install, and walks 6 steps from prerequisite verification through schema load. Knowing what each step does and what it writes lets you debug install failures cleanly (the wizard's error messages are usually clear, but knowing why the validation exists helps you fix the root cause rather than working around the symptom).

The other thing worth knowing: the wizard is idempotent in spirit but not in mechanism. The bootstrap check (SIMPLERISK_INSTALLED constant in config.php) determines whether the wizard runs; once config.php exists with SIMPLERISK_INSTALLED=true, the wizard doesn't run again. If you need to rerun the wizard (because the previous attempt failed mid-Step-6, for example, or because you're re-installing into a clean database), you delete config.php and the wizard runs again. There's no "rerun wizard" button.

The third thing: the wizard writes both to disk (the config.php file) and to the database (the SimpleRisk schema, the admin user, several initial settings). Step 6 is where these writes happen; failures during Step 6 can leave the install in a partial state (some database writes succeeded, others didn't, config.php may or may not have been written). Recovery from a partial Step 6 typically involves dropping the database and re-running.

This article walks each step in detail, including the validation rules each step enforces and the data each step writes. Read it before running the installer for the first time so you know what to expect at each prompt.

Before you start

Have these in hand:

  • A fresh SimpleRisk install with prerequisites in place (see System Requirements) and the source on disk via Installing on Linux, Installing via Docker, or Installing on Cloud.
  • MySQL admin credentials (the credentials the installer will use during Step 3 to create the SimpleRisk database and user). On a fresh MySQL install, that's the root user with the password set during mysql_secure_installation.
  • The desired SimpleRisk database name and SimpleRisk MySQL username. The installer creates both during Step 6; pick names that won't collide with anything else in your MySQL instance.
  • The default language for the install. The installer's UI is rendered in the chosen language; the database schema is loaded from the language-specific SQL file (simplerisk-{language}-{version}.sql). 30+ languages are supported.
  • A username, email address, and password for the first admin user. The wizard creates this user during Step 6.
  • Outbound HTTPS to raw.githubusercontent.com for the schema fetch in Step 6. Without it, the install hangs at Step 6.

Step-by-step

1. Open the installer URL

Browser to http:// / . SimpleRisk's index.php checks for the SIMPLERISK_INSTALLED constant in simplerisk/includes/config.php; if the constant doesn't exist or isn't set to 'true', the bootstrap loads the installer.

If you reach a "SimpleRisk is already installed" message instead of the wizard, config.php exists with SIMPLERISK_INSTALLED=true. Either you've already installed (in which case use the install rather than re-running the wizard), or someone left a stale config.php that needs removing.

2. Step 1 — Welcome

The Welcome step is informational. It introduces the installer and the steps to come. There's no input on this step; click through to Step 2.

3. Step 2 — Health Check

The Health Check validates prerequisites:

  • PHP version. Verifies PHP 8.1 or newer.
  • PHP extensions. Verifies all 12 required extensions are loaded: pdo, pdo_mysql, json, phar, zlib, mbstring, ldap, dom, curl, posix, zip, gd. Each missing extension is listed individually.
  • Memory limit. Verifies the PHP memory_limit is sufficient (typically at least 128 MB).
  • max_input_vars. Verifies PHP's max_input_vars ini setting is high enough for the larger forms SimpleRisk uses.
  • Directory permissions. Recursively verifies the web server user can write to the simplerisk/ directory tree.
  • Web connectivity. Verifies the install can reach raw.githubusercontent.com over HTTPS (needed for Step 6).

Each check produces a Pass or Fail indicator. A failed check blocks Step 3; the operator must fix the underlying issue and reload the page. Re-running the page repeats the checks; once all pass, the wizard advances.

The most common failures and their fixes are documented in Installing on Linux § Common pitfalls. At the high level: install missing PHP extensions and restart the web server, fix directory permissions with chown and chmod, open outbound HTTPS to GitHub.

4. Step 3 — Database Credentials

The Database Credentials step collects the credentials the installer will use to connect to MySQL. These are the MySQL admin credentials, not SimpleRisk-specific credentials — Step 6 uses these to create the SimpleRisk database and the SimpleRisk MySQL user.

Fields:

  • Database Hostname — typically localhost for same-server MySQL, the container name (e.g., mysql) for Docker Compose deployments, or the hostname/endpoint for managed databases (RDS endpoint, Azure DB hostname, Cloud SQL connection name).
  • Database Port — defaults to 3306. Adjust for non-standard MySQL ports.
  • Database Username — the MySQL admin username (typically root).
  • Database Password — the MySQL admin password.
  • Database SSL Certificate Path — optional. Provide a path to a PEM certificate file if the connection should use SSL/TLS. Stored in the generated config.php as DB_SSL_CERTIFICATE_PATH.

When you submit, the installer:

  1. Tests the PDO connection with the provided credentials.
  2. Queries the MySQL @@sql_mode variable and verifies that STRICT_TRANS_TABLES, NO_ZERO_DATE, and ONLY_FULL_GROUP_BY are not present. If any are present, the wizard returns a clear error explaining which mode is the problem.

If the connection or SQL-mode check fails, the wizard stays on Step 3 with the error displayed. Fix the underlying issue (correct credentials, MySQL sql_mode configuration) and resubmit.

5. Step 4 — SimpleRisk Configuration

The SimpleRisk Configuration step collects the SimpleRisk-specific values that determine the database name, the SimpleRisk MySQL user, the install's host pattern, and the language.

Fields:

  • SimpleRisk Hostname — the hostname or IP that SimpleRisk will run on. This becomes the host pattern for the SimpleRisk MySQL user (CREATE USER 'simplerisk'@' ' ). Special values:
  • localhost for same-server installs (MySQL only allows the user from the same server).
  • A specific hostname or IP for separate-server installs.
  • % for wildcard (any host can connect — appropriate for some cloud-database scenarios but security-relax it deliberately).
  • A comma-separated list (e.g., host1,host2,host3) for multi-instance deployments where multiple SimpleRisk hosts share a database.
  • Database Name — the name of the database the installer will create (max 64 characters per MySQL limits). Defaults to simplerisk. Pick a name that doesn't collide with existing databases on the MySQL instance.
  • SimpleRisk Username — the username the installer will create for SimpleRisk's runtime database access (max 16 characters per MySQL limits). Defaults to simplerisk. The installer auto-generates a strong password for this user.
  • Default Language — dropdown of supported languages (30+). The selection determines which language-specific schema SQL the installer fetches in Step 6, and sets the default_language setting that controls which translations new users see.
  • Use Database for Sessions — checkbox (default: true). When enabled, PHP session data is stored in the SimpleRisk database rather than on the filesystem. Recommended for multi-instance deployments and for installations where filesystem session storage would be problematic. Stored as the USE_DATABASE_FOR_SESSIONS constant in config.php.
  • Database SSL Certificate Path — optional, same as Step 3.

When you submit, the installer:

  1. Validates the SimpleRisk hostname (must be a valid hostname, IP address, wildcard pattern, or netmask).
  2. Verifies the database doesn't already exist (rejects collision with existing databases).
  3. Verifies the SimpleRisk MySQL username doesn't already exist (queries mysql.user and mysql.db tables).

Failures at this step are usually name collisions; pick different names and resubmit.

6. Step 5 — Admin Account Creation

The Admin Account Creation step collects the credentials for the first administrative user.

Fields:

  • Username — the login username for the admin account.
  • Full Name — the display name.
  • Email Address — the email address (validated for basic email format).
  • Password — the admin's password.
  • Confirm Password — the same password again.
  • Mailing List Opt-In — optional checkbox to receive SimpleRisk product updates.

When you submit, the installer:

  1. Verifies all required fields are present.
  2. Verifies the email format is valid.
  3. Verifies the password and confirmation match.

The admin user is not yet created at this point; the values are held for use in Step 6.

7. Step 6 — Installation Execution

Step 6 is where the actual install runs. The installer does the following, in order:

  1. Creates the database — runs CREATE DATABASE {sr_db}.
  2. Creates the SimpleRisk MySQL user — runs CREATE USER '{sr_user}'@'{sr_host}' IDENTIFIED BY ... with the auto-generated password.
  3. Grants minimal privileges — runs GRANT SELECT, INSERT, UPDATE, ALTER, DELETE, CREATE, DROP, INDEX, REFERENCES ON {sr_db}.* TO '{sr_user}'@'{sr_host}'. Note the deliberately scoped permissions — SimpleRisk doesn't need superuser; granting only the operations it actually performs is the principle-of-least-privilege application.
  4. Fetches the database schema — downloads simplerisk-{language}-{version}.sql from https://raw.githubusercontent.com/simplerisk/database/{branch}/. The branch and version are determined by the SimpleRisk source's release version. If the version-specific schema isn't published, the installer falls back to the latest released schema and runs upgrade scripts to bring the database to the current version.
  5. Loads the schema into the database via the SimpleRisk MySQL user. This creates all the SimpleRisk tables and seeds the initial reference data.
  6. Creates the admin user — inserts a row into the user table with type='simplerisk', role_id=1 (admin), admin=1, the password hashed with bcrypt, all teams from the team table assigned, all permissions from the permissions table assigned. Custom display settings JSON is initialized for risk-related views.
  7. Writes config.php — generates simplerisk/includes/config.php with the database credentials, the SSL certificate path (if provided), the session-storage flag, and the SIMPLERISK_INSTALLED constant set to true. If the file already exists and is writable, it's overwritten; if not, the installer displays the PHP code for manual copy-paste.
  8. Verifies HTTPS — if the request originated over HTTPS (i.e., the installer was reached at https://), runs a curl health check against the install's own URL with strict TLS verification. Sets the ssl_certificate_check_simplerisk setting to '1' (passed) or '0' (failed).
  9. Writes initial settings — populates the settings table with simplerisk_base_url (detected from the request origin), default_language (from Step 4), instance_id (a 50-character random token uniquely identifying this install), and schedule_cron_ping (a randomly-generated cron schedule for the install's regular ping to SimpleRisk's central ping endpoint, used for usage analytics and update notifications).

When Step 6 completes successfully, the installer redirects to the SimpleRisk login page. Log in with the admin account from Step 5 and proceed with post-install configuration (see Installing Extras, HTTPS and TLS Configuration, and the relevant chapters in this guide).

If Step 6 fails partway through, the install is in an indeterminate state. Recovery typically involves:

  • Dropping the partially-created database (DROP DATABASE {sr_db}).
  • Removing the partially-created SimpleRisk MySQL user (DROP USER '{sr_user}'@'{sr_host}').
  • Removing the config.php file if it was written.
  • Re-running the wizard from Step 1.

Common pitfalls

A handful of patterns recur with the wizard.

  • Health Check fails on missing PHP extensions. The single most common Step 2 failure. Install the missing extensions per Installing on Linux Step 1 and restart the web server. Re-run the Health Check.

  • Health Check passes locally but the production install fails on directory permissions. The web server runs as a different user in production than in development; verify the production web server user owns or can write to the simplerisk/ directory before running the wizard.

  • Step 3 fails on SQL mode. MySQL's strict modes (STRICT_TRANS_TABLES, NO_ZERO_DATE, ONLY_FULL_GROUP_BY) block SimpleRisk. Configure sql_mode = '' in MySQL's config (see System Requirements) and restart MySQL.

  • Step 3 fails with "access denied". The MySQL credentials are wrong, or the host the installer is connecting from isn't allowed by the MySQL user's host pattern. Verify by testing the credentials manually with mysql -h -u -p from the SimpleRisk install host.

  • Step 4 rejects the database name as already existing. Either the database genuinely exists from a prior install attempt (drop it before retrying) or there's a stale partial install (clean up the partial state).

  • Step 6 hangs on the schema fetch. The installer can't reach raw.githubusercontent.com. Check outbound HTTPS rules; check DNS resolution; check whether your environment requires a proxy (the installer doesn't have built-in proxy configuration; HTTPS_PROXY environment variable on the PHP process is the typical path).

  • Step 6 fails to write config.php. The web server user can't write to simplerisk/includes/. Either fix the directory permissions and retry, or copy the displayed PHP code into config.php manually.

  • Wizard runs again after a successful install. The bootstrap check looks for SIMPLERISK_INSTALLED=true in config.php. If the wizard re-runs, either config.php is missing (was deleted, was never written, was on a non-persistent volume) or the constant isn't set. Check the file's contents.

  • Picking the wrong language and wanting to change it. The default language set during Step 4 is the install's default for new users. Individual users can change their own language preference in their profile (see Your Account and Profile). Changing the install's default language post-install requires updating the default_language setting via admin configuration; the schema doesn't need re-loading because all language data is in the lang. .php files, not in the database.

  • Forgetting to record the auto-generated SimpleRisk MySQL password. The installer creates the SimpleRisk MySQL user with an auto-generated password and writes it to config.php. After install, the password is in config.php (DB_PASSWORD constant). For password rotation later, both config.php and the MySQL user's password need to be updated together.

  • Re-running Step 6 after a partial failure without cleaning up. If Step 6 created the database but failed before writing config.php, simply re-running Step 6 fails because the database already exists. Clean up the partial state (drop the database, drop the user) before retrying.

Related

Reference

  • Permission required: Server-side: filesystem write to simplerisk/; MySQL admin to create the database and user. SimpleRisk-side: not applicable.
  • Implementing files: simplerisk/index.php (bootstrap; checks SIMPLERISK_INSTALLED); simplerisk/install.php (entry point); simplerisk/includes/install.php (the 6-step simplerisk_installation() function plus the per-step handlers step_1_install_page() through step_6_simplerisk_installation(), the helpers installer_check_php_extensions() line 1613, installer_check_directories() line 1637, installer_add_admin_user() line 1698, create_config_file()); simplerisk/includes/config.php (generated during Step 6).
  • Database tables: settings (populated during Step 6 with simplerisk_base_url, ssl_certificate_check_simplerisk, default_language, instance_id, schedule_cron_ping); user, team, permissions (admin user added during Step 6); the full SimpleRisk schema (created during Step 6 from the GitHub-hosted SQL).
  • config_settings keys: simplerisk_base_url, ssl_certificate_check_simplerisk, default_language, instance_id, schedule_cron_ping.
  • External dependencies: Outbound HTTPS to https://raw.githubusercontent.com/simplerisk/database/ for schema fetch (Step 6).