---
title: 01.03 Installing via Docker
description: SimpleRisk's official Docker images live in the separate simplerisk/docker repository. Here's how to deploy with the published images, the docker-compose…
---
[Skip to content](https://support.simplerisk.com/kb/01-03-installing-via-docker#main-content)
English
Show submenu for translations
[Customer portal](https://support.simplerisk.com/tickets?hsLang=en)
[](https://www.simplerisk.com/)
Open main navigation
Close main navigation
- English
Show submenu for translations
- [Customer portal](https://support.simplerisk.com/tickets)
- [Contact us](https://www.simplerisk.com/about-us/contact-us)
[Contact us](https://www.simplerisk.com/about-us/contact-us)
How can we help you?
- There are no suggestions because the search field is empty.
1. [SimpleRisk Knowledge Base](https://support.simplerisk.com/kb?hsLang=en)
2. [Administrator Guide](https://support.simplerisk.com/kb/administrator-guide?hsLang=en)
3. [01 Installation and Deployment](https://support.simplerisk.com/kb/administrator-guide?hsLang=en#01-installation-and-deployment)
# 01.03 Installing via Docker
## SimpleRisk's official Docker images live in the separate simplerisk/docker repository. Here's how to deploy with the published images, the docker-compose pattern, the volume conventions, and the considerations specific to containerized deployments.
## Why this matters
The Docker deployment shape is the most common SimpleRisk deployment for organizations that already operate containerized infrastructure. The image is self-contained (PHP, the SimpleRisk source, the supervised entry point all packaged together), the deployment artifacts are version-controlled, and the cattle-not-pets lifecycle matches the rest of the organization's workload model. For organizations new to containers, the Docker path adds learning overhead that a native Linux install avoids; for organizations already running everything containerized, the Docker path is the obvious fit.
The honest scope to know: **the Docker artifacts are NOT in the SimpleRisk application repository** (the one this Admin Guide ships in). The Docker support (Dockerfiles, image-build pipeline, docker-compose templates) lives in the separate [`simplerisk/docker`](https://github.com/simplerisk/docker) repository on GitHub. This article describes the deployment pattern based on the published images; for the canonical Docker-side reference (image tags available, build instructions, image internals), the `simplerisk/docker` repository is the source of truth.
The other thing worth knowing: containerized SimpleRisk runs the same application as native-Linux SimpleRisk. The 6-step initial wizard, the Extras model, the v2 API surface, the operational mechanics — all identical. The Docker-specific concerns are the deployment shape (containers vs. processes), the data persistence (volume mounts), the configuration injection (environment variables, mounted config files), and the upgrade workflow (image pulls vs. file replacement). Those are the operationally distinctive bits documented here.
## Before you start
Have these in hand:
- **A Docker-capable host** (or a container orchestration platform like Kubernetes that can run the image). Docker Engine, Docker Desktop, or any compatible runtime works.
- **Docker Compose** (or `docker compose` plugin for newer Docker versions). Most SimpleRisk Docker deployments use Compose for the multi-container pattern (SimpleRisk image + MySQL image).
- **Persistent storage** for the SimpleRisk database and the application's writable directories. Docker volumes (managed) or host bind mounts (operator-managed) both work; pick the pattern your operations team prefers.
- **A reverse proxy or load balancer** for production HTTPS termination. SimpleRisk's container typically listens on HTTP internally; the production deployment puts a reverse proxy in front (Nginx, HAProxy, AWS ALB, etc.) to handle TLS, redirect HTTP to HTTPS, and add HSTS headers.
- **A read on the [System Requirements](https://support.simplerisk.com/kb/01-01-system-requirements?hsLang=en)** — the underlying application has the same requirements regardless of deployment shape, so the prerequisites still apply.
- **The image tag you want to deploy.** The published images are tagged by SimpleRisk version; the [`simplerisk/docker`](https://github.com/simplerisk/docker) repository documents which tag corresponds to which SimpleRisk release. Pin to a specific version rather than `latest` for production.
## Step-by-step
### 1. Get the Docker artifacts
Clone the [`simplerisk/docker`](https://github.com/simplerisk/docker) repository or download a release tarball. The repository contains:
- **Dockerfile(s)** — the image build definitions. Useful for reading the image's internals or for building custom variants.
- **docker-compose.yml** templates — reference Compose configurations for common deployment shapes.
- **Volume conventions** documented in the README — which paths in the container correspond to which SimpleRisk concerns (web root, logs, configuration, uploads).
Read the `simplerisk/docker` README for the current canonical guidance; this article describes the *general* pattern, but the specific image names, tags, and Compose files in that repository are authoritative for any given release.
### 2. Pick a deployment shape
Three common Docker deployment patterns:
- **Single-container with embedded MySQL** — the SimpleRisk image runs Apache, PHP, and MySQL all together. Simplest to deploy; appropriate for evaluation, demo, and small single-team installations. Not recommended for production — when you upgrade SimpleRisk, the database upgrade is bundled, and database backups have to extract through the same container.
- **Multi-container with separate MySQL container** — the SimpleRisk image runs Apache + PHP, an official MySQL image runs the database, the two containers communicate over a Docker network. The standard production-grade pattern; documented in the `simplerisk/docker` repository's reference Compose file. Recommended for most deployments.
- **Multi-container with external managed database** — the SimpleRisk image runs Apache + PHP, the database lives on managed RDS/Aurora/CloudSQL/Azure Database/etc. The right pattern for organizations with existing managed-database operational practice. The SimpleRisk container connects to the external database over network; configure the database credentials via environment variables or a mounted config file.
The choice affects the docker-compose configuration but not the SimpleRisk-side install steps.
### 3. Configure the environment
The SimpleRisk Docker image accepts configuration through:
- **Environment variables** for the database credentials and other install-time settings.
- **Mounted volumes** for persistent data (database files if using the embedded MySQL pattern, the SimpleRisk writable directories for logs and uploads, the `config.php` file once it's been generated).
- **Mounted configuration files** for advanced customizations (custom `php.ini` directives, custom Apache vhost overrides, etc.).
The `simplerisk/docker` repository's reference Compose file documents the specific environment variables and volume paths the published image expects. The general pattern looks like:
```
services:
simplerisk:
image: simplerisk/simplerisk:{version-tag}
ports:
- "80:80"
environment:
- DB_HOST=mysql
- DB_PORT=3306
- DB_NAME=simplerisk
- DB_USER=simplerisk
- DB_PASSWORD={your-secret}
volumes:
- simplerisk-config:/var/www/simplerisk/includes/config.php
- simplerisk-logs:/var/www/simplerisk/logs
- simplerisk-uploads:/var/www/simplerisk/uploads
depends_on:
- mysql
restart: unless-stopped
mysql:
image: mysql:8.4
environment:
- MYSQL_ROOT_PASSWORD={your-root-secret}
- MYSQL_DATABASE=simplerisk
- MYSQL_USER=simplerisk
- MYSQL_PASSWORD={your-secret}
command:
- --sql-mode=
volumes:
- mysql-data:/var/lib/mysql
restart: unless-stopped
volumes:
simplerisk-config:
simplerisk-logs:
simplerisk-uploads:
mysql-data:
```
Note the MySQL container's `--sql-mode=` argument — this disables the strict modes (`STRICT_TRANS_TABLES`, `NO_ZERO_DATE`, `ONLY_FULL_GROUP_BY`) that block SimpleRisk. See [System Requirements](https://support.simplerisk.com/kb/01-01-system-requirements?hsLang=en) for the SQL mode discussion.
On the MySQL version: the example above pins `mysql:8.4`, the official image's LTS tag and the same 8.4 LTS release the Linux setup script installs on Debian and RHEL-family hosts. The single-container `simplerisk/simplerisk` image doesn't give you this choice — it's built on Ubuntu and takes MySQL from Ubuntu's own archive, currently 8.0.x — but in a multi-container setup like this one, you're pulling the official MySQL image directly, so pin a current 8.4.x rather than tracking `latest` or reaching for 9.x, which isn't tested against.
(The above Compose file is illustrative; the canonical version with current image names and environment-variable conventions lives in the `simplerisk/docker` repository.)
### 4. Bring up the containers
```
docker compose up -d
```
Verify both containers are running:
```
docker compose ps
```
Both `simplerisk` and `mysql` services should show as healthy. If either is restarting or stopped, check the logs:
```
docker compose logs simplerisk
docker compose logs mysql
```
### 5. Run the SimpleRisk installer
Open `http://{docker-host}/` in a browser. The SimpleRisk container's entry point detects the uninstalled state and redirects to the 6-step initial wizard, the same wizard as the native Linux install. See [The Initial Configuration Wizard](https://support.simplerisk.com/kb/01-05-the-initial-configuration-wizard?hsLang=en) for the per-step walk-through.
The Docker-specific notes for the wizard:
- **Step 3 (Database Credentials)**: provide the *MySQL admin* credentials. If you used the Compose file above, that's `root` and the `MYSQL_ROOT_PASSWORD` you set. The hostname is the *container name* of the MySQL service (in the example, `mysql`), not `localhost`.
- **Step 4 (SimpleRisk Configuration)**: the SimpleRisk username and database name can match what the Compose file pre-created via the `MYSQL_USER` / `MYSQL_DATABASE` environment variables, or the installer can create them itself. If you used `MYSQL_USER`/`MYSQL_DATABASE`, the installer's "user already exists" check will surface; pick a different username/database, or pre-create them out-of-band.
- **Step 6 (Installation Execution)**: the installer fetches the schema from `raw.githubusercontent.com`. The container needs outbound HTTPS to GitHub; if your environment blocks this, configure a proxy at the Docker level (typically via `HTTPS_PROXY` environment variable) or pre-stage the schema in the image.
After Step 6 completes, the installer writes `config.php` to the mounted volume, and the application is operational.
### 6. Configure the reverse proxy for HTTPS
The Docker image typically listens on HTTP internally (port 80 in the container). For production, put a reverse proxy in front:
- **Nginx in a separate container** — add an Nginx service to the Compose file, terminate TLS there, proxy to the SimpleRisk container.
- **Traefik or Caddy** — both auto-issue Let's Encrypt certificates and proxy to backend services. Useful for development clusters and many small deployments.
- **Cloud-provider load balancer** — AWS ALB, Azure Application Gateway, GCP Load Balancer. The cloud LB handles TLS; the container behind it speaks HTTP.
The reverse proxy should:
- Terminate TLS with a valid certificate.
- Add an HTTP-to-HTTPS redirect for inbound HTTP requests.
- Pass the `X-Forwarded-Proto` and `X-Forwarded-For` headers so SimpleRisk knows the request was originally HTTPS (the `simplerisk_base_url` setting and cookie-secure-flag detection depend on this).
- Optionally add HSTS and other security headers the web server layer should still own. SimpleRisk sends its own `Content-Security-Policy` header from the application (new installs ship with it on by default; existing installs can turn it on from **Configure \> Security**), so a reverse-proxy CSP is only needed if you want something stricter than the built-in policy — see [Securing the Web Server](https://support.simplerisk.com/kb/09-05-securing-the-web-server?hsLang=en) before adding one.
See [HTTPS and TLS Configuration](https://support.simplerisk.com/kb/01-07-https-and-tls-configuration?hsLang=en) for the SimpleRisk-side considerations.
### 7. Set up cron jobs
The SimpleRisk image's behavior on cron varies by image variant. Some bundled images run cron internally (a supervisord process invokes the cron scripts on the container's own schedule); others expect the host or an external scheduler to invoke cron via `docker exec` or via the v2 API.
Confirm in the `simplerisk/docker` README which pattern your image uses. If the image doesn't run cron internally, set up a host-side cron entry that runs:
```
docker exec simplerisk php /var/www/simplerisk/cron/cron_notification.php
```
(And similar for the other cron scripts — see [The Cron Jobs](https://support.simplerisk.com/kb/02-07-the-cron-jobs?hsLang=en) for the full inventory.)
### 8. Plan for upgrades
Container upgrades use a different pattern than native Linux upgrades:
- Pull the new image tag.
- Stop the current container.
- Start a new container from the new image, with the same volume mounts.
- The application picks up the new code; any database migrations run on the next page load, walking the same release chain documented in [The Upgrade Process](https://support.simplerisk.com/kb/02-01-the-upgrade-process?hsLang=en).
The volume-based persistence (database, config, logs, uploads) survives the container replacement; the application code comes from the new image.
For zero-downtime upgrades on production deployments, run the new container alongside the old, drain the load balancer to the new container, and then stop the old. Standard blue-green container deployment patterns apply.
The upgrade-specific Docker workflow is in [Upgrading via Docker](https://support.simplerisk.com/kb/02-02-upgrading-via-docker?hsLang=en).
## Common pitfalls
A handful of patterns recur with Docker deployments.
- **Using `latest` tag in production.** The `latest` tag floats; production deployments should pin to a specific version tag so upgrades happen deliberately. Pin in the Compose file (`image: simplerisk/simplerisk:20260422-001` rather than `image: simplerisk/simplerisk:latest`). Schedule the upgrade explicitly when the next version is available.
- **Forgetting the `--sql-mode=` MySQL argument.** The MySQL official images default to strict modes that SimpleRisk's installer rejects. The `command: --sql-mode=` argument in the Compose file disables them; without this, the installer fails at Step 3 with the SQL mode error.
- **Volume mount points wrong for the image variant.** Different variants of the SimpleRisk Docker image expect mounts at different paths. The Compose file in this article uses `/var/www/simplerisk/...` paths; some image variants use `/srv/simplerisk/...` or other paths. Check the `simplerisk/docker` README for your image variant's specific paths.
- **Container can't reach GitHub for the schema fetch.** During Step 6, the installer needs outbound HTTPS to `raw.githubusercontent.com`. Container networking that blocks outbound HTTPS produces a Step 6 hang. Configure proxy settings if needed (`HTTPS_PROXY` environment variable in the Compose service).
- **Forgetting to mount `config.php` as a volume.** The installer writes `config.php` during Step 6. If `simplerisk/includes/config.php` isn't mounted as a volume, the file lives only inside the container's writable layer and is lost when the container is replaced (e.g., during an upgrade). Always mount `config.php` to a persistent volume.
- **Running cron from inside a stateless container without external scheduling.** Some operators stand up the SimpleRisk image and assume cron just works. If the image variant doesn't run cron internally, the cron jobs don't run, and notifications/syncs/maintenance go silent. Verify the cron pattern for your image variant; configure host-side cron if the image doesn't handle it.
- **Editing `config.php` inside the container instead of on its volume.** Settings that only a system administrator may change live in `config.php`, such as the networks asset discovery may scan ([Allowing asset discovery targets](https://support.simplerisk.com/kb/01-01-system-requirements#allowing-asset-discovery-targets)). Change the copy on the mounted volume so the change survives the next image upgrade. The queue worker picks up the edit on its own after the task it's running.
- **Sharing volumes across multiple SimpleRisk containers without coordination.** A scaled-out deployment with two SimpleRisk containers behind a load balancer needs to share the database (which is fine; both containers connect to the same MySQL), the uploads volume (so a file uploaded to container A is visible to container B), and the config (both containers need the same `config.php`). The cron, however, should run on *one* container only — running cron on both produces duplicate notifications and concurrent sync attempts. Designate one container (or a separate cron-only container) as the cron runner.
- **Treating volume snapshots as backups.** A Docker volume snapshot captures the volume's bytes at a moment in time, but a MySQL data volume snapshotted while the database is running can be inconsistent (mid-transaction state). For real backups, use the database's native backup tools (`mysqldump`, `xtrabackup`) inside the container; volume snapshots alone aren't a backup strategy. See [Database Backup and Restore](https://support.simplerisk.com/kb/02-05-database-backup-and-restore?hsLang=en).
- **Running outdated MySQL or PHP versions because the SimpleRisk image is pinned.** The SimpleRisk container has its own pinned PHP version; the MySQL container has its own MySQL version. Both should be updated as part of the security-patch cadence. The SimpleRisk version-tag pinning doesn't pin the MySQL container — those upgrade independently.
- **Not pulling images through a private registry mirror.** Production deployments that pull from Docker Hub directly are subject to Docker Hub's rate limits and any availability incidents. For production, mirror the SimpleRisk images through your organization's private container registry; pull from the mirror in production deployments.
## Related
- [System Requirements](https://support.simplerisk.com/kb/01-01-system-requirements?hsLang=en)
- [Installing on Linux](https://support.simplerisk.com/kb/01-02-installing-on-linux?hsLang=en) (the native pattern, covered in detail)
- [Installing on Cloud](https://support.simplerisk.com/kb/01-04-installing-on-cloud?hsLang=en)
- [The Initial Configuration Wizard](https://support.simplerisk.com/kb/01-05-the-initial-configuration-wizard?hsLang=en)
- [Installing Extras](https://support.simplerisk.com/kb/01-06-installing-extras?hsLang=en)
- [HTTPS and TLS Configuration](https://support.simplerisk.com/kb/01-07-https-and-tls-configuration?hsLang=en)
- [The Upgrade Process](https://support.simplerisk.com/kb/02-01-the-upgrade-process?hsLang=en)
- [Upgrading via Docker](https://support.simplerisk.com/kb/02-02-upgrading-via-docker?hsLang=en)
- [The Cron Jobs](https://support.simplerisk.com/kb/02-07-the-cron-jobs?hsLang=en)
- [Database Backup and Restore](https://support.simplerisk.com/kb/02-05-database-backup-and-restore?hsLang=en)
- [FAQs](https://support.simplerisk.com/kb/faqs?hsLang=en)
- [SimpleRisk Extras](https://support.simplerisk.com/kb/simplerisk-extras?hsLang=en#main-content)
- [Vulnerability Management Extra](https://support.simplerisk.com/kb/simplerisk-extras?hsLang=en#vulnerability-management-extra)
- [Team Separation Extra](https://support.simplerisk.com/kb/simplerisk-extras?hsLang=en#team-separation-extra)
- [Import-Export Extra](https://support.simplerisk.com/kb/simplerisk-extras?hsLang=en#import-export-extra)
- [Administrator Guide](https://support.simplerisk.com/kb/administrator-guide?hsLang=en#main-content)
- [00 About This Guide](https://support.simplerisk.com/kb/administrator-guide?hsLang=en#00-about-this-guide)
- [01 Installation and Deployment](https://support.simplerisk.com/kb/administrator-guide?hsLang=en#01-installation-and-deployment)
- [02 Upgrades and Maintenance](https://support.simplerisk.com/kb/administrator-guide?hsLang=en#02-upgrades-and-maintenance)
- [03 Users and Permissions](https://support.simplerisk.com/kb/administrator-guide?hsLang=en#03-users-and-permissions)
- [04 Authentication](https://support.simplerisk.com/kb/administrator-guide?hsLang=en#04-authentication)
- [05 Customization](https://support.simplerisk.com/kb/administrator-guide?hsLang=en#05-customization)
- [06 Configuring Risk and Compliance](https://support.simplerisk.com/kb/administrator-guide?hsLang=en#06-configuring-risk-and-compliance)
- [07 Integrations](https://support.simplerisk.com/kb/administrator-guide?hsLang=en#07-integrations)
- [08 The API](https://support.simplerisk.com/kb/administrator-guide?hsLang=en#08-the-api)
- [09 Encryption and Data Security](https://support.simplerisk.com/kb/administrator-guide?hsLang=en#09-encryption-and-data-security)
- [10 Workflows and Automation](https://support.simplerisk.com/kb/administrator-guide?hsLang=en#10-workflows-and-automation)
- [11 Reporting and Auditing](https://support.simplerisk.com/kb/administrator-guide?hsLang=en#11-reporting-and-auditing)
- [12 Operations](https://support.simplerisk.com/kb/administrator-guide?hsLang=en#12-operations)
- [13 Reference](https://support.simplerisk.com/kb/administrator-guide?hsLang=en#13-reference)
- [User Guide](https://support.simplerisk.com/kb/user-guide?hsLang=en#main-content)
- [00 Foundations of GRC](https://support.simplerisk.com/kb/user-guide?hsLang=en#00-foundations-of-grc)
- [01 Risk Management](https://support.simplerisk.com/kb/user-guide?hsLang=en#01-risk-management)
- [02 Compliance Management](https://support.simplerisk.com/kb/user-guide?hsLang=en#02-compliance-management)
- [03 Governance](https://support.simplerisk.com/kb/user-guide?hsLang=en#03-governance)
- [04 Asset and Data Inventory](https://support.simplerisk.com/kb/user-guide?hsLang=en#04-asset-and-data-inventory)
- [05 Threat and Vulnerability Management](https://support.simplerisk.com/kb/user-guide?hsLang=en#05-threat-and-vulnerability-management)
- [06 Assessments](https://support.simplerisk.com/kb/user-guide?hsLang=en#06-assessments)
- [07 Incident Management](https://support.simplerisk.com/kb/user-guide?hsLang=en#07-incident-management)
- [08 Audit and Reporting](https://support.simplerisk.com/kb/user-guide?hsLang=en#08-audit-and-reporting)
- [09 Day-to-Day SimpleRisk](https://support.simplerisk.com/kb/user-guide?hsLang=en#09-day-to-day-simplerisk)
- [10 Continuous Improvement](https://support.simplerisk.com/kb/user-guide?hsLang=en#10-continuous-improvement)
- [SimpleRisk User Guides](https://support.simplerisk.com/kb/simplerisk-user-guides?hsLang=en)
- [Troubleshooting](https://support.simplerisk.com/kb/troubleshooting?hsLang=en)
- [SimpleRisk Hosted](https://support.simplerisk.com/kb/simplerisk-hosted?hsLang=en)
- [How To videos](https://support.simplerisk.com/kb/how-to-videos?hsLang=en)
[](https://www.simplerisk.com)
Copyright © 2026, SimpleRisk, Inc.