Using Docker to Modernize a Legacy .NET System Without Touching the Monolith

Docker as a Compatibility Layer, Not a Rewrite Tool

Series: Modernizing a 15-Year-Old .NET System Without Breaking Production
Part 6 of 7

---

When teams hear “Docker modernization”, the instinct is often:

> “Let’s containerize the monolith.”

In a 15-year-old .NET system, that instinct is usually wrong.

This article explains how we used Docker as a compatibility layer to introduce new services—Kafka, event forwarders, schedulers, and background workers—without destabilizing the existing system running on IIS, shared databases, and internal networks.

Docker didn’t replace legacy infrastructure.
It coexisted with it.

1. Why We Did Not Dockerize the Monolith First

Containerizing the monolith looked attractive on paper:

• modern runtime
• reproducible environments
• simplified deployments

In reality, it introduced unacceptable risk.

Problems We Avoided

• Tight coupling to IIS and Windows services
• Complex filesystem dependencies
• Hidden assumptions about environment and paths
• Production-only behaviors that would be hard to reproduce

Most importantly: > Containerizing the monolith would have changed everything at once.

That violated our core rule: > Modernize incrementally and reversibly.

2. Docker’s Actual Role: Packaging New Things Safely

We used Docker to containerize only new components, such as:

• Kafka (dev/test)
• Event forwarder
• Outbox publisher
• Notification scheduler
• Background workers

These services:

• had no legacy baggage
• were stateless or near-stateless
• could fail independently
• could be rolled back instantly

Docker became a delivery tool, not an architectural goal.

3. docker-compose as the Integration Contract

Instead of complex scripts, we used docker-compose as the single source of truth for:

• service topology
• networking
• configuration
• local integration environments

This was critical for onboarding and debugging.

4. A Realistic docker-compose Setup

Below is a simplified (but realistic) example.

version: "3.9"

services:
  kafka:
    image: bitnami/kafka:3
    environment:
      KAFKA_CFG_ZOOKEEPER_CONNECT: zookeeper:2181
      KAFKA_CFG_ADVERTISED_LISTENERS: PLAINTEXT://kafka:9092
    ports:
      - "9092:9092"
    depends_on:
      - zookeeper

  zookeeper:
    image: bitnami/zookeeper:3
    environment:
      ALLOW_ANONYMOUS_LOGIN: "yes"

  event-forwarder:
    build: ./event-forwarder
    environment:
      ConnectionStrings__LegacyDb: ${LEGACY_DB}
      Kafka__BootstrapServers: kafka:9092
    depends_on:
      - kafka

  notification-worker:
    build: ./notification-worker
    environment:
      ConnectionStrings__LegacyDb: ${LEGACY_DB}
    depends_on:
      - kafka

Key point:

• SQL Server is not containerized initially
• The legacy DB is accessed externally

5. Connecting Containers to Legacy SQL Server

This was one of the most sensitive integration points.

On Windows / Mac

Docker provides:

host.docker.internal

So the connection string becomes:

Server=host.docker.internal;Database=LegacyDb;...

Why This Matters

• No DB duplication
• Same data as the legacy app
• Safe, observable behavior
• Zero schema drift

We accepted:

• slower local performance
• higher coupling

Because correctness mattered more.

6. Running Docker Alongside IIS Applications

In production and some dev environments:

• legacy app ran on IIS (host)
• new services ran in Docker

This hybrid setup was intentional.

Key Rules

• Containers never assumed ownership of ports used by IIS
• All communication used HTTP or Kafka
• No shared in-memory state
• Failures were isolated

The legacy app didn’t need to “know” Docker existed.

7. Environment Configuration Without Chaos

Legacy systems often rely on:

• config files
• environment variables
• registry settings
• secrets scattered everywhere

Docker forced discipline.

Pattern We Used

• .env for local values
• environment variables for containers
• no config files baked into images

Example:

LEGACY_DB=Server=host.docker.internal;Database=LegacyDb;User Id=...

This made environments:

• predictable
• reproducible
• easy to rotate

8. Volumes, File Shares, and Windows Pain Points

This is where theory meets reality.

Common Problems

• Permission errors on mounted volumes
• Line ending differences
• Path case sensitivity
• Timezone mismatches

Our Strategy

• Avoid shared volumes unless absolutely required
• Prefer database-backed communication
• Log to stdout whenever possible
• Use UTC everywhere

If file sharing was unavoidable:

volumes:
  - C:/shared:/app/shared

And document it explicitly.

9. Timezones and Clock Skew (Subtle but Dangerous)

Legacy apps often run in:

• local server time
• unspecified timezone assumptions

Containers default to UTC.

Rule We Enforced

• All new services use UTC
• All timestamps crossing boundaries are explicit
• No implicit conversions

This avoided:

• incorrect scheduling
• missed notifications
• time-based bugs that only appear in production

10. Health Checks and Failure Visibility

Docker makes failures visible — if you use it properly.

Example:

healthcheck:
  test: ["CMD", "curl", "-f", "http://localhost/health"]
  interval: 30s
  timeout: 5s
  retries: 3

We also:

• logged failures loudly
• avoided silent retries
• preferred crashing over hiding errors

A crashing container is easier to debug than a “healthy” one doing nothing.

11. Debugging Playbook (This Saved Us)

When something broke, we asked:

1. Can the container resolve DNS?
2. Can it reach the DB?
3. Can it reach Kafka?
4. Are ports exposed correctly?
5. Are clocks aligned?
6. Are logs visible?

Docker made these questions answerable quickly.

12. CI/CD Benefits (Unexpected but Huge)

Even before full container deployments, Docker gave us:

• consistent build environments
• repeatable integration tests
• fewer “works on my machine” issues

New services became:

• easier to test
• easier to deploy
• easier to reason about

All without touching the monolith.

13. What Docker Did Not Solve

Docker didn’t:

• clean legacy code
• fix poor architecture
• remove business complexity

And that’s fine.

Docker is not a silver bullet.
It is a lever.

14. Results and Trade-offs

What We Gained

• Isolation of new components
• Faster iteration
• Safer deployments
• Easier rollback
• Clearer system boundaries

What We Accepted

• Hybrid complexity
• More moving parts
• Need for documentation

That trade-off was worth it.

Final Thoughts

Docker was not our modernization goal.
It was our enabler.

By containerizing new services first, we:

• avoided risky rewrites
• respected existing stability
• created space for gradual change

That sequencing matters.

Modernization fails when teams try to change everything.
It succeeds when they change the right things, in the right order.

---

📘 Series navigation

⬅️ Previous:
Part 5 – Modernizing a Legacy Frontend Incrementally

➡️ Next:
Part 7 – The Real Challenges of Legacy Modernization