From e1904743e1dddc123dd48aa5cda225abbffdf60b Mon Sep 17 00:00:00 2001 From: Cody Maffucci <46459665+Maffooch@users.noreply.github.com> Date: Fri, 25 Sep 2026 10:41:18 -0600 Subject: [PATCH 1/4] docs(onprem): show how to run the compose database SQL and link DB tuning Tell readers to open psql as the postgres superuser before the CREATE statements, and point to the Hardware Sizing database tuning section at the database step. Co-Authored-By: Claude Opus 5.5 --- .../docker_compose/installing_on_docker_compose.md | 10 +++++++++- 1 file changed, 9 insertions(+), 1 deletion(-) diff --git a/docs/content/get_started/pro/onprem/docker_compose/installing_on_docker_compose.md b/docs/content/get_started/pro/onprem/docker_compose/installing_on_docker_compose.md index 60a3879557..26545beacb 100644 --- a/docs/content/get_started/pro/onprem/docker_compose/installing_on_docker_compose.md +++ b/docs/content/get_started/pro/onprem/docker_compose/installing_on_docker_compose.md @@ -44,7 +44,13 @@ apt update apt -y install postgresql postgresql-contrib ``` -Create the databases and the application user. DefectDojo uses a second database for its orchestration service, so create both: +Create the databases and the application user. DefectDojo uses a second database for its orchestration service, so create both. Open a `psql` session as the `postgres` superuser: + +```bash +sudo -u postgres psql +``` + +Then run: ```sql CREATE USER dojodbusr; @@ -79,6 +85,8 @@ Restart for both changes to take effect: systemctl restart postgresql ``` +PostgreSQL's stock settings are sized for a small machine. Before you load real data, raise the memory and connection settings to match the host, following [Tuning the database](/get_started/pro/onprem/hardware_sizing/#tuning-the-database) on the Hardware Sizing page. + ## Prepare the application host ### Outbound connectivity From 121e4448805a585d90ed70af49e37857716cbabc Mon Sep 17 00:00:00 2001 From: Cody Maffucci <46459665+Maffooch@users.noreply.github.com> Date: Fri, 25 Sep 2026 10:41:49 -0600 Subject: [PATCH 2/4] docs(onprem): correct the compose install wizard steps - Drop the Deploy Version prompt from the table. The wizard only shows it in developer mode; the deployment files follow the DefectDojo version. - Say that the version defaults to latest and recommend pinning a release from the Pro changelog. - Add an archive integrity check against the release's checksums.txt. - Show exporting DOJO_CLI_KEY and running first-install with sudo -E. - Point to change-password if the printed admin password does not work. Co-Authored-By: Claude Opus 5.5 --- .../installing_on_docker_compose.md | 32 +++++++++++++------ 1 file changed, 23 insertions(+), 9 deletions(-) diff --git a/docs/content/get_started/pro/onprem/docker_compose/installing_on_docker_compose.md b/docs/content/get_started/pro/onprem/docker_compose/installing_on_docker_compose.md index 26545beacb..f30b8d8d74 100644 --- a/docs/content/get_started/pro/onprem/docker_compose/installing_on_docker_compose.md +++ b/docs/content/get_started/pro/onprem/docker_compose/installing_on_docker_compose.md @@ -130,25 +130,36 @@ docker info ## Install DefectDojo -Copy the CLI archive and your license file to the application host, into the same directory, and extract the CLI: +Copy the CLI archive and your license file to the application host, into the same directory. + +Check the archive before you extract it. Each CLI release comes with a `checksums.txt` file listing the SHA-256 of every archive. With both files in the same directory: + +```bash +sha256sum --check --ignore-missing checksums.txt +``` + +The archive's line should end in `OK`. If you received the archive without `checksums.txt`, ask [support@defectdojo.com](mailto:support@defectdojo.com) for the expected checksum and compare it with the output of `sha256sum dojo-compose-cli_*.tar.gz`. + +Then extract the CLI: ```bash tar -xzvf dojo-compose-cli_*.tar.gz ``` -Then run the installer from that directory: +Choose a `DOJO_CLI_KEY` before you start. It is the encryption key for the configuration the CLI stores on disk, and every later command needs it, so store it somewhere safe. Export it in your shell and run the installer with `sudo -E`, which passes the variable through `sudo`: ```bash -sudo ./dojo-compose-cli first-install +export DOJO_CLI_KEY="" +sudo -E ./dojo-compose-cli first-install ``` +If the variable is not set, the installer asks for the key instead. + The wizard prompts for the following. | Prompt | What it is | | --- | --- | -| `DOJO_CLI_KEY` | An encryption key for configuration the CLI stores on disk. Choose it now and keep it, since later commands need it. | -| DefectDojo Version | The release to install. | -| Deploy Version | The deployment files to use. Set it to the same value as the version. | +| DefectDojo Version | The release to install. The default is `latest`. Enter a specific release from the [DefectDojo Pro changelog](/releases/pro/changelog/) instead, so that you know exactly what you are running and upgrade on your own schedule. The deployment files follow this version automatically. | | Deploy Type | `separate-db` for a database on its own host, or `containerized-db` to run PostgreSQL in a container. | | Database Connection Type | Choose Single Line and supply the whole connection string. | | Database URL | `postgres://:@:5432/dojodb`. It must begin with `postgres://` rather than `postgresql://`. | @@ -157,7 +168,7 @@ The wizard prompts for the following. Two things worth knowing at the prompts. Supply the database connection as a single line rather than value by value, since the per-value path does not currently ask for the username. And if the password contains characters like `!`, `@`, or `#`, URL encode them in the connection string. -The installer then pulls the images, starts the stack, creates a systemd service, and prints the generated admin credentials. **Save those credentials before you close the terminal. They are not shown again.** +The installer then pulls the images, starts the stack, creates a systemd service, and prints the generated admin credentials. **Save those credentials before you close the terminal. They are not shown again.** If the printed password does not let you log in, or you lose it, set a new one with `sudo -E dojo-compose-cli app change-password` (see [Reset the admin password](#reset-the-admin-password)). Once it finishes, DefectDojo is available at the site URL you gave it. @@ -238,7 +249,7 @@ If the file is missing or empty the container logs `No CA bundle found ...` inst If you lose the generated password, reset it from the application host. DefectDojo has to be running: ```bash -dojo-compose-cli app change-password +sudo -E dojo-compose-cli app change-password ``` ## Upgrading @@ -268,12 +279,15 @@ Upgrades are covered on their own page: see the [DefectDojo Pro Upgrade Guide (D | `register` | Authenticate to the container registry | | `update-binary` | Update the CLI itself | -Most commands need `DOJO_CLI_KEY`, since the configuration is encrypted at rest. Export it for your session, or pass it through `sudo` with `sudo -E`: +Most commands need `DOJO_CLI_KEY`, since the configuration is encrypted at rest. Export it for your session, then pass it through `sudo` with `sudo -E`: ```bash export DOJO_CLI_KEY="your-key" +sudo -E dojo-compose-cli config print ``` +Without it, the CLI asks for the key each time. + ## Questions or support If an install does not complete, `dojo-compose-cli diagnostics collect` gathers a report bundle that is the fastest way for us to help. Send it, along with what you were running when it failed, to [support@defectdojo.com](mailto:support@defectdojo.com). From ae438f5cd1da0a3a73b35833f1e8799fc2308e7c Mon Sep 17 00:00:00 2001 From: Cody Maffucci <46459665+Maffooch@users.noreply.github.com> Date: Fri, 25 Sep 2026 10:42:25 -0600 Subject: [PATCH 3/4] docs(onprem): fix the compose TLS certificate replacement steps The shipped certificate is a placeholder for another hostname, not a usable self-signed certificate, so say it must be replaced. Give the ownership and modes nginx needs (it runs as UID 1002 with group 0, so a dojosrv:dojosrv 0640 key stops it from starting) and add a check that nginx is up after the restart. Co-Authored-By: Claude Opus 5.5 --- .../installing_on_docker_compose.md | 26 ++++++++++++++++--- 1 file changed, 22 insertions(+), 4 deletions(-) diff --git a/docs/content/get_started/pro/onprem/docker_compose/installing_on_docker_compose.md b/docs/content/get_started/pro/onprem/docker_compose/installing_on_docker_compose.md index f30b8d8d74..3c8d6565f4 100644 --- a/docs/content/get_started/pro/onprem/docker_compose/installing_on_docker_compose.md +++ b/docs/content/get_started/pro/onprem/docker_compose/installing_on_docker_compose.md @@ -202,12 +202,30 @@ Use `app restart` after changing any configuration, since it recreates the conta ## Replace the TLS certificate -The installation ships a self-signed certificate so that the site works immediately. Replace it with your own by overwriting two files, keeping the names exactly as they are: +The installation ships a placeholder certificate so that nginx can start. It is issued for a different hostname than yours, so browsers will reject it until you replace it with a certificate for your own hostname. Do this before users start logging in. -- `/opt/dojo/certs/dojo.crt` -- `/opt/dojo/certs/dojo.key` +Replace it by overwriting two files, keeping the names exactly as they are: -Then `dojo-compose-cli app restart` to pick them up. +- `/opt/dojo/certs/dojo.crt`, your certificate followed by any intermediate certificates, in PEM format +- `/opt/dojo/certs/dojo.key`, the matching private key, in PEM format and without a passphrase + +The nginx container runs as user ID 1002 with group 0 (`root`), not as `dojosrv`, so it reads the key through its group. Give the key group `root` and make it group-readable. A key owned by `dojosrv:dojosrv` with mode `0640` is unreadable to nginx, and nginx will not start: + +```bash +sudo chown dojosrv:root /opt/dojo/certs/dojo.crt /opt/dojo/certs/dojo.key +sudo chmod 0644 /opt/dojo/certs/dojo.crt +sudo chmod 0640 /opt/dojo/certs/dojo.key +``` + +Then restart to pick them up, and confirm nginx came back: + +```bash +sudo -E dojo-compose-cli app restart +docker ps --filter name=nginx +curl -sSI https:/// +``` + +`docker ps` should show the nginx container as `Up` rather than `Restarting`, and `curl` should complete the TLS handshake without a certificate error. If nginx is restarting, `docker logs nginx` usually names the file it could not read. ## Trusting an internal or private CA From 0f8c10c835df5a266b0249275023be35b3957e99 Mon Sep 17 00:00:00 2001 From: Cody Maffucci <46459665+Maffooch@users.noreply.github.com> Date: Fri, 25 Sep 2026 10:43:22 -0600 Subject: [PATCH 4/4] docs(onprem): add inbound firewall guidance and a systemd restart-loop note for compose - Say that users need only 80 and 443, and that the stack also publishes 9142 (MCP server) and 9871 (orchestration) on all interfaces. Because Docker's rules for published ports bypass ufw, restrict them at the network firewall or in the DOCKER-USER chain. - Add a troubleshooting entry for the unit repeatedly failing with "already running": disable the unit rather than stopping it, since its ExecStop runs app stop and removes the containers. Co-Authored-By: Claude Opus 5.5 --- .../installing_on_docker_compose.md | 20 +++++++++++++++++++ 1 file changed, 20 insertions(+) diff --git a/docs/content/get_started/pro/onprem/docker_compose/installing_on_docker_compose.md b/docs/content/get_started/pro/onprem/docker_compose/installing_on_docker_compose.md index 3c8d6565f4..391a8dafa3 100644 --- a/docs/content/get_started/pro/onprem/docker_compose/installing_on_docker_compose.md +++ b/docs/content/get_started/pro/onprem/docker_compose/installing_on_docker_compose.md @@ -106,6 +106,14 @@ Allowlist by hostname rather than by address. The registry sits behind a content If the host reaches the internet through an outbound proxy, see [Running DefectDojo Behind a Forward HTTPS Proxy](/get_started/pro/onprem/forward_proxy/). If it has no route to the internet at all, follow the air-gapped installation procedure in this section instead. +### Inbound access + +Users only need to reach the application host on ports 80 and 443, which nginx serves. Allow those from your users' networks and nothing else. + +Plan for two more ports that the stack publishes on every interface of the host: `9142` for the MCP server and `9871` for the orchestration service. Unless you have a reason to reach them from elsewhere, block them from outside the host. + +Do this at your network firewall or security group, or in the `DOCKER-USER` iptables chain on the host. A host firewall such as `ufw` is not enough on its own: Docker writes its own rules for published ports, and those rules take effect ahead of `ufw`, so a `ufw deny` does not close a port Docker has published. See Docker's [packet filtering and firewalls](https://docs.docker.com/engine/network/packet-filtering-firewalls/) documentation for how to add rules to `DOCKER-USER`. + ### Confirm the database is reachable Install the client tools and connect before going any further. A database problem is much easier to diagnose now than in the middle of the install: @@ -306,6 +314,18 @@ sudo -E dojo-compose-cli config print Without it, the CLI asks for the key each time. +## Troubleshooting + +### The systemd service keeps restarting + +If `journalctl -u defectdojo-compose` shows the service failing with a message that DefectDojo is already running, over and over, the unit is trying to start a stack that is already up. The application itself keeps running. To stop the repeated restarts, disable the unit: + +```bash +sudo systemctl disable defectdojo-compose +``` + +Do not run `systemctl stop defectdojo-compose` while the unit is active. Its stop action runs `app stop`, which takes the containers down. With the unit disabled, the stack still comes back after a reboot, because Docker restarts the containers on its own under their restart policy. + ## Questions or support If an install does not complete, `dojo-compose-cli diagnostics collect` gathers a report bundle that is the fastest way for us to help. Send it, along with what you were running when it failed, to [support@defectdojo.com](mailto:support@defectdojo.com).