Docker, Containers, Persistent Storage, and Production Deployment: Core Concepts and Mental Model

1. Current container baseline: packaging is not architecture

This chapter uses SonarQube Community Build 26.9.0.129388 and the official image sonarqube:26.9.0.129388-community. Docker Hub currently maps the Community Build tag to multi-platform index digest sha256:62930c7f510534bb2bf551ca69ad3ee6f8e12b4116d394597c64cefccbb3313b. A tag is a human-readable selection; a digest is the stronger content identity. Record both.

Containers package SonarQube binaries and its Java runtime, but the instance still depends on a supported database, embedded-search host prerequisites, writable paths, a network path to the database, secure configuration, resource headroom, and a deliberate upgrade/recovery plan.

2. Mental model: six boundaries around one SonarQube container

Start from ownership rather than from a docker run command. The container is replaceable compute. Durable product state is not “inside Docker” as one undifferentiated thing.

flowchart TD
I[Pinned SonarQube image
tag + digest] --> C[SonarQube container]
CFG[Runtime configuration
JDBC + web + JVM options] --> C
SEC[Secret source
DB password / JWT / tokens] --> C
HOST[Container host
CPU RAM disk kernel limits] --> C
C --> V[Named volumes
data / extensions / logs]
C --> TMP[Writable temp
ephemeral scratch]
C --> N[Private Docker network]
N --> DB[(PostgreSQL
durable application state)]
C --> WEB[Web :9000]
C --> CE[Compute Engine]
C --> ES[Embedded search]
WEB --> DB
CE --> DB
ES --> V

The image supplies versioned application bits. Runtime configuration selects database and server behavior. Named volumes preserve selected filesystem state across container replacement. The database is the durable source of SonarQube application state. Embedded search still inherits host-level constraints. The network resolves other containers by service/container name. Each boundary fails differently.

3. Persistence model: database first, then supporting volumes

Current SonarSource Docker preparation guidance explicitly creates named volumes for data, logs, and extensions, and warns against casually deleting database volumes. The image also declares its temp path as a volume, but temp is writable scratch rather than the durable source of project history.

4. Image identity: tag, platform manifest, and runtime user

Read-only image inspection should happen before starting the application:

docker pull sonarqube:26.9.0.129388-community
docker image inspect sonarqube:26.9.0.129388-community --format '{{json .RepoDigests}}'
docker image inspect sonarqube:26.9.0.129388-community --format 'user={{.Config.User}} ports={{json .Config.ExposedPorts}} volumes={{json .Config.Volumes}}'

The current official image runs as the non-root sonarqube user (UID 1000 in the published image build), exposes TCP 9000, and defines SonarQube paths under /opt/sonarqube. Those facts matter when you choose bind mounts or security policies: a host directory writable only by root can make the container fail even though the image itself is valid.

5. Runtime configuration and secrets are different concerns

For Docker installations, SonarSource prefers system properties as environment variables. The JDBC boundary uses SONAR_JDBC_URL, SONAR_JDBC_USERNAME, and SONAR_JDBC_PASSWORD. That does not mean a production password belongs in a Dockerfile, Git repository, copied shell history, or screenshot.

# Example names only; never commit a real production value.
SONAR_JDBC_URL=jdbc:postgresql://db:5432/sonar
SONAR_JDBC_USERNAME=sonar
SONAR_JDBC_PASSWORD=FAKE_LOCAL_LAB_PASSWORD

A Dockerfile is build-time provenance and should remain reusable. Environment injection is runtime configuration, but Docker daemon administrators can inspect container configuration, so production secret handling must use the organization’s supported secret-management/orchestration boundary and least-privilege daemon access. This chapter does not invent an unsupported *_FILE convention.

6. Container DNS: why localhost is usually the wrong database host

Inside the SonarQube container, localhost means that same SonarQube container. A PostgreSQL process in a different container is reached through the private network using its container/service DNS name, for example db.

Correct: jdbc:postgresql://db:5432/sonar
Wrong for a separate DB container: jdbc:postgresql://localhost:5432/sonar

Publishing PostgreSQL port 5432 to the host is unnecessary for the mandatory lab. Only SonarQube’s loopback-bound web port needs host exposure. Keeping the database private reduces accidental reachability and makes the trust boundary visible.

7. Containers inherit host constraints

Embedded Elasticsearch still uses the Linux kernel underneath the container runtime. On a native Linux Docker host, current SonarQube guidance requires at least vm.max_map_count=524288, fs.file-max=131072, ulimit -n 131072, and ulimit -u 8192. Elasticsearch 8.x also needs read/write access to /tmp.

# Read-only Linux-host preflight
sysctl vm.max_map_count
sysctl fs.file-max
ulimit -n
ulimit -u
docker info --format 'CPUs={{{{.NCPU}}}} Memory={{{{.MemTotal}}}}'

With Docker Desktop on Windows/macOS, a managed Linux VM owns these kernel details. Do not “fix” a bootstrap failure by disabling Elasticsearch checks. Verify the current platform-specific runtime guidance or use a suitable Linux VM/host for a production-shaped exercise.

8. Read-only container inspection before any redeploy

docker ps --filter name=sq-lab --no-trunc
docker inspect sq-lab --format 'image={{{{.Image}}}} user={{{{.Config.User}}}}'
docker inspect sq-lab --format '{{{{json .Mounts}}}}'
docker inspect sq-lab --format '{{{{json .NetworkSettings.Networks}}}}'
docker logs --tail 120 sq-lab
docker stats --no-stream sq-lab

These commands answer different questions: which image object is running, which user the image requests, which mounts survived container creation, which networks/DNS scope the container joined, what first-failure evidence exists, and whether the container host is resource-starved.

9. Foundation mistakes to eliminate early

• “The container is the backup.” It is replaceable compute, not a database recovery artifact.
• “Named volumes make every file durable.” Only mounted paths persist; external database state has its own volume/backup lifecycle.
• “localhost means my Docker host or sibling DB.” Inside a container it means that container.
• “latest is convenient and therefore safe.” It hides change identity and can make rollback analysis ambiguous.
• “Docker solved the Elasticsearch host limits.” Containers still share/inherit host kernel constraints.
• “Putting a password in ENV makes it secret.” Runtime environment is configuration; production secret controls need a deliberate trust boundary.

10. Why this matters in DevOps

A production deployment must be reproducible enough that an operator can answer: which image digest ran, which database it used, which volumes were mounted, which configuration source supplied JDBC settings, which host constraints were satisfied, and which logs prove the first healthy/failed start. That is the container equivalent of the evidence chain introduced in Chapters 01–03.

Knowledge check

Official references and version notes

• SonarQube Community Build downloads — current Community Build release identity.
• Official SonarQube Docker image tags — current official image tags and digests.
• Prepare the Docker installation — pre-installation checks and named-volume guidance.
• Set up and start your container — docker run/Compose, JDBC environment variables, ports, and volume warnings.
• Linux pre-installation — embedded-search host limits and writable /tmp requirements.
• Configuration methods — preferred Docker environment-variable configuration model.
• System properties — current JDBC and web-server property names.
• Installing database — supported database versions and H2 non-production boundary.
• Updating Community Build — container recreation and persistent-state upgrade guidance.
• SonarQube official image overview — official image usage, host prerequisites, port and edition tags.