Your Docker Builds Are Slow Because You're Doing It Wrong (And I Built a Tool to Prove It)

Stop waiting 10 minutes for CI to rebuild everything when you change one line of code. Here's what's actually breaking your Docker layer cache."

. It's basically a tool that looks at your Dockerfile and tells you when you messed up.

(Also it was a good excuse to write some Go code. But mainly the other thing.)

How Docker Caching Actually Works (The 5-Minute Version)

So nobody really explains this when you're learning Docker. They just tell you to write a Dockerfile and good luck. But here's what's actually happening: every line in your Dockerfile creates a layer. These layers get cached. Which is great! Except the cache breaks super easily.

Best way I can explain it - imagine a stack of pancakes. (I'm hungry, don't judge.) Each line (FROM, RUN, COPY, whatever) is one pancake. Docker caches each pancake. So far so good.

But then. Here's where it gets annoying: if you change one pancake, Docker throws away that pancake plus every single pancake above it.

So like, if you change pancake 3, pancakes 3, 4, 5, 6, and 7 all get tossed. Only pancakes 1 and 2 stay cached.

This whole thing is called the "invalidation chain" and it's literally why your builds take forever.

The Cache-Killer Pattern

Here's the classic mistake everyone makes (including me for like 2 years):

FROM node:18

WORKDIR /app



COPY . .                    # Layer 1: Copy everything

RUN npm install             # Layer 2: Install dependencies

RUN npm run build           # Layer 3: Build



CMD ["node", "dist/server.js"]

Okay so what happens when you change src/index.js?

1. Layer 1 (COPY . .) sees something changed ❌


2. Cache = broken


3. Layer 2 (npm install) has to run again ❌


4. Layer 3 (npm run build) runs again too ❌

You literally just reinstalled 400 packages because you changed one file. And Docker's sitting there like "yep, seems right".

Meet LayerLint: The Dockerfile Linter You Didn't Know You Needed

So I've seen this same mistake approximately 47 times. Someone (usually me) puts COPY . . before npm install and then wonders why builds take forever. Eventually I just got annoyed enough to build something about it.

That's LayerLint.

What is it?

It's a static analysis tool I wrote in Go. You point it at your Dockerfile, it reads through it and goes "yo, this is gonna be slow". Doesn't even need to build the image. Just looks at the file.

Why not use hadolint or whatever?

Hadolint is great for syntax stuff and general best practices. LayerLint is specifically focused on layer caching anti-patterns. The stuff that makes your builds slow. Different problem.

Think of it like having that one DevOps person who's always grumpy about Dockerfiles, except it runs instantly and won't send you passive-aggressive Slack messages.

The Walkthrough: Let's Break Some Stuff

Installation (Pick Your Poison)

There's like 3 different ways to install it depending on how paranoid you are:

The lazy way (this is what I use):

curl -sSL https://raw.githubusercontent.com/vviveksharma/layerLint/main/install.sh | sh

The "I don't trust random install scripts" way (fair enough):

# Grab the binary from releases

wget https://github.com/vviveksharma/layerLint/releases/latest/download/layerLint_Linux_x86_64.tar.gz

tar -xzf layerLint_Linux_x86_64.tar.gz

chmod +x layerlint

The "I'm gonna build it from source" way (respect):

git clone https://github.com/vviveksharma/layerLint

cd layerLint

make generate-build

The Scan

Let me use that bad Dockerfile from before:

FROM golang:1.22

WORKDIR /app

COPY . .

RUN go mod download

RUN go build -o server ./cmd/server

Now run LayerLint on it:

./layerlint scan --dockerfile Dockerfile

if you're curious.

The Real Win: Automation with GitHub Actions

Okay so finding issues is one thing. But the real win? Making it so nobody (including yourself in 3 months when you forget all this) can merge a bad Dockerfile.

Here's what you do. Add this to .github/workflows/docker-lint.yml:

name: Lint Dockerfile

on: [push, pull_request]



jobs:

  lint:

    runs-on: ubuntu-latest

    steps:

      - uses: actions/checkout@v3



      - name: Install LayerLint

        run: |

          curl -sSL https://raw.githubusercontent.com/vviveksharma/layerLint/main/install.sh | sh



      - name: Scan Dockerfile

        run: ./layerlint scan --dockerfile ./Dockerfile --fail-on-severity high

And boom. Now every PR gets checked automatically. Someone tries to merge a slow Dockerfile? CI says no. PR blocked. They gotta fix it first.

(Saved me from myself more times than I can count.)

Oh and LayerLint can output different formats if you need:

• 
  --format json if you're doing scripting stuff


• 
  --format sarif if you want it in GitHub's Security tab


• 
  --format html for when you need to show management something pretty

Real-World Example Workflows

I put some example workflows in the repo that you can just copy:

• 
  
  

  And this is actual time. Not theoretical. Real minutes you get back to:

  
  
  
  
  
  • Actually write code
  
  
  • Read docs (lol who am I kidding)
  
  
  • Get coffee
  
  
  • Scroll through Twitter/X or whatever we're calling it now
  
  
  • Take a walk
  
  
  • Pet your dog
  
  
  • Literally anything that isn't watching a progress bar slowly fill up
  
  
  
  
  

  
  
  
  Other Platforms (Because Not Everyone Uses GitHub)
  

  
  
  

  LayerLint works on whatever CI system you're using:

  
  
  

  GitLab CI:
  
  

  
  
  
  
  

  CODE Kopieren

  docker-lint:
  
    script:
  
      - curl -sSL https://raw.githubusercontent.com/vviveksharma/layerLint/main/install.sh | sh
  
      - ./layerlint scan --dockerfile Dockerfile
  
  

  
  
  
  
  
  
  
  

  CircleCI:
  
  

  
  
  
  
  

  CODE Kopieren

  - run:
  
      name: Lint Dockerfile
  
      command: |
  
        curl -sSL https://raw.githubusercontent.com/vviveksharma/layerLint/main/install.sh | sh
  
        ./layerlint scan --dockerfile Dockerfile
  
  

  
  
  
  
  
  
  
  

  Jenkins:
  
  

  
  
  
  
  

  CODE Kopieren

  sh 'curl -sSL https://raw.githubusercontent.com/vviveksharma/layerLint/main/install.sh | sh'
  
  sh './layerlint scan --dockerfile Dockerfile'
  
  

  
  
  
  
  
  
  
  

  More platforms in the to see how it's done.

  
  
  

  PRs welcome. If you find a caching anti-pattern that LayerLint misses, definitely add it. I'm sure there's stuff I haven't thought of. The Go parser stuff is pretty straightforward once you get into it.

  
  
  

  (First few times looking at the Dockerfile parser I was confused but it makes sense eventually.)

  
  
  

  
  
  
  Why I Built This
  

  
  
  

  Honestly? I got tired of:

  
  
  
  
  
  • Sitting around waiting for builds (so much time wasted)
  
  
  • Explaining the same Docker caching stuff over and over
  
  
  • Forgetting these rules myself and having to relearn them every few months
  
  
  • Watching our CI bill go up because of dumb mistakes (my manager wasn't happy about that one)
  
  
  
  
  

  So yeah. Built a tool that explains it for me. Now when someone asks I just go "run layerlint" and we're good. Plus I can share the repo instead of typing the same explanation in Slack for the 100th time.

  
  
  

  If this saves you 5 minutes a day, cool. If it saves your whole team hours every week? Even better. That's the goal.

  
  
  

  
  
  
  The Bottom Line
  

  
  
  

  Before:

  
  
  
  
  
  • Builds take forever
  
  
  • Burning through CI minutes (and money)
  
  
  • Everyone's annoyed
  
  
  • "Why is this so slow?" (nobody knows)
  
  
  
  
  

  After:

  
  
  
  
  
  • Builds are actually fast
  
  
  • Cache works like it's supposed to
  
  
  • CI catches bad Dockerfiles automatically
  
  
  • You get your time back
  
  
  
  
  

  The tool's free, it's open source, and it literally takes 30 seconds to run. So like... just try it? Worst case you wasted 30 seconds. Best case you save hours.

  
  
  

  I mean you've read this far, might as well give it a shot right?

  
  
  

  
  



• 
  All the rules:
  


• 
  Download page: github.com/vviveksharma/layerLint/releases
  

If it helps, star the repo maybe? If it doesn't help, open an issue and tell me what's broken.

Anyway. Go fix your Dockerfiles. Future you will be grateful.

MIT License. Built it because I got lazy and tired of explaining Docker caching.

Comments Section Starter

What's your worst Dockerfile horror story? I wanna hear it. Drop it in the comments.

Bonus points if it involved npm install in production or a 2GB Docker image for a hello world app.