> For the complete documentation index, see [llms.txt](https://docs.sonarsource.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.sonarsource.com/sonarqube-server/server-installation/ai-agents/deploying-with-docker-installation.md).

# Deploying with a Docker installation

Run SonarQube Server and the AI agent components together from one Docker Compose bundle. This page is for SonarQube Server 2026.5.

Use this page to run SonarQube Server from the Docker image together with the AI agents. The Docker Compose bundle generator writes one bundle that runs SonarQube Server and the agent components. If SonarQube Server runs from the ZIP file, see [Deploying alongside a ZIP installation](https://docs.sonarsource.com/sonarqube-server/server-installation/ai-agents/deploying-alongside-zip-installation.md).

The [Docker Compose bundle generator](https://github.com/SonarSource/docker-sonarqube/tree/master/agentic-compose-generator) writes the Compose file, the `.env` file, and the egress proxy files. Use those files as the generator writes them. The networks, the egress allowlist, `stop_grace_period`, and `runtime: runsc` are part of the security boundary described in [Installation overview](https://docs.sonarsource.com/sonarqube-server/server-installation/ai-agents/installation-overview.md).

{% hint style="info" %}
Before you begin, read [Before you start](https://docs.sonarsource.com/sonarqube-server/server-installation/ai-agents/before-you-start.md) and complete [Setting up the sandbox runtime](https://docs.sonarsource.com/sonarqube-server/server-installation/ai-agents/sandbox-runtime.md) and [Setting up shared storage](https://docs.sonarsource.com/sonarqube-server/server-installation/ai-agents/shared-storage.md). On a Linux host, register `runsc` before you start the bundle. The bounded overlay that caps a job's disk usage is set when you register `runsc`, see [Setting up the sandbox runtime](https://docs.sonarsource.com/sonarqube-server/server-installation/ai-agents/sandbox-runtime.md#on-docker). On Docker Desktop, the agent runtimes cannot use a sandbox, so use it for evaluation only, see [Setting up the sandbox runtime](https://docs.sonarsource.com/sonarqube-server/server-installation/ai-agents/sandbox-runtime.md#without-sandbox) and [Deploying on Windows](https://docs.sonarsource.com/sonarqube-server/server-installation/ai-agents/deploying-on-windows.md).
{% endhint %}

## Generate the bundle <a href="#generate" id="generate"></a>

You need Docker Engine with Docker Compose v2.23 or later. The command is `docker compose`.

```bash
git clone https://github.com/SonarSource/docker-sonarqube.git
cd docker-sonarqube/agentic-compose-generator
```

The flags are in the [generator README](https://github.com/SonarSource/docker-sonarqube/blob/master/agentic-compose-generator/README.md). Run `python3 generate.py` with those flags. If `python3 --version` is not found, use the `docker run` command in that README (`python:3.13-slim`) instead of `python3 generate.py`.

The generator writes the signing secret into the bundle. Keep the whole bundle directory private. `.env` holds the signing secret, and `docker-compose.yaml` holds the database password.

`--edition enterprise` or `--edition datacenter` makes the bundle run a new SonarQube Server and connect the database, storage, keys, and networks. The generator cannot attach the components to a SonarQube Server that already runs in a container. `--edition none` is for a SonarQube Server installed from the ZIP file, see [Deploying alongside a ZIP installation](https://docs.sonarsource.com/sonarqube-server/server-installation/ai-agents/deploying-alongside-zip-installation.md).

`--tls` modifies the connection between SonarQube Server and the containers. The database connection stays TLS. See [Before you start](https://docs.sonarsource.com/sonarqube-server/server-installation/ai-agents/before-you-start.md#database).

After `generate.py` finishes, the bundle is the directory you passed to `--out`. `docker compose` runs in that directory. The generator also writes the Orchestrator URL, the Vortex analysis URL, and the signing files into the SonarQube Server container.

## Start the components <a href="#starting" id="starting"></a>

The Orchestrator stores job state in the SonarQube Server database and stays unhealthy until SonarQube Server has created the schema.

With `--edition enterprise` or `--edition datacenter`, the bundle runs SonarQube Server. `docker compose up -d` starts it with the other containers. The Orchestrator waits until that SonarQube Server container is healthy. After an update that changes the database schema, SonarQube Server does not migrate the database by itself and stays unhealthy until you do. Open `/setup` in SonarQube Server, or send `POST /api/system/migrate_db`, and the Orchestrator starts after the migration. Patch updates within one release line do not normally change the schema.

```bash
docker compose up -d
docker compose ps
```

### Stopping without losing a job <a href="#stop-grace" id="stop-grace"></a>

The generator sets `stop_grace_period` above each service's drain: 44,430 seconds for the Hunter Agent runtime, 3,630 seconds for the Remediation Agent runtime, 2,580 seconds for the Orchestrator, and 180 seconds for Vortex analysis. The runtime values sit just above each image's graceful-shutdown limit, 44,400 seconds for the Hunter Agent and 3,600 seconds for the Remediation Agent. These are ceilings. An idle stack stops as soon as nothing is in flight.

How those values relate to the job timeouts is in [Installation overview](https://docs.sonarsource.com/sonarqube-server/server-installation/ai-agents/installation-overview.md#timeouts).

{% hint style="danger" %}
Removing `stop_grace_period` makes `docker compose down`, `stop`, and `restart` send `SIGTERM` and kill the container 10 seconds later, in the middle of the drain. A running job is lost with its results unwritten. The runtime is killed before it can report anything, so the Orchestrator fails the job only when its own watcher timeout expires, up to 12 hours and 20 minutes later for the Hunter Agent (44,400 seconds).
{% endhint %}

## Network isolation <a href="#network-isolation" id="network-isolation"></a>

The generator places each runtime on its own internal network, shared with the Orchestrator for job dispatch and with the egress proxy for the route off the host. The boundaries are in [Installation overview](https://docs.sonarsource.com/sonarqube-server/server-installation/ai-agents/installation-overview.md#network-boundaries). Leave the generated networks as they are.

## Confirm the deployment <a href="#confirming" id="confirming"></a>

Go to **Administration** > **System**. The Agent Orchestrator, Vortex analysis, and each agent runtime the Orchestrator can see report healthy. See [Verifying the deployment](https://docs.sonarsource.com/sonarqube-server/server-installation/ai-agents/verifying-the-deployment.md).

## Advanced configuration <a href="#advanced" id="advanced"></a>

Every other `generate.py` option is in the [generator README](https://github.com/SonarSource/docker-sonarqube/blob/master/agentic-compose-generator/README.md). Generate again to change them. To adjust a generated service without editing the generated file, add a `docker-compose.override.yaml` beside it.

When SonarQube Server runs on another machine, both sides need a name that resolves from where the process runs, and a network path to the published Orchestrator and Vortex analysis ports. With `--tls off`, a bundle that runs SonarQube Server also publishes port 9000. For the ZIP case, the addresses are on [Deploying alongside a ZIP installation](https://docs.sonarsource.com/sonarqube-server/server-installation/ai-agents/deploying-alongside-zip-installation.md).

For storage backends, see [Setting up shared storage](https://docs.sonarsource.com/sonarqube-server/server-installation/ai-agents/shared-storage.md). For a private certificate authority, see [Installation overview](https://docs.sonarsource.com/sonarqube-server/server-installation/ai-agents/installation-overview.md#private-certificate-authority).

## Temporary storage <a href="#temporary-storage" id="temporary-storage"></a>

The Compose generator mounts a private disk volume at the Orchestrator's `/tmp` instead of memory-backed temporary storage. A bundle generated with an earlier version of the generator still uses memory-backed storage. To switch it to the disk volume, generate the bundle again into the same output directory, keeping the same `--project-name` and omitting `--rotate-secrets`: the generator then keeps the signing secret from the existing `.env`, and Docker Compose reuses the existing data volumes. See [Updating the agentic components](https://docs.sonarsource.com/sonarqube-server/server-update-and-maintenance/update/updating-agentic-components.md#docker-compose).

Provision free disk space on the filesystem backing Docker's named volumes, see [Capacity planning](https://docs.sonarsource.com/sonarqube-server/server-installation/ai-agents/capacity-planning.md#orchestrator-temporary-storage).

## Next step <a href="#next-step" id="next-step"></a>

Confirm the deployment works, see [Verifying the deployment](https://docs.sonarsource.com/sonarqube-server/server-installation/ai-agents/verifying-the-deployment.md).

## Related pages <a href="#related-pages" id="related-pages"></a>

* [Installation overview](https://docs.sonarsource.com/sonarqube-server/server-installation/ai-agents/installation-overview.md)
* [Deploying alongside a ZIP installation](https://docs.sonarsource.com/sonarqube-server/server-installation/ai-agents/deploying-alongside-zip-installation.md)
* [Configuration reference](https://docs.sonarsource.com/sonarqube-server/server-installation/ai-agents/configuration-reference.md)
* [Verifying the deployment](https://docs.sonarsource.com/sonarqube-server/server-installation/ai-agents/verifying-the-deployment.md)
* [Capacity planning](https://docs.sonarsource.com/sonarqube-server/server-installation/ai-agents/capacity-planning.md)
* [Troubleshooting](https://docs.sonarsource.com/sonarqube-server/server-installation/ai-agents/troubleshooting.md)


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.sonarsource.com/sonarqube-server/server-installation/ai-agents/deploying-with-docker-installation.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.
