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

01.02 Installing on Linux

Install SimpleRisk natively on Linux — install the prerequisites, place the SimpleRisk source, configure the web server, point the browser at the install URL, and walk the 6-step initial wizard. The native Linux deployment is the most common production deployment shape.

Why this matters

Native Linux is the deployment shape most SimpleRisk production installations use. The reasons aren't exciting: PHP and MySQL are mature on Linux, the operations team usually already has the tooling for log management and monitoring, and the cost-versus-flexibility trade-off lands on top for organizations not specifically committed to containerization. The Docker and cloud-image deployments (covered in Installing via Docker and Installing on Cloud) layer different patterns on top of the same application, but the underlying SimpleRisk install behavior is identical.

The native install path is browser-driven once the prerequisites are in place — there's no command-line installer to run; SimpleRisk's index.php detects an uninstalled state and redirects to the installer, which walks the 6-step wizard documented in The Initial Configuration Wizard. The Linux-specific work is everything before that point: installing PHP and the required extensions, installing MySQL, placing the SimpleRisk source on disk, configuring the web server, setting filesystem permissions correctly.

The other thing worth knowing: most install failures aren't SimpleRisk-specific failures. They're prerequisite failures (missing PHP extension, MySQL strict-mode enabled, web server user can't write to the directory) that the installer's Health Check catches. Working through this article in order — install prerequisites, verify them, then run the installer — produces a clean install most of the time. Skipping ahead to "just run the installer" produces the recurring "Step 2 failed, what now?" pattern that consumes operator time.

Before you start

Have these in hand:

  • A Linux server (physical, virtual, or cloud-instance) running a current Ubuntu LTS, Debian stable, or RHEL-family release (Rocky, Alma, RHEL itself). The choice affects the package names but not the overall workflow. Sizing per System Requirements.
  • Root or sudo access for installing system packages and editing config files.
  • A network plan: the server's hostname or IP, the URL SimpleRisk will be reached at (an A record or DNS entry pointing to the server), the port (default 443 for HTTPS, 80 for HTTP), and any firewall rules that need adjustment.
  • A TLS certificate strategy if you'll use HTTPS in production (recommended). Either Let's Encrypt with certbot, a certificate from your organization's PKI, or a commercial CA cert. See HTTPS and TLS Configuration for the SimpleRisk-side configuration.
  • A read on which database setup you want: SimpleRisk's MySQL on the same server, or a separate MySQL host. For initial deployments the same-server pattern is simpler; for production-scale or compliance-driven deployments, a separate database host is common.
  • A read on the System Requirements article, especially the PHP-extension list. Knowing which packages to install on this particular distribution is the first concrete prerequisite.

Step-by-step

1. Install PHP 8.1 and the required extensions

For Ubuntu/Debian:

sudo apt update
sudo apt install -y php8.1 php8.1-fpm php8.1-cli \
  php8.1-mysql php8.1-curl php8.1-mbstring \
  php8.1-xml php8.1-zip php8.1-gd \
  php8.1-ldap php8.1-bcmath php8.1-intl

If php8.1 isn't in your distribution's default repositories, add the Ondřej PHP PPA:

sudo apt install -y software-properties-common
sudo add-apt-repository ppa:ondrej/php
sudo apt update

For RHEL/CentOS/Rocky/Alma with EPEL and Remi repositories enabled:

sudo dnf install -y php php-fpm php-cli \
  php-mysqlnd php-curl php-mbstring \
  php-xml php-zip php-gd \
  php-ldap php-bcmath php-intl

Verify the installation:

php -v   # expect PHP 8.1.x or newer
php -m   # confirm pdo, pdo_mysql, json, phar, zlib, mbstring, ldap, dom, curl, posix, zip, gd are listed

The 12 required extensions are documented in System Requirements. All twelve must be present; the installer's Health Check (Step 2) will block installation otherwise.

2. Install and configure MySQL

For Ubuntu/Debian:

sudo apt install -y mysql-server
sudo systemctl enable --now mysql
sudo mysql_secure_installation

For RHEL/CentOS/Rocky/Alma:

sudo dnf install -y mysql-server
sudo systemctl enable --now mysqld
sudo mysql_secure_installation

After installation, configure the SQL modes. Edit /etc/mysql/mysql.conf.d/mysqld.cnf (Debian/Ubuntu) or /etc/my.cnf.d/server.cnf (RHEL family) and add or modify the [mysqld] section:

[mysqld]
sql_mode = ''

The empty sql_mode removes the default-strict modes (STRICT_TRANS_TABLES, NO_ZERO_DATE, ONLY_FULL_GROUP_BY) that block SimpleRisk. If you'd rather keep some strict modes for other databases on this server, configure SimpleRisk's modes per-session via the SimpleRisk MySQL user instead — but for dedicated SimpleRisk MySQL instances, the empty sql_mode is simpler.

Restart MySQL to pick up the change:

sudo systemctl restart mysql   # or mysqld on RHEL

The installer creates the SimpleRisk database and the SimpleRisk MySQL user during Step 6; you don't need to pre-create them. You do need a MySQL admin user (typically root) that the installer can use to create the database and grant permissions — provide those credentials in Step 3.

3. Install Apache or Nginx

Both web servers work; pick the one your team already operates.

For Apache on Ubuntu/Debian with mod_php:

sudo apt install -y apache2 libapache2-mod-php8.1
sudo systemctl enable --now apache2

For Nginx with PHP-FPM:

sudo apt install -y nginx   # PHP-FPM was installed in Step 1
sudo systemctl enable --now nginx php8.1-fpm

Test the web server is responsive: open http:// / in a browser; you should see the default Apache or Nginx welcome page.

4. Place the SimpleRisk source

Download the latest SimpleRisk release. The release tarballs are available from https://github.com/simplerisk/code-development/releases — pick the most recent stable release.

cd /var/www
sudo wget https://github.com/simplerisk/code-development/archive/refs/tags/
  
   .tar.gz sudo tar xzf 
   
    .tar.gz sudo mv code-development-
    
     /simplerisk /var/www/simplerisk

(Adjust the path /var/www/simplerisk to wherever you want the install. The path you pick becomes the document root for the web server.)

Set ownership and permissions so the web server user has read and write access:

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

sudo find /var/www/simplerisk -type d -exec chmod 750 {} \;
sudo find /var/www/simplerisk -type f -exec chmod 640 {} \;

Some SimpleRisk paths need write access by the web server user; the installer's Health Check (Step 2) verifies this and reports any directories that aren't writable. If the check fails, expand the writable scope appropriately for your environment.

5. Configure the web server document root

For Apache, edit /etc/apache2/sites-available/000-default.conf (or create a new vhost file) so the DocumentRoot points at the SimpleRisk install:


  
    ServerName simplerisk.example.com DocumentRoot /var/www/simplerisk 
   
     AllowOverride All Require all granted 
    ErrorLog ${APACHE_LOG_DIR}/simplerisk-error.log CustomLog ${APACHE_LOG_DIR}/simplerisk-access.log combined

Enable the site and restart Apache:

sudo a2ensite 000-default
sudo systemctl restart apache2

For Nginx with PHP-FPM, create /etc/nginx/sites-available/simplerisk (Debian/Ubuntu) or /etc/nginx/conf.d/simplerisk.conf (RHEL family):

server {
    listen 80;
    server_name simplerisk.example.com;
    root /var/www/simplerisk;

    index index.php index.html;

    location / {
        try_files $uri $uri/ /index.php?$query_string;
    }

    location ~ \.php$ {
        include snippets/fastcgi-php.conf;
        fastcgi_pass unix:/var/run/php/php8.1-fpm.sock;
    }

    location ~ /\.ht {
        deny all;
    }

    error_log /var/log/nginx/simplerisk-error.log;
    access_log /var/log/nginx/simplerisk-access.log;
}

Enable the site and reload Nginx:

sudo ln -s /etc/nginx/sites-available/simplerisk /etc/nginx/sites-enabled/
sudo nginx -t   # syntax check
sudo systemctl reload nginx

6. Open the installer in a browser

Point your browser at http://simplerisk.example.com/ (or whichever URL your web server is configured to serve). SimpleRisk's index.php detects that the install hasn't been run yet (the SIMPLERISK_INSTALLED constant in config.php doesn't exist or isn't set to true) and redirects you to the installer's Step 1.

The installer is browser-driven and walks 6 steps:

  1. Welcome — introduction to the installation.
  2. Health Check — validates PHP version, the 12 required extensions, directory permissions, and outbound web connectivity.
  3. Database Credentials — your MySQL admin credentials (used to create the SimpleRisk database and user).
  4. SimpleRisk Configuration — the SimpleRisk-specific values (database name, SimpleRisk MySQL username, allowed host, default language, session-storage option).
  5. Admin Account Creation — the first administrative user account.
  6. Installation Execution — runs the actual install (creates database, creates user, fetches and loads schema, creates admin, writes config.php).

The full per-step walk-through is in The Initial Configuration Wizard. Most of the install time is the Step 6 schema load; budget a few minutes.

7. Configure HTTPS

After the basic install completes, configure HTTPS for production. SimpleRisk doesn't enforce HTTPS itself — that's the web server's job. The full configuration is in HTTPS and TLS Configuration; briefly:

  • Obtain a TLS certificate (Let's Encrypt via certbot is the most common path).
  • Configure the web server to listen on 443 with the certificate.
  • Add an HTTP-to-HTTPS redirect (web-server-side; SimpleRisk doesn't do this internally).
  • Update the SimpleRisk simplerisk_base_url setting to use https:// (the installer detects this from the request origin during Step 6 if you ran the installer over HTTPS; otherwise update post-install).

8. Install Extras as needed

After the base install, activate any Extras the program needs. The Extras live under simplerisk/extras/ and are activated through the admin panel at /admin/extras.php. The pattern is documented in Installing Extras; the strategic guidance on which Extras to activate is in the User Guide's When and How to Bring in Extras.

9. Set up the cron jobs

SimpleRisk has several cron jobs that handle scheduled work (notifications, framework updates, vulnerability syncs, AI processing, etc.). Configure your system cron (crontab -e for the user that should run them, typically the web server user or a dedicated simplerisk user) to invoke the cron scripts on appropriate cadences. The full configuration is in The Cron Jobs — at minimum, the notification cron should run every few minutes, and the maintenance crons should run daily.

10. Verify the install end-to-end

Log in with the admin account you created in Step 5. Walk through:

  • The dashboard loads.
  • You can navigate the sidebar (which shows the full menu for an admin account).
  • The Configure → Settings page is accessible.
  • A test risk submission and review works (validates the database write path).
  • (If HTTPS is configured) the URL bar shows the secure connection.
  • (If notifications are configured) trigger a test event and verify the email arrives.

If any of these fail, check the web server's error log and SimpleRisk's debug log at simplerisk/logs/ for diagnostic information.

Common pitfalls

A handful of patterns recur with Linux native installs.

  • Missing PHP extensions. The single most common installation failure. The Health Check (Step 2) lists each missing extension; install the corresponding php - package and restart the web server. Re-run the Health Check; it should pass.

  • MySQL SQL modes blocking install. The Health Check fails with "MySQL SQL mode includes STRICT_TRANS_TABLES" or similar. Edit /etc/mysql/mysql.conf.d/mysqld.cnf to set sql_mode = '' and restart MySQL.

  • Web server user can't write to simplerisk/. The Health Check fails on directory permissions. Run chown -R : /var/www/simplerisk with the right user/group for your distribution.

  • Apache mod_php vs Nginx PHP-FPM confusion. When both are installed (a common artifact of distribution defaults), they can fight for ports or service ownership. Disable whichever you're not using; SimpleRisk doesn't care which web server you use, but you have to pick one.

  • Letting the installer fetch the schema while outbound HTTPS is blocked. The installer fetches simplerisk-{language}-{version}.sql from raw.githubusercontent.com. If outbound HTTPS to GitHub is blocked, the install hangs at Step 6. Either open the firewall rule or pre-stage the SQL file locally and modify the installer's behavior accordingly (advanced; see the SimpleRisk repository for guidance).

  • Installing on a server that's also serving production traffic for something else. SimpleRisk's PHP processes can compete with other PHP applications for FPM workers; SimpleRisk's MySQL queries can compete with other database workloads. For evaluation installs, sharing a server is fine; for production, give SimpleRisk its own server (or at least its own resource pool).

  • Skipping the cron setup. Without the cron jobs running, the notification system goes silent (see Notifications and Email Preferences), framework updates don't process, and several Extras stop syncing. The cron setup is part of the install, not a separate optional step.

  • Forgetting to back up config.php after install. The simplerisk/includes/config.php file holds the database credentials and other install-specific values. Lose it and you're rebuilding from a database backup. Include it in the deployment's backup process from day one. See Database Backup and Restore.

Related

Reference

  • Permission required: Server-side: root or sudo to install packages and edit web server config; MySQL admin to create the database and user during the install. SimpleRisk-side: not applicable (pre-installation).
  • Implementing files: simplerisk/index.php (bootstrap; redirects to installer if uninstalled); simplerisk/install.php and simplerisk/includes/install.php (the 6-step wizard); simplerisk/includes/config.php (generated during Step 6).
  • Database tables: Created during Step 6 from the SQL schema fetched at https://raw.githubusercontent.com/simplerisk/database/{branch}/simplerisk-{language}-{version}.sql.
  • config_settings keys: Set during Step 6: simplerisk_base_url, ssl_certificate_check_simplerisk, default_language, instance_id, schedule_cron_ping.
  • Web server config: Apache vhost or Nginx server block; DocumentRoot / root set to the simplerisk/ directory; PHP-FPM upstream configured for Nginx deployments.
  • External dependencies: PHP 8.1+ packages, MySQL server, Apache or Nginx; outbound HTTPS to raw.githubusercontent.com for the schema fetch.