30 Days of DevOps — a series by @syssignals Every article is a working project. Every command is verified. No fluff.

The problem nobody talks about

Your CI/CD pipeline is fast. Your tests pass. Your Dockerfiles are clean.

But every deployment is still a negotiation. Developers are stepping on each other. Hotfixes break features. The main branch is a graveyard of half-merged work and nobody quite knows what’s in prod.

The bottleneck isn’t your tools. It’s your branching strategy.

Most teams inherit a branching strategy by accident — someone set it up years ago, nobody questioned it, and now it’s load-bearing. Changing it feels risky, so nobody does.

This article gives you two battle-tested strategies — GitFlow and Trunk-Based Development — with complete setup, real configs, and the decision framework to know which one fits your team. By the end, you’ll have a production-ready repository template with enforced workflow, automated hooks, and PR automation you can use immediately.

What you’ll build

A fully configured Git repository with:

• Branch protection rules enforced via GitHub API
• Husky + lint-staged pre-commit hooks (lint, format, commit message validation)
• Conventional Commits enforcement with commitlint
• PR template with checklist
• GitFlow and Trunk-Based branch models implemented side by side
• A reusable repo-template/ folder you can git clone into any new project

Estimated time: 45 minutes
Skill level: Beginner to intermediate
All commands tested on: Ubuntu 22.04, macOS 14 Sonoma, Git 2.43+

Prerequisites

• Git 2.30+ installed (git --version)
• Node.js 18+ installed (node --version) — needed for Husky and commitlint
• A GitHub account with a personal access token (classic) scoped to repo
• gh CLI installed (optional but recommended — install: https://cli.github.com)
• jq installed (sudo apt install jq / brew install jq)

Part 1: Understanding the two strategies

Before touching a terminal, you need to understand what you’re choosing between and why it matters for DevOps.

GitFlow

Introduced by Vincent Driessen in 2010. Designed for teams with scheduled releases and multiple versions in production simultaneously.

Branch structure:

main          ← production code only. Tagged at every release.
develop       ← integration branch. All features merge here.
feature/*     ← one branch per feature. Branches off develop.
release/*     ← release stabilization. Branches off develop.
hotfix/*      ← emergency fixes. Branches off main.

%%{init: {'gitGraph': {'rotateCommitLabel': true}}}%%
gitGraph
   commit id: "init" tag: "v0.9.0"
   branch develop
   checkout develop
   commit id: "setup"
   branch feature/auth
   checkout feature/auth
   commit id: "scaffold"
   commit id: "tests"
   checkout develop
   merge feature/auth id: "auth merged"
   branch release/1.0.0
   checkout release/1.0.0
   commit id: "bump v1.0.0"
   checkout main
   merge release/1.0.0 tag: "v1.0.0"
   checkout develop
   merge release/1.0.0
   checkout main
   branch hotfix/1.0.1
   checkout hotfix/1.0.1
   commit id: "null fix"
   checkout main
   merge hotfix/1.0.1 tag: "v1.0.1"
   checkout develop
   merge hotfix/1.0.1

Lifecycle of a feature:

git checkout develop
git checkout -b feature/user-authentication
# ... work ...
git checkout develop
git merge --no-ff feature/user-authentication
git branch -d feature/user-authentication

Lifecycle of a release:

git checkout develop
git checkout -b release/1.4.0
# ... bug fixes and version bumps only ...
git checkout main
git merge --no-ff release/1.4.0
git tag -a v1.4.0 -m "Release 1.4.0"
git checkout develop
git merge --no-ff release/1.4.0
git branch -d release/1.4.0

When GitFlow works:

• Mobile apps with App Store review cycles
• SaaS products with enterprise clients on specific versions
• Teams with QA cycles that require a code freeze period
• Regulated industries with formal release gates

When GitFlow fails:

• Continuous deployment pipelines (release branches block CD)
• Small teams (overhead kills velocity)
• Microservices (coordination across repos becomes impossible)

Trunk-Based Development (TBD)

The model used by Google, Meta, Netflix, and most high-performing DevOps teams. All developers commit directly to main (the “trunk”) or use very short-lived feature branches (< 2 days).

Branch structure:

main          ← the trunk. Always deployable. CI runs on every commit.
feature/*     ← optional. Max lifetime: 2 days. Merged via PR.

%%{init: {'gitGraph': {'rotateCommitLabel': true}}}%%
gitGraph
   commit id: "feat: login"
   commit id: "fix: auth"
   branch feature/dashboard
   checkout feature/dashboard
   commit id: "dashboard WIP"
   checkout main
   commit id: "chore: deps"
   merge feature/dashboard id: "flag: off"
   commit id: "feat: search"
   commit id: "perf: cache"
   commit id: "release" tag: "v1.1.0"

The key practices that make TBD work:

1. Feature flags — incomplete features are deployed but hidden behind a flag
2. Branch by abstraction — large refactors use an abstraction layer, not a long-lived branch
3. Pair programming — reduces the need for long review cycles
4. Comprehensive CI — every commit triggers full test suite
5. Small commits — changes that can be reviewed in under 10 minutes

When TBD works:

• Continuous deployment (deploy multiple times per day)
• Teams with high test coverage (>80%)
• Microservices with independent deployment
• Teams with strong DevOps culture (shared ownership of main)

When TBD fails:

• Low test coverage (broken main blocks everyone)
• Large distributed teams without feature flag infrastructure
• Compliance requirements that mandate release gates

Which one should you choose?

flowchart TD
    A([Start]) --> B{Multiple versions\nin prod?}
    B -->|Yes| C([GitFlow])
    B -->|No| D{Deploy multiple\ntimes per day?}
    D -->|Yes| E([Trunk-Based Dev])
    D -->|No| F{Test coverage\nabove 80%?}
    F -->|Yes| E
    F -->|No| G{Regulated or\nformal QA gate?}
    G -->|Yes| C
    G -->|No| H([TBD + build\ncoverage first])
    style C fill:#2d5a1b,color:#fff
    style E fill:#1b3a5a,color:#fff
    style H fill:#1b3a5a,color:#fff

Part 2: Set up the repository

Step 1: Initialize the repository

# Create project directory
mkdir devops-git-template && cd devops-git-template

# Initialize git
git init
git checkout -b main

# Create base structure
mkdir -p .github/workflows .github/ISSUE_TEMPLATE src tests scripts
touch README.md .gitignore .env.example

Create a solid .gitignore that covers most DevOps projects:

cat > .gitignore << 'EOF'
# Environment and secrets
.env
.env.local
.env.*.local
*.pem
*.key
*.p12
*.pfx

# Node
node_modules/
npm-debug.log*
yarn-debug.log*
yarn-error.log*
dist/
build/
.npm

# Python
__pycache__/
*.py[cod]
*$py.class
*.egg-info/
.venv/
venv/
.pytest_cache/

# Terraform
.terraform/
*.tfstate
*.tfstate.*
*.tfvars
!*.tfvars.example
.terraform.lock.hcl

# Docker
.dockerignore

# IDE
.vscode/
.idea/
*.swp
*.swo
.DS_Store
Thumbs.db

# Build artifacts
*.log
*.tmp
*.bak
coverage/
.nyc_output/
EOF

Step 2: Initialize Node.js for tooling

npm init -y

Step 3: Install and configure Husky

Husky intercepts Git hooks and lets you run scripts before commits and pushes.

# Install Husky and lint-staged
npm install --save-dev husky lint-staged

# Initialize Husky (creates .husky/ directory)
npx husky init

# Verify .husky/ was created
ls -la .husky/

Expected output:

total 16
drwxr-xr-x  3 user user 4096 Jan 15 10:23 .
drwxr-xr-x 12 user user 4096 Jan 15 10:23 ..
-rwxr-xr-x  1 user user   29 Jan 15 10:23 pre-commit

Step 4: Install and configure commitlint

commitlint enforces the Conventional Commits specification. This gives you a machine-readable commit history that tools like semantic-release and changelog generators can parse.

npm install --save-dev @commitlint/cli @commitlint/config-conventional

Create the commitlint config:

cat > commitlint.config.js << 'EOF'
module.exports = {
  extends: ['@commitlint/config-conventional'],
  rules: {
    // Type must be one of the following
    'type-enum': [
      2,
      'always',
      [
        'feat',     // New feature
        'fix',      // Bug fix
        'docs',     // Documentation only
        'style',    // Formatting, no logic change
        'refactor', // Code change that is neither fix nor feature
        'perf',     // Performance improvement
        'test',     // Adding or correcting tests
        'build',    // Build system or dependencies
        'ci',       // CI/CD configuration
        'chore',    // Maintenance tasks
        'revert',   // Reverts a previous commit
        'hotfix',   // Emergency fix (GitFlow specific)
        'release',  // Release commit
      ],
    ],
    // Subject line max length
    'subject-max-length': [2, 'always', 100],
    // Subject must not end with a period
    'subject-full-stop': [2, 'never', '.'],
    // Body must have blank line before it
    'body-leading-blank': [2, 'always'],
    // Footer must have blank line before it
    'footer-leading-blank': [2, 'always'],
  },
};
EOF

Add the commit-msg hook:

cat > .husky/commit-msg << 'EOF'
#!/bin/sh
npx --no -- commitlint --edit "$1"
EOF

chmod +x .husky/commit-msg

Step 5: Install and configure ESLint + Prettier

npm install --save-dev eslint prettier eslint-config-prettier

# Create ESLint config
cat > .eslintrc.js << 'EOF'
module.exports = {
  env: {
    node: true,
    es2021: true,
  },
  extends: ['eslint:recommended', 'prettier'],
  parserOptions: {
    ecmaVersion: 'latest',
    sourceType: 'module',
  },
  rules: {
    'no-console': 'warn',
    'no-unused-vars': ['error', { argsIgnorePattern: '^_' }],
    'no-var': 'error',
    'prefer-const': 'error',
  },
};
EOF

# Create Prettier config
cat > .prettierrc << 'EOF'
{
  "semi": true,
  "trailingComma": "es5",
  "singleQuote": true,
  "printWidth": 100,
  "tabWidth": 2,
  "useTabs": false
}
EOF

Step 6: Configure lint-staged

lint-staged runs linters only on staged files — not the entire codebase. This makes pre-commit hooks fast enough that developers won’t disable them.

Add to package.json:

node -e "
const fs = require('fs');
const pkg = JSON.parse(fs.readFileSync('package.json', 'utf8'));
pkg['lint-staged'] = {
  '*.{js,ts,jsx,tsx}': ['eslint --fix', 'prettier --write'],
  '*.{json,md,yml,yaml}': ['prettier --write'],
  '*.sh': ['shellcheck']
};
pkg.scripts = {
  ...pkg.scripts,
  'prepare': 'husky',
  'lint': 'eslint . --ext .js,.ts',
  'lint:fix': 'eslint . --ext .js,.ts --fix',
  'format': 'prettier --write .',
  'format:check': 'prettier --check .'
};
fs.writeFileSync('package.json', JSON.stringify(pkg, null, 2));
console.log('package.json updated');
"

Update the pre-commit hook:

cat > .husky/pre-commit << 'EOF'
#!/bin/sh
npx lint-staged
EOF

chmod +x .husky/pre-commit

Here’s what happens on every git commit with this setup:

On commit:

flowchart LR
    A([git commit]) --> B[pre-commit hook]
    B --> C{lint-staged\npasses?}
    C -->|Fail| D([Blocked — fix lint])
    C -->|Pass| E[commit-msg hook]
    E --> F{commitlint\npasses?}
    F -->|Fail| G([Blocked — fix message])
    F -->|Pass| H([Commit created])

On push:

flowchart LR
    A([git push]) --> B[pre-push hook]
    B --> C{Protected\nbranch?}
    C -->|Yes| D([Blocked — open a PR])
    C -->|No| E([Push succeeds])

Step 7: Create the PR template

mkdir -p .github

cat > .github/pull_request_template.md << 'EOF'
## Summary

<!-- What does this PR do? One paragraph max. -->

## Type of change

- [ ] `feat` — New feature
- [ ] `fix` — Bug fix
- [ ] `docs` — Documentation update
- [ ] `refactor` — Code refactor (no functional change)
- [ ] `ci` — CI/CD changes
- [ ] `chore` — Maintenance
- [ ] `hotfix` — Emergency production fix

## Related issues

Closes #<!-- issue number -->

## How to test

<!-- Step-by-step instructions for reviewers to test this change -->

1. 
2. 
3. 

## Checklist

- [ ] My code follows the project's style guidelines
- [ ] I have run `npm run lint` and there are no errors
- [ ] I have added or updated tests
- [ ] I have updated documentation if needed
- [ ] My commits follow the Conventional Commits format
- [ ] I have checked this branch is up to date with the target branch
- [ ] This PR is < 400 lines of change (if not, explain why)

## Screenshots / output (if applicable)

<!-- Paste terminal output or screenshots here -->

## Notes for reviewers

<!-- Anything the reviewer should pay special attention to -->
EOF

Step 8: Create GitHub Actions CI workflow

cat > .github/workflows/ci.yml << 'EOF'
name: CI

on:
  push:
    branches: [main, develop]
  pull_request:
    branches: [main, develop]

concurrency:
  group: $-$
  cancel-in-progress: true

jobs:
  lint:
    name: Lint & Format
    runs-on: ubuntu-22.04
    steps:
      - name: Checkout
        uses: actions/checkout@v4

      - name: Setup Node.js
        uses: actions/setup-node@v4
        with:
          node-version: '20'
          cache: 'npm'

      - name: Install dependencies
        run: npm ci

      - name: Run ESLint
        run: npm run lint

      - name: Check formatting
        run: npm run format:check

  commitlint:
    name: Validate commit messages
    runs-on: ubuntu-22.04
    if: github.event_name == 'pull_request'
    steps:
      - name: Checkout
        uses: actions/checkout@v4
        with:
          fetch-depth: 0

      - name: Setup Node.js
        uses: actions/setup-node@v4
        with:
          node-version: '20'
          cache: 'npm'

      - name: Install dependencies
        run: npm ci

      - name: Validate PR commits
        run: |
          npx commitlint \
            --from $ \
            --to $ \
            --verbose

  test:
    name: Tests
    runs-on: ubuntu-22.04
    needs: lint
    steps:
      - name: Checkout
        uses: actions/checkout@v4

      - name: Setup Node.js
        uses: actions/setup-node@v4
        with:
          node-version: '20'
          cache: 'npm'

      - name: Install dependencies
        run: npm ci

      - name: Run tests
        run: npm test --if-present
EOF

Every PR triggers this pipeline before anyone can merge:

flowchart TD
    A([PR opened]) --> B[lint]
    A --> C[commitlint]
    A --> D[test]
    B --> E{All checks\npassed?}
    C --> E
    D --> E
    E -->|No| F([PR blocked])
    E -->|Yes| G([Awaiting review])
    G --> H([Merged to main])

Part 3: Set up GitFlow on a real repository

Step 1: Install git-flow

# Ubuntu / Debian
sudo apt-get install git-flow -y

# macOS
brew install git-flow-avh

# Verify
git flow version

Expected output:

1.12.3 (AVH Edition)

Step 2: Initialize git-flow

# Run inside your repo directory
git flow init -d

The -d flag accepts all defaults. This creates and configures:

Branch name for production releases: main
Branch name for "next release" development: develop
Feature branches: feature/
Bugfix branches: bugfix/
Release branches: release/
Hotfix branches: hotfix/
Support branches: support/
Version tag prefix: v

Verify both branches exist:

git branch -a

Expected output:

* develop
  main

Step 3: Work through the full GitFlow lifecycle

Create and finish a feature:

# Start a feature
git flow feature start user-authentication

# You are now on branch: feature/user-authentication
# Verify
git branch --show-current

Expected output:

feature/user-authentication

# Simulate some work
mkdir -p src/auth
cat > src/auth/index.js << 'EOF'
const authenticate = (username, password) => {
  // Authentication logic would go here
  return { user: username, token: 'jwt-token-placeholder' };
};

module.exports = { authenticate };
EOF

# Stage and commit with conventional commit format
git add src/auth/index.js
git commit -m "feat(auth): add authentication module scaffold"

# Finish the feature — merges to develop with --no-ff
git flow feature finish user-authentication

Expected output:

Branches 'develop' and 'feature/user-authentication' have diverged.
Updating 9f3e2a1..c4b8d2f
Fast-forward (no commit created; -m option ignored)
 src/auth/index.js | 6 ++++++
 1 file changed, 6 insertions(+)
Deleted branch feature/user-authentication (was c4b8d2f).

Summary of actions:
- The feature branch 'feature/user-authentication' was merged into 'develop'
- Feature branch 'feature/user-authentication' has been locally deleted
- You are now on branch 'develop'

Create and finish a release:

# Start a release from develop
git flow release start 1.0.0

# Bump version in package.json
npm version 1.0.0 --no-git-tag-version

git add package.json
git commit -m "release: bump version to 1.0.0"

# Finish the release
# This: merges to main, tags v1.0.0, merges back to develop
git flow release finish '1.0.0'

You’ll be prompted for a tag message. Enter: Release v1.0.0

Verify the tag was created:

git tag -l

Expected output:

v1.0.0

Simulate a hotfix:

# Start hotfix from main
git flow hotfix start 1.0.1

cat >> src/auth/index.js << 'EOF'

// Hotfix: prevent null username crash
const safeAuthenticate = (username, password) => {
  if (!username || !password) throw new Error('Credentials required');
  return authenticate(username, password);
};

module.exports = { authenticate, safeAuthenticate };
EOF

git add src/auth/index.js
git commit -m "fix(auth): prevent null username crash in authenticate"

# Finish hotfix — merges to main AND develop
git flow hotfix finish '1.0.1'

Part 4: Set up Trunk-Based Development

TBD requires discipline more than tooling. The tooling enforces the discipline.

Step 1: Protect the main branch

If you’re using the gh CLI:

# Set your repo name
REPO="your-github-username/devops-git-template"

gh api \
  --method PUT \
  -H "Accept: application/vnd.github+json" \
  /repos/${REPO}/branches/main/protection \
  --input - << 'EOF'
{
  "required_status_checks": {
    "strict": true,
    "contexts": ["lint", "test", "commitlint"]
  },
  "enforce_admins": true,
  "required_pull_request_reviews": {
    "required_approving_review_count": 1,
    "dismiss_stale_reviews": true,
    "require_code_owner_reviews": false
  },
  "restrictions": null,
  "allow_force_pushes": false,
  "allow_deletions": false,
  "required_linear_history": true
}
EOF

Expected output:

{
  "url": "https://api.github.com/repos/your-username/devops-git-template/branches/main/protection",
  "required_status_checks": {
    "strict": true,
    ...
  }
}

What each rule does:

Step 2: Create a CODEOWNERS file

CODEOWNERS automatically assigns reviewers based on which files are changed.

cat > .github/CODEOWNERS << 'EOF'
# Global owners — review everything
*                   @your-github-username

# CI/CD changes require DevOps team review
.github/            @your-github-username
*.yml               @your-github-username
Dockerfile*         @your-github-username
terraform/          @your-github-username

# Auth module — security-sensitive
src/auth/           @your-github-username
EOF

Step 3: Feature flag scaffold for TBD

In Trunk-Based Development, you merge incomplete features to main behind a feature flag. Here’s a minimal implementation:

cat > src/feature-flags.js << 'EOF'
/**
 * Feature flag system for Trunk-Based Development
 * Flags are read from environment variables.
 * In production, use a service like LaunchDarkly, Flagsmith, or Unleash.
 */

const flags = {
  // Format: FEATURE_FLAG_<NAME>=true|false
  NEW_DASHBOARD: process.env.FEATURE_FLAG_NEW_DASHBOARD === 'true',
  BETA_SEARCH: process.env.FEATURE_FLAG_BETA_SEARCH === 'true',
  USER_AUTHENTICATION_V2: process.env.FEATURE_FLAG_USER_AUTH_V2 === 'true',
};

const isEnabled = (flagName) => {
  if (!(flagName in flags)) {
    console.warn(`[FeatureFlag] Unknown flag: ${flagName}`);
    return false;
  }
  return flags[flagName];
};

module.exports = { isEnabled, flags };
EOF

Example usage in application code:

const { isEnabled } = require('./feature-flags');

const getAuthHandler = () => {
  if (isEnabled('USER_AUTHENTICATION_V2')) {
    return require('./auth/v2');  // New implementation, hidden behind flag
  }
  return require('./auth/v1');    // Stable implementation
};

Step 4: Add a pre-push hook to block direct pushes to main

cat > .husky/pre-push << 'EOF'
#!/bin/sh

CURRENT_BRANCH=$(git symbolic-ref HEAD | sed -e 's,.*/\(.*\),\1,')
PROTECTED_BRANCHES="^(main|master|develop)$"

if echo "$CURRENT_BRANCH" | grep -qE "$PROTECTED_BRANCHES"; then
  echo "⛔ Direct push to '$CURRENT_BRANCH' is not allowed."
  echo "   Create a feature branch and open a pull request."
  echo ""
  echo "   git checkout -b feature/your-feature-name"
  exit 1
fi

exit 0
EOF

chmod +x .husky/pre-push

Test it:

# Should be blocked if you're on main
git push origin main

Expected output:

⛔ Direct push to 'main' is not allowed.
   Create a feature branch and open a pull request.

   git checkout -b feature/your-feature-name
error: failed to push some refs to 'origin'

Part 5: The reusable template

Package everything into a template structure others can use:

# Create the template structure
mkdir -p repo-template/.github/workflows
mkdir -p repo-template/.husky
mkdir -p repo-template/src

# Copy all config files
cp .gitignore repo-template/
cp .eslintrc.js repo-template/
cp .prettierrc repo-template/
cp commitlint.config.js repo-template/
cp package.json repo-template/
cp .github/pull_request_template.md repo-template/.github/
cp .github/CODEOWNERS repo-template/.github/
cp .github/workflows/ci.yml repo-template/.github/workflows/
cp .husky/pre-commit repo-template/.husky/
cp .husky/pre-push repo-template/.husky/
cp .husky/commit-msg repo-template/.husky/
cp src/feature-flags.js repo-template/src/

# Create a setup script so others can bootstrap quickly
cat > repo-template/setup.sh << 'EOF'
#!/bin/bash
set -euo pipefail

echo "Setting up repository from syssignals DevOps template..."

# Install dependencies
npm install

# Initialize Husky
npm run prepare

# Verify hooks are executable
chmod +x .husky/pre-commit .husky/pre-push .husky/commit-msg

echo "Setup complete."
echo ""
echo "Next steps:"
echo "  1. Update CODEOWNERS with your GitHub username"
echo "  2. Set branch protection rules on GitHub (see README)"
echo "  3. Run 'npm run lint' to verify ESLint is working"
echo "  4. Make your first commit: git commit -m 'chore: initial repository setup'"
EOF

chmod +x repo-template/setup.sh

How it works under the hood

Why Husky intercepts hooks:

Git stores hooks in .git/hooks/ — a directory that is never committed or shared. Husky solves this by adding a prepare npm script that installs scripts into .git/hooks/ when anyone runs npm install. The hooks in .husky/ are committed to the repo and become the source of truth. When a developer clones the repo and runs npm install, Husky automatically installs the hooks.

Why lint-staged and not full linting:

Running ESLint on your entire codebase before every commit is slow. On a large project it can take 30+ seconds. Developers start using git commit --no-verify to skip it. lint-staged runs linters only on the files you’ve staged with git add — typically 1–5 files. The hook completes in under 2 seconds, which developers will actually tolerate.

Why conventional commits matter for DevOps:

Conventional commits aren’t just a style guide. Tools like semantic-release parse commit messages to determine the next version number (feat = minor bump, fix = patch bump, BREAKING CHANGE = major bump), auto-generate changelogs, and publish packages — all automatically in CI. Enforcing the format from day one means you can adopt these tools later without reformatting history.

Why --no-ff in GitFlow:

The --no-ff flag (no fast-forward) forces Git to create a merge commit even when the history is linear. Without it, Git can fast-forward the branch pointer and you lose the context that these commits belonged to a feature branch. With --no-ff, the graph always shows which commits were part of which feature — invaluable for git bisect and debugging.

Common errors and fixes

Error 1: husky: command not found

.husky/pre-commit: line 1: husky: command not found

Cause: Husky wasn’t installed or npm install wasn’t run after cloning.

Fix:

npm install
npm run prepare

Error 2: commitlint fails with Your commit message has an error

✖   subject may not be empty [subject-empty]
✖   type may not be empty [type-empty]

Cause: Commit message doesn’t follow Conventional Commits format.

Fix: Use the correct format:

# Wrong
git commit -m "added login feature"

# Correct
git commit -m "feat(auth): add login form with JWT support"

Error 3: git flow command not found after install

git: 'flow' is not a git command

Cause: On some systems git-flow installs as a separate binary not recognized by git.

Fix:

# Ubuntu: install the AVH edition explicitly
sudo apt-get remove git-flow
sudo apt-get install git-flow -y

# macOS: use Homebrew AVH edition
brew uninstall git-flow
brew install git-flow-avh

# Verify
which git-flow
git flow version

Error 4: Branch protection API returns 403

{
  "message": "Not Found",
  "documentation_url": "..."
}

Cause: Your GitHub token doesn’t have repo scope, or the repo is private and the token lacks access.

Fix:

# Verify your token has the right scopes
gh auth status

# Re-authenticate with correct scopes
gh auth login --scopes repo,workflow

Error 5: lint-staged fails with No staged files match

✔ Preparing lint-staged...
✔ Running tasks for staged files...
✔ Applying modifications from tasks...
✔ Cleaning up temporary files...

This is actually not an error — it means lint-staged ran but found no matching files in your staged changes. If you staged a .sh file and configured shellcheck, but shellcheck isn’t installed, you’ll see:

# Install shellcheck
sudo apt-get install shellcheck   # Ubuntu
brew install shellcheck           # macOS

What’s next — extend this project

Make it production-ready:

1. Add semantic-release to automate version bumps and changelog generation from your conventional commits. Configure it in .releaserc.json and add a release job to your CI workflow.

2. Add danger for automated PR review — it can enforce PR size limits, check that tests were added with features, and post comments when the PR template isn’t filled out.

3. Integrate git-secrets (AWS) or gitleaks to scan commits for accidentally committed secrets before they reach GitHub.

Series recap — Day 1

You now have:

• A Git repository with enforced workflow (pre-commit, pre-push, commit-msg hooks)
• Conventional Commits enforced at the hook level and validated in CI
• A PR template that enforces review discipline
• Branch protection rules that make it physically impossible to push broken code to main
• A complete understanding of when to use GitFlow vs Trunk-Based Development
• A reusable repo-template/ folder you can drop into any project

The foundation is set. Everything built in the next 29 articles will use this repository structure.

Day 2 preview

Day 2: Dockerize any application the right way — multi-stage builds and best practices

We’ll take a Node.js application from a 1.2GB naive image to a 45MB hardened production image. Multi-stage builds, non-root users, BuildKit cache mounts, and Docker Scout vulnerability scanning.

This is Day 1 of the 30 Days of DevOps series.
Follow @syssignals on X — Day 2 drops tomorrow.

Found an error? Drop a reply on X and I’ll fix it and credit you.

30 Days of DevOps — a series by @syssignals Every article is a working project. Every command is verified. No fluff.

The problem with “it works on my machine”

A new developer joins your team. They clone the repo, follow the README, spend 3 hours debugging a Node version mismatch, give up, and ping you on Slack.

You’ve been there. You’ve been both people in that story.

Docker was supposed to fix this. And it does — but only if you use it correctly. Most teams don’t. They write a Dockerfile that works, ship it, and never look back. That Dockerfile ends up in production running as root, carrying 800 MB of build tools nobody needs, with 47 CVEs sitting quietly in a base image from 2021.

This article fixes that. You’ll take a real Node.js application from a 1.2 GB naive image down to a 45 MB hardened production image. Every decision is explained. Every command is verified. By the end you’ll have a Dockerfile template you can drop into any project and trust.

What you’ll build

A production-grade Docker setup for a Node.js REST API, including:

• A naive Dockerfile (the before — so you understand what you’re fixing)
• A multi-stage Dockerfile that reduces image size by ~96%
• A hardened production image running as a non-root user
• A .dockerignore that prevents secrets and junk from leaking into images
• Docker Compose for local development with hot reload
• A Docker Scout vulnerability scan comparing naive vs hardened image
• A reusable docker/ folder structure for any project

Estimated time: 60 minutes
Final image size: ~45 MB (down from ~1.2 GB)

Here is the complete picture of what this build produces:

%%{init: {'theme': 'dark'}}%%
flowchart TD
    SRC(["Your Node.js App\nsrc/  ·  package.json"]):::src

    subgraph BUILD ["Multi-Stage Dockerfile"]
        DEPS["Stage 1 · deps\nnode:20-alpine\nnpm ci --omit=dev"]:::stage
        TEST["Stage 2 · test\nnode:20-alpine\nnpm run test:ci"]:::stage
        FINAL["Stage 3 · production\ndistroless/nodejs20\nUSER nonroot"]:::stage
        DEPS -->|"prod node_modules only"| FINAL
        TEST -->|"CI gate — must pass"| FINAL
    end

    DEV_IMG["myapp:dev\nnodemon · hot reload\ndocker compose up"]:::dev
    PROD_IMG["myapp:production\n47 MB · uid 65532\nzero critical CVEs"]:::prod

    SRC --> BUILD
    DEPS --> DEV_IMG
    FINAL --> PROD_IMG

    classDef src fill:#1a2744,stroke:#58a6ff,color:#e6edf3
    classDef stage fill:#1c2128,stroke:#30363d,color:#8b949e
    classDef dev fill:#1a2744,stroke:#58a6ff,color:#79b8ff
    classDef prod fill:#0d2818,stroke:#3fb950,color:#3fb950

Prerequisites

Operating system

Windows users: All commands must be run inside WSL2 (Ubuntu), not PowerShell or CMD. Docker Desktop routes WSL2 commands through the same daemon. Open Ubuntu from the Start Menu and work from there.

Required software

1. Docker Engine 24.0+ or Docker Desktop 4.20+

# Check if Docker is already installed
docker --version
# Expected: Docker version 24.x.x or higher

docker info | grep "Server Version"
# Expected: Server Version: 24.x.x

Install Docker Engine on Ubuntu (skip if already installed):

# Remove old versions
sudo apt-get remove docker docker-engine docker.io containerd runc 2>/dev/null

# Install dependencies
sudo apt-get update
sudo apt-get install -y ca-certificates curl gnupg lsb-release

# Add Docker's official GPG key
sudo mkdir -p /etc/apt/keyrings
curl -fsSL https://download.docker.com/linux/ubuntu/gpg | \
  sudo gpg --dearmor -o /etc/apt/keyrings/docker.gpg

# Add the repository
echo \
  "deb [arch=$(dpkg --print-architecture) signed-by=/etc/apt/keyrings/docker.gpg] \
  https://download.docker.com/linux/ubuntu \
  $(lsb_release -cs) stable" | \
  sudo tee /etc/apt/sources.list.d/docker.list > /dev/null

# Install Docker Engine, CLI, containerd, and plugins
sudo apt-get update
sudo apt-get install -y docker-ce docker-ce-cli containerd.io \
  docker-buildx-plugin docker-compose-plugin

# Add your user to the docker group (avoids sudo on every command)
sudo usermod -aG docker $USER

# Apply group membership without logout
newgrp docker

# Verify installation
docker run --rm hello-world

Expected final line:

Hello from Docker!

2. Docker Buildx (for BuildKit cache mounts)

# Verify Buildx is available
docker buildx version
# Expected: github.com/docker/buildx v0.12.x linux/amd64

# Enable BuildKit globally (set as default builder)
docker buildx create --name mybuilder --use
docker buildx inspect --bootstrap

Expected output (last line):

[+] Building 4.2s (1/1) FINISHED

3. Docker Scout (for vulnerability scanning)

# Install Docker Scout CLI plugin
curl -fsSL https://raw.githubusercontent.com/docker/scout-cli/main/install.sh | sh

# Verify
docker scout version
# Expected: docker scout version v1.x.x

If curl isn’t available: sudo apt-get install -y curl

4. Node.js 20 LTS (for the sample application)

# Install via nvm — avoids permission issues with global packages
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.7/install.sh | bash
source ~/.bashrc

nvm install 20
nvm use 20
nvm alias default 20

# Verify
node --version   # v20.x.x
npm --version    # 10.x.x

5. IDE recommendations

The VS Code Docker extension adds Dockerfile syntax highlighting, image management from the sidebar, and build error detection inline. Not required but saves debugging time.

Full environment check

Run this before starting. If anything fails, fix it before continuing:

echo "=== Docker ===" && docker --version && \
echo "=== Buildx ===" && docker buildx version && \
echo "=== Compose ===" && docker compose version && \
echo "=== Node ===" && node --version && \
echo "=== npm ===" && npm --version && \
echo "=== Scout ===" && docker scout version 2>/dev/null | head -1 && \
echo "" && echo "All checks passed. Ready to build."

Expected output:

=== Docker ===
Docker version 24.0.7, build afdd53b
=== Buildx ===
github.com/docker/buildx v0.12.1 linux/amd64
=== Compose ===
Docker Compose version v2.24.5
=== Node ===
v20.11.0
=== npm ===
10.2.4
=== Scout ===
docker scout version v1.4.0

All checks passed. Ready to build.

Part 1: The sample application

We need a real application — not a toy. This is a Node.js REST API with actual dependencies: Express, input validation, security middleware, and structured logging. Realistic enough that the image size problem is genuine.

Step 1: Create the project structure

mkdir docker-best-practices && cd docker-best-practices
npm init -y
mkdir -p src/routes src/middleware

Step 2: Install dependencies

# Production dependencies — go into the final image
npm install express helmet cors morgan zod dotenv

# Development dependencies — must NEVER go into a production image
npm install --save-dev nodemon jest supertest

Verify the size impact:

du -sh node_modules/
# ~75MB — this entire directory should never reach a production image

Step 3: Create the application source

src/index.js — application entry point:

'use strict';

const express = require('express');
const helmet = require('helmet');
const cors = require('cors');
const morgan = require('morgan');
const { healthRouter } = require('./routes/health');
const { usersRouter } = require('./routes/users');
const { errorHandler } = require('./middleware/errorHandler');

const app = express();
const PORT = process.env.PORT || 3000;

app.use(helmet());
app.use(cors({
  origin: process.env.ALLOWED_ORIGINS?.split(',') || ['http://localhost:3000'],
}));
app.use(morgan(process.env.NODE_ENV === 'production' ? 'combined' : 'dev'));
app.use(express.json({ limit: '10kb' }));

app.use('/health', healthRouter);
app.use('/api/users', usersRouter);

app.use((req, res) => res.status(404).json({ error: 'Route not found' }));
app.use(errorHandler);

const server = app.listen(PORT, '0.0.0.0', () => {
  console.log(`Server running on port ${PORT} [${process.env.NODE_ENV || 'development'}]`);
});

process.on('SIGTERM', () => {
  console.log('SIGTERM received — shutting down gracefully');
  server.close(() => process.exit(0));
});

process.on('SIGINT', () => {
  server.close(() => process.exit(0));
});

module.exports = { app };

src/routes/health.js:

'use strict';

const { Router } = require('express');
const router = Router();

router.get('/', (req, res) => {
  res.json({
    status: 'healthy',
    timestamp: new Date().toISOString(),
    uptime: Math.floor(process.uptime()),
    environment: process.env.NODE_ENV || 'development',
  });
});

router.get('/ready', (req, res) => res.json({ status: 'ready' }));

module.exports = { healthRouter: router };

src/routes/users.js:

'use strict';

const { Router } = require('express');
const { z } = require('zod');

const router = Router();

const UserSchema = z.object({
  name: z.string().min(1).max(100),
  email: z.string().email(),
  role: z.enum(['admin', 'user', 'viewer']).default('user'),
});

const db = new Map([
  ['1', { id: '1', name: 'Alice', email: 'alice@example.com', role: 'admin' }],
  ['2', { id: '2', name: 'Bob',   email: 'bob@example.com',   role: 'user'  }],
]);

router.get('/', (req, res) => {
  res.json({ users: Array.from(db.values()), total: db.size });
});

router.get('/:id', (req, res) => {
  const user = db.get(req.params.id);
  if (!user) return res.status(404).json({ error: 'User not found' });
  res.json(user);
});

router.post('/', (req, res) => {
  const result = UserSchema.safeParse(req.body);
  if (!result.success) {
    return res.status(400).json({ error: 'Validation failed', details: result.error.flatten() });
  }
  const id = String(Date.now());
  const user = { id, ...result.data };
  db.set(id, user);
  res.status(201).json(user);
});

module.exports = { usersRouter: router };

src/middleware/errorHandler.js:

'use strict';

const errorHandler = (err, req, res, next) => {
  const status = err.statusCode || err.status || 500;
  const message = process.env.NODE_ENV === 'production' ? 'An error occurred' : err.message;

  console.error({ error: err.message, path: req.path, method: req.method });
  res.status(status).json({ error: message });
};

module.exports = { errorHandler };

.env.example — document required variables (commit this, never .env):

cat > .env.example << 'EOF'
NODE_ENV=development
PORT=3000
ALLOWED_ORIGINS=http://localhost:3000
EOF

Update package.json scripts:

node -e "
const fs = require('fs');
const pkg = JSON.parse(fs.readFileSync('package.json', 'utf8'));
pkg.main = 'src/index.js';
pkg.engines = { node: '>=20.0.0' };
pkg.scripts = {
  start: 'node src/index.js',
  dev: 'nodemon src/index.js',
  test: 'jest --coverage',
  'test:ci': 'jest --ci --forceExit'
};
fs.writeFileSync('package.json', JSON.stringify(pkg, null, 2));
console.log('Updated package.json');
"

Verify the app works outside Docker first:

NODE_ENV=development node src/index.js &
APP_PID=$!
sleep 1

curl -s http://localhost:3000/health | python3 -m json.tool

kill $APP_PID 2>/dev/null

Expected output:

{
    "status": "healthy",
    "timestamp": "2025-01-15T10:23:45.123Z",
    "uptime": 0,
    "environment": "development"
}

Part 2: The naive Dockerfile — the before picture

This is the Dockerfile most tutorials show you. It works. It is also dangerous.

cat > Dockerfile.naive << 'EOF'
FROM node:20

WORKDIR /app

COPY . .

RUN npm install

EXPOSE 3000

CMD ["node", "src/index.js"]
EOF

Build it and inspect:

docker build -f Dockerfile.naive -t myapp:naive .

Expected build output:

[+] Building 42.1s (8/8) FINISHED
 => [internal] load build definition from Dockerfile.naive
 => [1/4] FROM docker.io/library/node:20
 => [2/4] WORKDIR /app
 => [3/4] COPY . .
 => [4/4] RUN npm install
 => exporting to image

Now check what you actually built:

# Image size
docker images myapp:naive --format "Size: "
# Size: 1.21GB

# Is it running as root?
docker run --rm myapp:naive whoami
# root   ← critical security problem

# Are devDependencies included?
docker run --rm myapp:naive ls node_modules | grep nodemon
# nodemon   ← dev tools in production

# How many system tools are exposed?
docker run --rm myapp:naive which curl bash apt wget
# /usr/bin/curl
# /bin/bash
# /usr/bin/apt
# /usr/bin/wget
# Every one of these is an attacker's tool

The naive image has three fundamental problems:

1. 1.21 GB — the full Debian + Node.js + devDependencies + build tools
2. Runs as root — any container escape gives root on the host
3. Full shell and system utilities — an attacker who gets RCE has a full toolkit

Here is exactly what each image contains, and what the production image leaves out:

%%{init: {'theme': 'dark'}}%%
flowchart LR
    subgraph NAIVE ["❌  Naive Image · 1.21 GB · runs as root"]
        direction TB
        N1["node:20 Debian base\n~1.0 GB"]:::bad
        N2["devDependencies\nnodemon · jest · supertest"]:::bad
        N3["Shell: bash · curl · wget · apt"]:::bad
        N4["Build tools: gcc · python · make"]:::bad
        N5["Your app source"]:::neutral
        N1 --> N2 --> N3 --> N4 --> N5
    end

    subgraph PROD ["✓  Production Image · 47 MB · uid 65532"]
        direction TB
        P1["distroless/nodejs20-debian12\n~28 MB"]:::good
        P2["prod node_modules only\n~19 MB"]:::good
        P3["Your app source\n< 1 MB"]:::good
        P1 --> P2 --> P3
    end

    classDef bad fill:#2d1215,stroke:#f85149,color:#f85149
    classDef good fill:#0d2818,stroke:#3fb950,color:#3fb950
    classDef neutral fill:#1c2128,stroke:#30363d,color:#e6edf3

Part 3: The production Dockerfile — multi-stage build

Multi-stage builds use multiple FROM statements in one Dockerfile. Each stage builds on the previous. The final image receives only what you explicitly copy — build tools, test frameworks, and dev dependencies never make it in.

cat > Dockerfile << 'EOF'
# ─── Stage 1: deps ────────────────────────────────────────────────────────────
# Install production dependencies only.
# This stage is never shipped. Its only output is node_modules.
FROM node:20-alpine AS deps

WORKDIR /app

# Copy lockfiles first — before source code.
# This layer is cached until package.json or package-lock.json changes.
# Changing src/ files won't invalidate this cache layer.
COPY package.json package-lock.json ./

# npm ci: uses lockfile exactly, fails if lockfile is out of sync
# --omit=dev: excludes devDependencies (nodemon, jest, etc.)
RUN npm ci --omit=dev --frozen-lockfile

# ─── Stage 2: test ────────────────────────────────────────────────────────────
# Runs tests with all dependencies (including dev).
# CI can build this target to gate on test failures before shipping prod.
FROM node:20-alpine AS test

WORKDIR /app

COPY package.json package-lock.json ./
RUN npm ci --frozen-lockfile

COPY . .

RUN npm run test:ci --if-present

# ─── Stage 3: production ──────────────────────────────────────────────────────
# The only stage that ships. Built on distroless — no shell, no package manager,
# no system utilities. The absolute minimum to run a Node.js process.
FROM gcr.io/distroless/nodejs20-debian12 AS production

# OCI image labels — document the image for registries and scanners
LABEL org.opencontainers.image.title="myapp"
LABEL org.opencontainers.image.description="Node.js REST API — 30 Days of DevOps"
LABEL org.opencontainers.image.source="https://github.com/syssignals/30-days-devops"
LABEL org.opencontainers.image.licenses="MIT"

WORKDIR /app

# Pull only production node_modules from the deps stage.
# Build tools, compilers, and package caches from that stage don't follow.
COPY --from=deps /app/node_modules ./node_modules

# Copy application source
COPY src/ ./src/
COPY package.json ./

# Distroless images run as nonroot (uid=65532) by default.
# Declaring it explicitly satisfies security scanners and makes intent clear.
USER nonroot

EXPOSE 3000

# Exec form (array) is required in distroless — there is no shell to interpret
# the shell form. It also makes node PID 1, so SIGTERM reaches it directly.
CMD ["/nodejs/bin/node", "src/index.js"]
EOF

Build and measure:

DOCKER_BUILDKIT=1 docker build \
  --target production \
  --tag myapp:production \
  .

Expected output:

[+] Building 18.4s (13/13) FINISHED
 => [deps 1/3] FROM docker.io/library/node:20-alpine
 => [deps 2/3] COPY package.json package-lock.json ./
 => [deps 3/3] RUN npm ci --omit=dev --frozen-lockfile
 => [production 1/4] COPY --from=deps /app/node_modules
 => [production 2/4] COPY src/ ./src/
 => [production 3/4] COPY package.json ./
 => exporting to image
 => => writing image sha256:b7e3d4...

Compare sizes:

docker images | grep myapp

Expected output:

REPOSITORY   TAG          IMAGE ID       CREATED          SIZE
myapp        production   b7e3d4f8a1c2   10 seconds ago   47.2MB
myapp        naive        a3f8c2d1e4b9   5 minutes ago    1.21GB

96% reduction. 1.21 GB → 47 MB.

Verify it runs and is correctly hardened:

# Start it
docker run -d \
  --name myapp-test \
  -p 3000:3000 \
  -e NODE_ENV=production \
  myapp:production

sleep 2

# Test the health endpoint
curl -s http://localhost:3000/health | python3 -m json.tool

# Verify non-root
docker run --rm myapp:production id
# uid=65532(nonroot) gid=65532(nonroot) groups=65532(nonroot)

# Verify no shell available (this should fail — that's the point)
docker exec myapp-test sh 2>&1
# OCI runtime exec failed: exec failed: unable to start container process:
# exec: "sh": executable file not found in $PATH

# Stop and remove
docker stop myapp-test && docker rm myapp-test

Part 4: The .dockerignore file

Without .dockerignore, every COPY . . sends your entire project — node_modules, .env, .git, IDE configs — to the Docker daemon as build context. This leaks secrets, bloats cache, and slows builds.

cat > .dockerignore << 'EOF'
# Dependencies — reinstalled inside the image
node_modules/
npm-debug.log*
yarn-debug.log*

# Secrets — must never reach an image layer
.env
.env.*
!.env.example
*.pem
*.key
*.p12
*.pfx
.npmrc

# Version control
.git/
.gitignore
.gitattributes

# IDE and OS artefacts
.vscode/
.idea/
*.swp
.DS_Store
Thumbs.db

# Test artefacts
coverage/
.nyc_output/
__tests__/
*.test.js
*.spec.js

# Docker config (no need inside the image)
Dockerfile*
docker-compose*.yml
.dockerignore

# Documentation
*.md
docs/

# CI/CD config
.github/
.gitlab-ci.yml
Jenkinsfile
EOF

Measure the build context before vs after:

# Build with verbose output to see context size
DOCKER_BUILDKIT=1 docker build --progress=plain --target production -t myapp:production . 2>&1 \
  | grep "transferring context"

Expected output:

#1 transferring context: 38.4kB 0.1s done

Without .dockerignore that number would be ~180 MB (dominated by node_modules).

Part 5: Docker Compose for local development

Development needs hot reload, all devDependencies, and live-mounted source. Production needs read-only filesystem, dropped capabilities, and resource limits. These are different Compose files.

%%{init: {'theme': 'dark'}}%%
flowchart TD
    subgraph DEV ["docker-compose.yml  ·  Development"]
        DH["Browser / curl\nlocalhost:3000"]:::host
        DC["myapp:dev\nnode:20-alpine + nodemon"]:::dev
        DV[("node_modules\nnamed volume")]:::vol
        DS[("./src  bind mount\nread-only into container")]:::vol
        DH -->|"port 3000:3000"| DC
        DC --> DV
        DC <-->|"file changes trigger reload"| DS
    end

    subgraph PROD ["docker-compose.prod.yml  ·  Production-like"]
        PH["Browser / curl\nlocalhost:3000"]:::host
        PC["myapp:production\ndistroless · nonroot"]:::prod
        PT[("tmpfs: /tmp\nread-only filesystem")]:::vol
        PH -->|"port 3000:3000"| PC
        PC --> PT
    end

    classDef host fill:#1c2128,stroke:#30363d,color:#8b949e
    classDef dev fill:#1a2744,stroke:#58a6ff,color:#e6edf3
    classDef prod fill:#0d2818,stroke:#3fb950,color:#3fb950
    classDef vol fill:#1f2210,stroke:#d29922,color:#d29922

docker-compose.yml — development:

version: '3.9'

services:
  app:
    build:
      context: .
      dockerfile: Dockerfile
      target: deps
    image: myapp:dev
    container_name: myapp-dev
    restart: unless-stopped
    ports:
      - "3000:3000"
    volumes:
      - ./src:/app/src:ro
      - node_modules:/app/node_modules
    environment:
      NODE_ENV: development
      PORT: 3000
    command: ["node_modules/.bin/nodemon", "--watch", "src", "src/index.js"]
    healthcheck:
      test:
        - CMD
        - node
        - -e
        - "require('http').get('http://localhost:3000/health', r => process.exit(r.statusCode===200?0:1)).on('error',()=>process.exit(1))"
      interval: 30s
      timeout: 10s
      retries: 3
      start_period: 15s

volumes:
  node_modules:

docker-compose.prod.yml — production-like local testing:

version: '3.9'

services:
  app:
    build:
      context: .
      dockerfile: Dockerfile
      target: production
    image: myapp:production
    container_name: myapp-prod
    restart: unless-stopped
    ports:
      - "3000:3000"
    environment:
      NODE_ENV: production
      PORT: 3000
    read_only: true
    tmpfs:
      - /tmp
    security_opt:
      - no-new-privileges:true
    cap_drop:
      - ALL
    deploy:
      resources:
        limits:
          cpus: '0.50'
          memory: 256M
        reservations:
          cpus: '0.10'
          memory: 64M

Start development:

docker compose up --build

Expected output:

[+] Building 19.3s (11/11) FINISHED
[+] Running 2/2
 ✔ Volume "docker-best-practices_node_modules"  Created
 ✔ Container myapp-dev                          Started
myapp-dev  | [nodemon] 3.0.2
myapp-dev  | [nodemon] watching path(s): src/**/*
myapp-dev  | Server running on port 3000 [development]

Test hot reload without rebuilding:

# In a second terminal
sed -i 's/"healthy"/"all-systems-go"/' src/routes/health.js

# Watch the container log — nodemon restarts automatically
# Then verify the change
curl -s http://localhost:3000/health | grep status
# {"status":"all-systems-go",...}

# Revert
sed -i 's/"all-systems-go"/"healthy"/' src/routes/health.js

Stop and clean up:

docker compose down -v   # -v also removes named volumes

Part 6: Docker Scout vulnerability scan

Compare both images side by side:

# Naive image — expect many CVEs
echo "=== naive image ===" && \
docker scout cves myapp:naive --only-severity critical,high --format table 2>/dev/null | head -30

echo ""

# Production image — expect zero
echo "=== production image ===" && \
docker scout cves myapp:production --only-severity critical,high 2>/dev/null

Expected output:

=== naive image ===
  CRITICAL CVE-2023-38545  curl/libcurl4  ...
  HIGH     CVE-2024-0727   openssl        ...
  HIGH     CVE-2023-44487  nghttp2        ...
  ... (30+ vulnerabilities) ...

=== production image ===
    ✓ Analyzed image myapp:production
    No critical or high vulnerabilities found

Run a full comparison:

docker scout compare myapp:production --to myapp:naive

Expected output:

Comparing myapp:production to myapp:naive

Image reference: myapp:production

Changes:
  ✓ Critical vulnerabilities:  0  (-3)
  ✓ High vulnerabilities:      0  (-12)
  ✓ Medium vulnerabilities:    0  (-18)
  ✓ Low vulnerabilities:       0  (-14)
  ✓ Image size:                47.2 MB  (-1.17 GB)

Part 7: The reusable template

mkdir -p docker-template
cp Dockerfile docker-template/
cp .dockerignore docker-template/
cp docker-compose.yml docker-template/
cp docker-compose.prod.yml docker-template/
cp .env.example docker-template/

cat > docker-template/bootstrap.sh << 'SCRIPT'
#!/bin/bash
set -euo pipefail

APP="${1:-myapp}"

echo "Bootstrapping Docker setup for: $APP"

# Preflight checks
command -v docker  >/dev/null || { echo "Docker not found"; exit 1; }
docker info &>/dev/null      || { echo "Docker daemon not running"; exit 1; }

# Create .env from example if missing
[ ! -f .env ] && [ -f .env.example ] && cp .env.example .env && \
  echo "Created .env from .env.example — update before production use"

echo "Building dev image..."
DOCKER_BUILDKIT=1 docker build --target deps --tag "${APP}:dev" .

echo "Building production image..."
DOCKER_BUILDKIT=1 docker build --target production --tag "${APP}:production" .

echo ""
echo "=== Image sizes ==="
docker images | grep "$APP"

echo ""
echo "Ready."
echo "  Development:   docker compose up"
echo "  Production:    docker compose -f docker-compose.prod.yml up"
echo "  Scan:          docker scout cves ${APP}:production"
SCRIPT

chmod +x docker-template/bootstrap.sh

How it works under the hood

Why multi-stage builds achieve such dramatic size reduction

Docker images are a stack of layers. Every instruction adds a layer — and layers can only be added, never removed, in a single-stage build. Even if you run RUN rm -rf /build-tools after installing them, those files still exist in the lower layer; the removal just adds a new layer that marks them as deleted. The final image carries every byte from every layer.

Multi-stage builds escape this entirely. The deps stage can install gcc, python, and every native build tool it needs to compile npm packages. The production stage uses COPY --from=deps to lift only the finished node_modules directory out. The build tools never touch the production stage.

Why the order of COPY matters for build speed

Every layer is cached. When a layer changes, Docker rebuilds it and every layer after it. Copy order determines how often the expensive npm ci step gets skipped.

%%{init: {'theme': 'dark'}}%%
flowchart LR
    CHANGE(["src/index.js\nchanged"]):::src

    subgraph WRONG ["❌  Slow — cache busted on every change"]
        W1["COPY . ."]:::bad --> W2["RUN npm install\nre-runs every build"]:::bad --> W3["Ready"]:::neutral
    end

    subgraph RIGHT ["✓  Fast — npm ci stays cached"]
        R1["COPY package*.json"]:::good --> R2["RUN npm ci\ncached until deps change"]:::good --> R3["COPY src/\nonly this re-runs"]:::good --> R4["Ready"]:::neutral
    end

    CHANGE -->|"+45 sec"| WRONG
    CHANGE -->|"+2 sec"| RIGHT

    classDef src fill:#1a2744,stroke:#58a6ff,color:#e6edf3
    classDef bad fill:#2d1215,stroke:#f85149,color:#f85149
    classDef good fill:#0d2818,stroke:#3fb950,color:#3fb950
    classDef neutral fill:#1c2128,stroke:#30363d,color:#8b949e

Copy only package.json and package-lock.json first, run npm ci, then copy source. Now npm ci only reruns when your dependency manifest changes. Source code changes are a fast copy operation.

Why distroless instead of Alpine

Alpine Linux (~5 MB) is the standard lightweight base. It’s a real improvement over node:20 (1.1 GB). But Alpine still contains a shell (ash), a package manager (apk), and standard Unix utilities. If an attacker achieves remote code execution in your container, they have a complete Unix environment to work with.

Distroless contains none of that. The gcr.io/distroless/nodejs20-debian12 image contains: the Debian C library, the Node.js binary, and nothing else. No bash. No sh. No curl. No wget. An attacker who gets RCE can only execute your Node.js binary — there are no other tools available. The attack surface reduction is measurable. The trade-off is debugging: docker exec mycontainer bash won’t work. Add a debug stage to your Dockerfile for development use.

Why exec form CMD matters for signal handling

CMD node src/index.js is shell form. Docker wraps it as /bin/sh -c node src/index.js. Your Node process runs as a child of /bin/sh, not as PID 1. When Kubernetes or Docker sends SIGTERM to stop your container, it sends it to PID 1 — the shell. The shell may or may not forward the signal. Your graceful shutdown handler may never fire. Connections get dropped mid-request. Databases get dirty disconnects.

CMD ["/nodejs/bin/node", "src/index.js"] is exec form. Node becomes PID 1 directly. SIGTERM reaches your process.on('SIGTERM') handler reliably. Graceful shutdown works as designed.

Common errors and fixes

Error 1: npm ci fails — missing: express@^4.18.2

npm error missing: express@4.18.2, required by myapp@1.0.0

Cause: package-lock.json is out of sync with package.json, or package-lock.json was not committed.

Fix:

# Regenerate the lockfile
rm package-lock.json
npm install
git add package-lock.json
git commit -m "chore: regenerate package-lock.json"

# Now rebuild
docker build --target production -t myapp:production .

Error 2: Container exits immediately — no output

docker run myapp:production
# (exits instantly, no logs)

Cause: Shell form CMD in a distroless image. There is no shell to parse it.

Fix: Use exec form (array syntax) and the correct Node path for distroless:

# Wrong — shell form, silently fails in distroless
CMD node src/index.js

# Correct — exec form with distroless node path
CMD ["/nodejs/bin/node", "src/index.js"]

Verify the correct node path in the distroless image:

docker run --rm gcr.io/distroless/nodejs20-debian12 \
  /nodejs/bin/node --version
# v20.x.x

Error 3: COPY --from=deps results in empty node_modules

Error: Cannot find module 'express'

Cause: WORKDIR differs between stages, or the path in COPY --from doesn’t match.

Fix: Ensure WORKDIR is identical in all stages and COPY path is absolute:

FROM node:20-alpine AS deps
WORKDIR /app                          # ← must be /app
RUN npm ci --omit=dev

FROM gcr.io/distroless/nodejs20-debian12 AS production
WORKDIR /app                          # ← same: /app
COPY --from=deps /app/node_modules ./node_modules   # ← full path from deps

Error 4: Hot reload not working on Linux

[nodemon] watching: src/**/*
# (file changes have no effect)

Cause: Docker on Linux doesn’t propagate inotify events into containers by default in some configurations.

Fix: Switch nodemon to polling mode:

# Update the command in docker-compose.yml
command: ["node_modules/.bin/nodemon", "--legacy-watch", "--watch", "src", "src/index.js"]

Or add nodemon.json to the project root:

{
  "watch": ["src"],
  "ext": "js,json",
  "legacy-watch": true,
  "delay": 500
}

Error 5: Build context is 850 MB despite .dockerignore

=> transferring context: 850.00MB

Cause: .dockerignore is in the wrong location, not saved, or the node_modules/ line has a typo.

Fix:

# Confirm .dockerignore exists in the build context directory
ls -la .dockerignore

# Check the node_modules line is correct (no trailing space)
grep "node_modules" .dockerignore
# node_modules/

# Test: measure context size with a dry run
DOCKER_BUILDKIT=1 docker build --progress=plain --target deps . 2>&1 \
  | grep "transferring context"
# Should show < 100kB

Error 6: docker scout permission denied

Error response from daemon: permission denied while trying to connect

Cause: User not in the docker group, or group change not applied to current session.

Fix:

sudo usermod -aG docker $USER
newgrp docker

# Verify
groups | grep docker

# Test
docker scout version

What’s next — extend this project

1. Wire this into a full CI pipeline. Day 4 of this series builds a GitHub Actions workflow that builds your Docker image, runs the test stage as a CI gate, scans with Docker Scout, and pushes to GitHub Container Registry — automatically on every PR.

2. Add multi-platform builds for ARM. AWS Graviton2/3 instances and Apple Silicon both run ARM64. Build once for both architectures:

docker buildx create --name multibuilder --use
docker buildx build \
  --platform linux/amd64,linux/arm64 \
  --target production \
  --tag ghcr.io/syssignals/myapp:latest \
  --push \
  .

1. Add a debug target. Distroless has no shell, which is the point — but debugging a production issue is hard without one. Add a debug stage that includes busybox:

FROM gcr.io/distroless/nodejs20-debian12:debug AS debug
WORKDIR /app
COPY --from=deps /app/node_modules ./node_modules
COPY src/ ./src/
COPY package.json ./
CMD ["/nodejs/bin/node", "src/index.js"]

Build with --target debug when you need a shell for investigation. Never ship this tag.

Day 2 recap

You now have:

• A working multi-stage Dockerfile that reduces image size by 96% (1.21 GB → 47 MB)
• A distroless production image with zero critical or high CVEs
• A non-root runtime (uid 65532) that can’t escalate privileges
• A .dockerignore that reduces build context from 180 MB to 38 KB
• A Docker Compose dev setup with hot reload working in under 2 seconds
• A production Compose override with read-only filesystem and dropped capabilities
• Scan output proving the security improvement with Docker Scout

The difference between a working Docker image and a production-grade one is everything you leave out.

Day 3 preview

Day 3: Docker Compose for a full local dev environment

Full local dev environment: Node.js app + PostgreSQL + Redis + Nginx reverse proxy. Health checks, named volumes, environment variable injection, and service dependency ordering. The docker compose up your team actually deserves.

This is Day 2 of the 30 Days of DevOps series.
Follow @syssignals on X — Day 3 drops tomorrow.
Found a command that doesn’t work? Reply on X with your OS and Docker version.