> 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/reference-architectures/up-to-10m-loc.md).

# Up to 10 M LOC

Architecture of a single-node SonarQube Server Enterprise edition instance for up to 10 million lines of code. This page is for SonarQube Server 2026.5.

## Overview <a href="#overview" id="overview"></a>

This reference architecture covers the following components:

* A dedicated virtual machine with SonarQube Server Enterprise edition installed and an nginx HTTPS proxy.
* PostgreSQL database on a dedicated host.
* Analysis integrated with GitHub Actions.
* Authentication through GitHub.com.
* Monitoring with Prometheus.
* Outbound email notifications using an SMTP relay.
* Optionally, the agentic features running as additional containers with shared storage that you provide.

The following diagram shows these components and the connections between them. The optional agentic feature components are outlined in blue, and sandboxed containers have a dashed border.

```mermaid
%%{init: {'theme': 'base', 'themeVariables': {'primaryColor': '#F1F6FC', 'primaryBorderColor': '#126ED3', 'primaryTextColor': '#0A0A0A', 'lineColor': '#126ED3', 'secondaryColor': '#F4F6F8', 'tertiaryColor': '#F4F6F8', 'clusterBkg': '#F4F6F8', 'clusterBorder': '#D4D4D4', 'edgeLabelBackground': '#FFFFFF'}}}%%
flowchart LR
    subgraph devops["DevOps/CI platform: GitHub.com"]
        REPO["Repositories"]
        APP["SonarQube GitHub App"]
        GHA["GitHub Actions runner<br/>GitHub-hosted or self-hosted"]
    end

    subgraph internal["Internal network"]
        BROWSER["Browser"]
        IDE["SonarQube for IDE"]
        CLI["SonarQube CLI"]
        MCP["SonarQube MCP Server"]
        PROM["Monitoring<br/>Prometheus"]
        SMTP["SMTP relay"]
    end

    subgraph subnet["SonarQube subnet"]
        subgraph host["SonarQube Server host"]
            PROXY["HTTPS proxy<br/>nginx"]
            SQ["SonarQube Server"]
        end
        subgraph ai["Agentic features, optional"]
            AO["Agent Orchestrator"]
            RT["Agent runtime"]
            VX["Sonar Vortex"]
        end
        DB[("Database")]
        STORE[("Shared storage<br/>file share or S3")]
    end

    LLM["LLM provider"]

    GHA -->|"Analysis reports"| PROXY
    BROWSER -->|"Web UI access"| PROXY
    IDE -->|"Connected mode"| PROXY
    CLI -->|"Web API access"| PROXY
    MCP -->|"Web API access"| PROXY
    PROM -->|"Web API access"| PROXY
    PROXY --> SQ
    SQ -->|"Pull request reports"| APP
    SQ -->|"Authentication, permission sync"| APP
    SQ --> DB
    SQ -->|"Email notifications"| SMTP
    SQ -->|"Trigger job"| AO
    SQ <-->|"Analyzer context"| STORE
    AO -->|"Job state"| DB
    AO -->|"Start job"| RT
    AO -->|"Clone code, open pull requests"| REPO
    AO <-->|"Stage code, read results"| STORE
    RT <--> STORE
    RT -->|"Prompts"| LLM
    RT -->|"Verify fixes"| VX
    VX <--> STORE

    classDef neutral fill:#FFFFFF,stroke:#D4D4D4,color:#0A0A0A
    classDef external fill:#F4F6F8,stroke:#D4D4D4,color:#0A0A0A
    classDef subject fill:#FFFFFF,stroke:#126ED3,color:#0A0A0A
    classDef sandbox fill:#FFFFFF,stroke:#126ED3,color:#0A0A0A,stroke-dasharray: 5 5
    class PROXY,SQ,DB neutral
    class REPO,APP,GHA,BROWSER,IDE,CLI,MCP,PROM,SMTP,LLM external
    class AO,VX,STORE subject
    class RT sandbox
    style devops fill:#F4F6F8,stroke:#D4D4D4
    style internal fill:#F4F6F8,stroke:#D4D4D4
    style subnet fill:#F4F6F8,stroke:#D4D4D4
    style host fill:#FFFFFF,stroke:#D4D4D4
    style ai fill:#F1F6FC,stroke:#126ED3
```

This architecture favors the use of open-source components when available. These may be substituted with other similarly capable components, and it is recommended that organizations use components that they are comfortable supporting.

## SonarQube Server Host <a href="#sonarqube-host" id="sonarqube-host"></a>

The dedicated SonarQube Server Host will have the SonarQube Server software installed as well as nginx acting as an HTTPS proxy.

<details>

<summary>Host specification</summary>

The VM configuration is the requirement. The cloud instance types are examples with the same resources.

* **VM configuration**:
  * 2 vCPU
  * 8 GB RAM
  * 50GB SSD Local Storage
* **AWS EC2**: m7i.large
* **Azure VM**: Standard\_D2s\_v5
* **GCE**: n2-standard-2

</details>

<details>

<summary>Networking</summary>

By source/destination:

* **SonarQube Server host**:
  * **Direction**: Outbound
  * **Port**: 5432
  * **Purpose**: Database
* **SonarQube Server host**:
  * **Direction**: Outbound
  * **Port** (Protocol): 25 (SMTP)
  * **Purpose**: Email notifications
* **Internal network (user desktops):**
  * **Direction**: Inbound
  * **Port (Protocol):** 443 (HTTPS)
  * **Purpose:** Inbound web and API traffic
* **CI platform (GitHub Runners):**
  * **Direction**: Inbound
  * **Port (Protocol):** 443 (HTTPS)
  * **Purpose:** Analysis reports
* **DevOps platform (GitHub.com):**
  * **Direction**: Inbound
  * **Port (Protocol):** 443 (HTTPS)
  * **Purpose:** Pull Request reports

</details>

<details>

<summary>Software</summary>

* OS - Ubuntu Server (or other Linux distribution)
* OpenJDK 21 or 25
* SonarQube Server Enterprise edition
  * Two Compute Engine workers, one per vCPU (see [Server host requirements](https://docs.sonarsource.com/sonarqube-server/server-installation/server-host-requirements.md#compute-engine-workers) and [Improving performance](https://docs.sonarsource.com/sonarqube-server/server-update-and-maintenance/maintenance/improving-performance.md))
* nginx
  * Configured as a reverse proxy between incoming traffic and SonarQube Server port 9000.
  * Secured with SSL. Use of self-signed SSL certificates will require installation of the certificate on all CI build agents, and developer desktops using SonarQube for IDE.
  * May be substituted with other reverse proxy (ex. haproxy) or a solution from a cloud provider, such as an AWS Application Load Balancer (ALB).

</details>

## Database <a href="#database" id="database"></a>

This architecture utilizes a dedicated PostgreSQL database installed on a separate host.

<details>

<summary>Host specification</summary>

The VM configuration is the minimum requirement. The cloud instance types are examples. Where a provider has no production instance type with exactly these resources, the example is the smallest one that meets them.

* **VM Configuration:**
  * 2 vCPU
  * 2 GB RAM
  * 30 GB table space
* **AWS RDS:**
  * db.m7g.large or db.m7i.large (8 GB RAM)
* **Azure Database for PostgreSQL flexible server:**
  * Standard\_D2ds\_v5 (General Purpose, 8 GB RAM)
* **Google Cloud SQL:**
  * db-custom-2-3840 (3.75 GB RAM, the minimum for 2 vCPU)

The load tests used the burstable class db.t4g.small. At the heaviest tested rate, it used CPU credits faster than it earned them. Under sustained load, a burstable class runs out of credits, and on AWS the extra CPU time is billed as an extra charge. Use a fixed-performance class.

{% hint style="info" %}
If you use the Enterprise edition with the Advanced Security product, allocate 30% more table space.
{% endhint %}

</details>

Database requirements can vary widely based on the usage patterns of each SonarQube Server installation. Therefore, it is important to monitor and adjust database resources as needed.

PostgreSQL may be substituted with other supported database platforms. The sizing on this page was tested with PostgreSQL only.

## DevOps/CI platform <a href="#devops-ci-platform" id="devops-ci-platform"></a>

Automated analysis of source code is enabled through the installation of the various SonarScanners into continuous integration pipelines. When using GitHub Actions, scanners are initiated through the repository’s workflow YAML file(s).

Upon analysis completion, SonarQube Server submits reports back to pull requests to integrate with code review processes. This functionality is enabled in GitHub.com using a GitHub App.

GitHub.com may be substituted with other supported DevOps and/or CI platforms without changes to other components in this architecture.

## Authentication <a href="#authentication" id="authentication"></a>

It is recommended that authentication and authorization be handled through an external identity provider. The architecture utilizes the GitHub App to authorize users and synchronize access to SonarQube Server projects.

Other external identity providers such as SAML may be substituted. Features such as group and permission synchronization are not available for all authentication methods.

## Monitoring <a href="#monitoring" id="monitoring"></a>

SonarQube Server exposes endpoints that are easy to monitor using Prometheus or other monitoring solutions. In addition to the overall system health of both the SonarQube Server host and database, it is recommended to monitor SonarQube Server’s Compute Engine performance statistics to ensure incoming analyses are being promptly processed.

## Email notifications <a href="#notifications" id="notifications"></a>

Users can be notified of new issues and events via email. SonarQube Server will deliver these notifications through an SMTP mail relay. The volume of emails is low, dependent on the number of users subscribed, and a dedicated SMTP server is typically not required.

## Agentic features (optional) <a href="#agentic-features" id="agentic-features"></a>

The agentic features (Hunter Agent, Remediation Agent, and Sonar Vortex) run as additional containers alongside this architecture. They require the Enterprise or Data Center edition, and each agent requires a separate subscription.

These components add their own hosts and storage rather than changing the SonarQube Server host specification in this architecture, so you can add them to an existing installation without redeploying SonarQube Server. The database grows slightly, because the Agent Orchestrator tracks job state there.

The agentic feature components run as containers alongside SonarQube Server, and they exchange data through shared storage that you provision. For the components and their resource requirements, see [Agentic features architecture](https://docs.sonarsource.com/sonarqube-server/server-installation/reference-architectures/agentic-features-architecture.md). For the deployment procedures, see [Deploying AI agents](https://docs.sonarsource.com/sonarqube-server/server-installation/ai-agents.md).

## Resiliency <a href="#resiliency" id="resiliency"></a>

As a single-host installation, this architecture relies on robust monitoring, automated backups of the database, and a rapid recovery process to maximize resiliency. If high availability is critical, SonarQube Server Data Center edition is recommended.

## Scalability <a href="#scalability" id="scalability"></a>

This architecture supports up to 10 million lines of code. For larger instances, see [Up to 50 M LOC](https://docs.sonarsource.com/sonarqube-server/server-installation/reference-architectures/up-to-50m-loc.md).

It’s sized for a heavy workload, the rate of analyses per hour typical of a busy instance with up to 10 million lines of code. The number of analyses per hour and the average size of the analyzed projects matter more than the total lines of code. If analyses often pile up in the queue of background tasks, the instance is too small for its workload. See [Server host requirements](https://docs.sonarsource.com/sonarqube-server/server-installation/server-host-requirements.md#sizing-for-your-workload) and [Improving performance](https://docs.sonarsource.com/sonarqube-server/server-update-and-maintenance/maintenance/improving-performance.md).

### Use cases that may require additional capacity <a href="#additional-capacity" id="additional-capacity"></a>

<details>

<summary>High-frequency analysis</summary>

The number of Compute Engine workers limits how many analyses the instance processes. This architecture runs two workers, one per vCPU. If analyses often wait in the queue, add vCPUs to the host and one worker per added vCPU. Running more workers than vCPUs did not increase throughput in testing. Monitor the Compute Engine process to check that your installation keeps up with demand. See [SonarQube Server instance](https://docs.sonarsource.com/sonarqube-server/server-update-and-maintenance/monitoring/instance.md).

</details>

<details>

<summary>Large repositories</summary>

An analysis of a very large project occupies a Compute Engine worker for the whole time it takes to process. When several of them are processed at the same time, other analyses wait in the queue. If your instance holds many very large projects, plan for more vCPUs and Compute Engine workers.

</details>

<details>

<summary>Heavy API integration</summary>

SonarQube Server exposes a REST-based API for reporting and automation of administration tasks. This architecture assumes occasional use of this API. Heavy use of this API may require the allocation of additional memory and CPU resources to SonarQube Server’s Web process.

</details>

<details>

<summary>Third-party plugins</summary>

This architecture assumes that no third-party plugins are in use. As these extensions are developed by open-source developers, their impact on the performance of a SonarQube Server instance varies based on the function being performed and the quality of the implementation. It is recommended that the use of third-party plugins is carefully considered and monitored for performance throughout the life of your SonarQube Server implementation.

</details>

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

* [Server host requirements](https://docs.sonarsource.com/sonarqube-server/server-installation/server-host-requirements.md)
* [Installing database](https://docs.sonarsource.com/sonarqube-server/server-installation/installing-the-database.md#database-requirements)
* [Server installation and setup](https://docs.sonarsource.com/sonarqube-server/server-installation.md)
* [Reverse proxy and network security](https://docs.sonarsource.com/sonarqube-server/server-installation/network-security/securing-behind-proxy.md)
* [GitHub](https://docs.sonarsource.com/sonarqube-server/discovering/devops-platforms/github.md)
* [Setting up monitoring](https://docs.sonarsource.com/sonarqube-server/server-installation/on-kubernetes-or-openshift/set-up-monitoring.md)(on Kubernetes)
* [Setting up email notifications](https://docs.sonarsource.com/sonarqube-server/instance-administration/system-functions/email-notifications.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/reference-architectures/up-to-10m-loc.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.
