Docker from the basics to practice

Docker packs an application and everything it needs to run (OS libraries, a runtime such as Java, configuration files) into one box, a container, that runs the same way anywhere. Released in 2013, it is now the standard way to ship and run applications.

Think of shipping containers. Furniture or food, once it is in a standard box it travels the same way by ship, truck or train. A Docker container is the same: a Java app or a database, it starts with the same steps on any machine that has Docker.

Virtual machines have long offered "a whole environment". The difference is how much OS each one carries.

Neither is better; they do different jobs. In the cloud and on-premises alike, Docker on top of VMs is entirely normal: VMs divide the machines, containers divide the applications.

Images follow the industry-standard OCI format, so an image built with Docker also runs on Podman, Kubernetes and other tools.

From here on, the example is a business web system for a client (a CRM for managing customers). It uses what many Java projects use today: a Spring Boot (Java) API, Vue screens and a PostgreSQL database.

The sample in this guide (Spring Boot 4.1.1 on Java 25, Vue 3, nginx 1.30, PostgreSQL 18) was built, started, upgraded and rolled back for real on Docker Engine 29 with Compose v5.

Start where the payoff is biggest and the risk smallest: containerise just the database. Put this compose.yaml at the root of the project.

# crm/compose.yaml (development: database only)
services:
  postgres:
    image: postgres:18          # same major version as production
    environment:
      POSTGRES_DB: crm
      POSTGRES_USER: crm
      POSTGRES_PASSWORD: secret
    ports:
      - "5432"                  # mapped to a free port on your PC

Spring Boot has Docker Compose support (spring-boot-docker-compose). Add the dependency and, when you start the app from the IDE, Spring Boot runs docker compose up itself and points the database connection at the container. You don't even write the connection details in application.properties.

# Log at application start (excerpt, real output)
DockerComposeLifecycleManager : Using Docker Compose file .../crm/compose.yaml
DockerCli : Container crm-postgres-1 Started
DockerCli : Container crm-postgres-1 Healthy
DbMigrate : Migrating schema "public" to version "1 - create customer"
CrmApplication : Started CrmApplication in 7.271 seconds

For tests there is Testcontainers: a real PostgreSQL starts only while the tests run and is cleaned up afterwards. In Spring Boot, adding @ServiceConnection wires up the connection.

// Test configuration (much as Spring Initializr generates it)
@TestConfiguration(proxyBeanMethods = false)
class TestcontainersConfiguration {
    @Bean
    @ServiceConnection
    PostgreSQLContainer postgresContainer() {
        return new PostgreSQLContainer(DockerImageName.parse("postgres:18"));
    }
}

Next, the Spring Boot app itself. The key is a multi-stage build: one stage to build (JDK and Maven), one to run (JRE only), so the production image carries neither compiler nor source.

# crm/Dockerfile
# syntax=docker/dockerfile:1

# ---- 1. Build stage (JDK and Maven make the jar) ----
FROM eclipse-temurin:25-jdk AS build
WORKDIR /src
COPY .mvn/ .mvn/
COPY mvnw pom.xml ./
RUN --mount=type=cache,target=/root/.m2 ./mvnw -B -q dependency:go-offline
COPY src/ src/
RUN --mount=type=cache,target=/root/.m2 ./mvnw -B -q -DskipTests package

# ---- 2. Runtime stage (a small JRE-only image) ----
FROM eclipse-temurin:25-jre
WORKDIR /app
RUN useradd --system --uid 10001 app
COPY --from=build /src/target/crm-*.jar app.jar
USER app
EXPOSE 8080
ENTRYPOINT ["java", "-XX:MaxRAMPercentage=75", "-jar", "app.jar"]

• Copy the dependency list first: if pom.xml hasn't changed, dependency download comes from cache. A small code change rebuilds in seconds to tens of seconds
• Don't run as root: a dedicated user (app) limits the damage if something goes wrong
• Size memory as a share: -XX:MaxRAMPercentage=75 caps the heap at 75% of the container's memory
• Or skip the Dockerfile: Spring Boot's ./mvnw spring-boot:build-image builds an image with Buildpacks

The Vue screens follow the same idea: build with node, then put only the static output into an nginx image.

# web/Dockerfile
FROM node:24-alpine AS build
WORKDIR /web
COPY package*.json ./
RUN npm ci
COPY . .
RUN npm run build

FROM nginx:1.30-alpine
COPY nginx.conf /etc/nginx/conf.d/default.conf
COPY --from=build /web/dist /usr/share/nginx/html

# web/nginx.conf
server {
    listen 80;
    root /usr/share/nginx/html;

    location / {                       # Vue screens (SPA)
        try_files $uri $uri/ /index.html;
    }
    location /api/ {                   # API goes to the Spring Boot container
        proxy_pass http://app:8080;
        proxy_set_header Host $host;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
    }
}

The app in proxy_pass http://app:8080 is the service name in the Compose file below. No IP addresses: containers find each other by name.

For anything that fits on one server, Docker Compose is the easiest option. Staging and production get the same compose.yaml.

# deploy/compose.yaml (staging and production)
services:
  web:                      # Vue screens + entry point (nginx)
    image: registry.example.com/crm/web:${TAG}
    ports:
      - "80:80"
    depends_on:
      - app
    restart: unless-stopped

  app:                      # The Spring Boot business app
    image: registry.example.com/crm/app:${TAG}
    environment:
      SPRING_DATASOURCE_URL: jdbc:postgresql://db:5432/crm
      SPRING_DATASOURCE_USERNAME: crm
      SPRING_DATASOURCE_PASSWORD: ${DB_PASSWORD}
      TZ: Asia/Tokyo
    depends_on:
      db:
        condition: service_healthy   # start once the database is ready
    restart: unless-stopped

  db:                       # PostgreSQL (data kept in a volume)
    image: postgres:18
    environment:
      POSTGRES_DB: crm
      POSTGRES_USER: crm
      POSTGRES_PASSWORD: ${DB_PASSWORD}
      TZ: Asia/Tokyo
    volumes:
      - db-data:/var/lib/postgresql
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U crm -d crm"]
      interval: 5s
      retries: 10
    restart: unless-stopped

volumes:
  db-data:

# deploy/.env (one per server; not in Git)
TAG=1.0.0
DB_PASSWORD=change-me

• The version lives in one place, TAG: .env decides which release runs
• Passwords stay out of the file: pass them through .env or a secrets mechanism, never in the Compose file
• PostgreSQL 18 volumes: from 18 the data location changed; mount the volume at /var/lib/postgresql (17 and earlier used /var/lib/postgresql/data)
• restart: unless-stopped: containers come back by themselves after a server reboot or a crash

One command starts it all: docker compose up -d. The screen at the top of this guide is the real output; note that the app waits for the database to report healthy.

An upgrade is a matter of changing TAG in .env and running docker compose up -d again. Only the services that changed are recreated; the database keeps running.

For releases that change the data structure (adding a table, say), let Flyway or a similar tool apply the change at application start, and swapping the image is all it takes. Decide in advance how the database will be rolled back: make changes reversible, or back up before upgrading.

Operations

• Status at a glance: docker compose ps for every service, docker compose logs -f app for the app's logs; the same commands on every server
• Self-healing: restart policies and health checks bring crashed containers back
• Fewer environment-specific incidents: OS and library differences, the usual cause of "garbled only in production" or "fails only in production", disappear
• Resource limits: cap CPU and memory per container so one runaway doesn't take everything down
• The same image at any scale: as users grow, move the same image to Kubernetes or a cloud container service

Maintenance

There's no need to containerise everything at once. A good order is (1) the dev database, (2) tests with Testcontainers, (3) image builds in CI, (4) staging, (5) production, checking the benefit of each step before the next.