Docker with GitLab CI/CD: Build Pipelines That Don't Burn You at 3 AM

You've seen the email: 'Pipeline failed — no space left on device.' Or worse, the 3 AM page because a Docker build that worked locally pushed a broken image to production. Docker with GitLab CI/CD is the backbone of modern DevOps, but most teams treat it like a black box. They copy-paste a .gitlab-ci.yml from a blog, cross their fingers, and hope. That works until it doesn't — and when it breaks, it breaks hard. This article gives you the battle-tested patterns to build pipelines that don't burn you. You'll learn how to cache like a pro, avoid the Docker-in-Docker trap, and debug the failures that make juniors cry. By the end, you'll be able to design a pipeline that's fast, reliable, and actually safe for production.

Why Your Pipeline Needs Docker (And Why It Doesn't)

Docker gives you reproducibility. Your build runs in the exact same environment every time — same OS packages, same Node version, same glibc. Without it, you get the classic 'works on my machine' nightmare. But Docker isn't free. It adds complexity: you need a Docker daemon in your CI, you need to manage image caches, and you need to handle layer bloat. If your app is a simple static site that just needs npm install && npm build, you might be better off using a pre-built image with the tools you need, skipping Docker entirely. The rule: use Docker when you need to ship a container. Use a plain shell executor when you just need to run tests or lint.

// io.thecodeforge — DevOps tutorial

# Minimal Docker pipeline for a Node.js app
image: node:18-alpine

services:
  - docker:dind

variables:
  DOCKER_HOST: tcp://docker:2375
  DOCKER_DRIVER: overlay2
  DOCKER_TLS_CERTDIR: ""

before_script:
  - docker login -u $CI_REGISTRY_USER -p $CI_REGISTRY_PASSWORD $CI_REGISTRY

build:
  stage: build
  script:
    - docker build --cache-from $CI_REGISTRY_IMAGE:latest -t $CI_REGISTRY_IMAGE:$CI_COMMIT_SHA .
    - docker push $CI_REGISTRY_IMAGE:$CI_COMMIT_SHA
  only:
    - main

Layer Caching: The Art of Not Rebuilding the World

Every RUN command in your Dockerfile creates a layer. If you change a file early in the Dockerfile, all subsequent layers are invalidated and rebuilt. The classic mistake: putting COPY . . before RUN npm install. That means every code change triggers a full npm install. Fix: copy package.json and package-lock.json first, run install, then copy the rest. But even then, npm install can take 30 seconds. Use --cache-from to pull the last built image and reuse its layers. GitLab CI/CD makes this easy: docker build --cache-from $CI_REGISTRY_IMAGE:latest. This cuts build times from 5 minutes to 30 seconds for a typical Node app.

// io.thecodeforge — DevOps tutorial

FROM node:18-alpine AS builder
WORKDIR /app

# Copy only dependency files first to leverage cache
COPY package.json package-lock.json ./
RUN npm ci --only=production

# Now copy the rest of the app
COPY . .
RUN npm run build

FROM node:18-alpine
WORKDIR /app
COPY --from=builder /app/dist ./dist
COPY --from=builder /app/node_modules ./node_modules
EXPOSE 3000
CMD ["node", "dist/index.js"]

The Docker-in-Docker Trap: When Isolation Bites Back

Docker-in-Docker (dind) is the default way to build Docker images inside a GitLab CI job. You spin up a docker:dind service container, and your job talks to it via DOCKER_HOST=tcp://docker:2375. Sounds clean. But here's the catch: the dind container uses the overlay2 storage driver, which can eat disk space like candy. I've seen a single pipeline consume 50GB of disk because every build left dangling layers. The fix: run docker system prune -f in an after_script to clean up. Also, set DOCKER_DRIVER=overlay2 explicitly. Another trap: TLS. By default, dind expects TLS. If you don't set DOCKER_TLS_CERTDIR="", your job will fail with 'Cannot connect to the Docker daemon'. Always set that variable.

// io.thecodeforge — DevOps tutorial

# Safer dind configuration with cleanup
image: docker:24-git

services:
  - name: docker:24-dind
    command: ["--storage-driver", "overlay2"]

variables:
  DOCKER_HOST: tcp://docker:2375
  DOCKER_TLS_CERTDIR: ""
  DOCKER_DRIVER: overlay2

before_script:
  - docker info  # Verify daemon is reachable
  - docker login -u $CI_REGISTRY_USER -p $CI_REGISTRY_PASSWORD $CI_REGISTRY

build:
  stage: build
  script:
    - docker build -t $CI_REGISTRY_IMAGE:$CI_COMMIT_SHA .
    - docker push $CI_REGISTRY_IMAGE:$CI_COMMIT_SHA
  after_script:
    - docker system prune -f --all --volumes  # Free disk space
  only:
    - main

Secrets Management: Don't Bake Credentials Into Images

The worst thing you can do is hardcode a password in your Dockerfile. Next worst: passing it as a build arg that ends up in the image history. Use Docker build secrets (--secret) or GitLab CI/CD variables. For production, use a secrets manager like Vault or AWS Secrets Manager, and inject at runtime. Never, ever store secrets in the image. I've seen a startup's entire AWS account compromised because someone forgot to remove a .env file from the build context.

// io.thecodeforge — DevOps tutorial

# Use build secrets to avoid leaking credentials
FROM node:18-alpine
WORKDIR /app

# Copy only what's needed
COPY package.json package-lock.json ./
RUN npm ci --only=production

COPY . .

# Use a runtime secret, not a build arg
# The secret is mounted at /run/secrets/npm_token
RUN --mount=type=secret,id=npm_token \
    NPM_TOKEN=$(cat /run/secrets/npm_token) \
    npm publish --registry https://registry.npmjs.org/ --//registry.npmjs.org/:_authToken=$NPM_TOKEN

EXPOSE 3000
CMD ["node", "dist/index.js"]

Testing Your Docker Image in the Pipeline

Building an image is useless if you don't test it. The pattern: build the image, then run a container from it in the same pipeline, execute tests, and only push if tests pass. Use the docker run command with --rm to auto-clean. For integration tests, you might need to start dependent services (database, cache) as additional containers. GitLab CI's services keyword is perfect for this — it spins up containers linked to your job.

// io.thecodeforge — DevOps tutorial

# Build, test, then push
image: docker:24-git

services:
  - docker:dind
  - postgres:13-alpine  # For integration tests

variables:
  DOCKER_HOST: tcp://docker:2375
  DOCKER_TLS_CERTDIR: ""
  POSTGRES_PASSWORD: testpass
  POSTGRES_DB: testdb

stages:
  - build
  - test
  - push

build:
  stage: build
  script:
    - docker build -t $CI_REGISTRY_IMAGE:$CI_COMMIT_SHA .
    - docker tag $CI_REGISTRY_IMAGE:$CI_COMMIT_SHA $CI_REGISTRY_IMAGE:test
  artifacts:
    paths:
      - image_id.txt
  only:
    - main

test:
  stage: test
  script:
    - docker run --rm --network host -e DATABASE_URL=postgres://postgres:testpass@localhost:5432/testdb $CI_REGISTRY_IMAGE:test npm test
  only:
    - main

push:
  stage: push
  script:
    - docker push $CI_REGISTRY_IMAGE:$CI_COMMIT_SHA
  only:
    - main

When Docker in CI Is Overkill

If your project is a simple library or a static site, you don't need Docker in your pipeline. Use a pre-built image with the tools you need (e.g., node:18-alpine for Node, python:3.10 for Python). Run your tests directly. Only add Docker when you need to produce a container image. Also, if your team is small and your deployment target is a PaaS like Heroku or Vercel, they handle containerization for you. Don't add complexity you don't need.

// io.thecodeforge — DevOps tutorial

# Simple pipeline without Docker for a Node.js library
image: node:18-alpine

stages:
  - test
  - publish

test:
  stage: test
  script:
    - npm ci
    - npm test
  only:
    - main

publish:
  stage: publish
  script:
    - npm ci
    - npm publish
  only:
    - tags
  except:
    - branches