DEV Community: Agustín Rodríguez

The Life Has No Shortcuts. VS Code Has Too Many.

Agustín Rodríguez — Fri, 13 Feb 2026 01:51:20 +0000

Every time you install a VS Code extension, something quiet happens in the background: new keyboard shortcuts show up. Nobody tells you. Nobody asks if you want them. They just appear, silently overriding what was there before.

One day you press Ctrl+Shift+P and something unexpected runs. Or Cmd+D stops doing what it used to. You check your keybindings and find a mess - ten extensions fighting over the same keys, and you never chose any of them.

Why should an extension decide what my keyboard does?

🎹 The invisible problem

Keyboard shortcuts are muscle memory. They're personal. You build them over months and years of work, and they become part of how you think while coding.

But VS Code treats extension shortcuts as equals to your own. They land in the same space, with the same priority, and they accumulate silently. The more extensions you install, the more your keyboard belongs to someone else's defaults.

Most developers don't notice until something breaks. And by then, it's hard to know what changed, when, or why.

🧩 Why I built Harmonia Shortcuts

I wanted a simple answer to a simple question: which extension shortcuts am I actually using?

Not a keybinding editor. Not a conflict resolver with complex rules. Just a way to see every shortcut that extensions added to my environment, and decide - one by one or in bulk - whether I want them active.

That's what Harmonia Shortcuts does. It reads every extension's contributed keybindings, shows them grouped by extension, and lets you:

Approve the ones you want to keep.
Deactivate the ones that get in your way.
Remap the ones you like but want on a different key.
Skip the ones you'll decide about later.

No automation. No heuristics. No "smart" decisions made on your behalf. Just you, your shortcuts, and a clear interface to review them.

🔒 Your shortcuts are sacred

Harmonia never touches your custom keybindings. They are read-only, always protected. The extension only manages what other extensions brought in - the shortcuts you never explicitly chose.

If two extensions compete for the same key, Harmonia shows the conflict and lets you resolve it. If an extension updates and adds new shortcuts, you get a notification so nothing slips through unreviewed.

Everything happens through keybindings.json using standard VS Code mechanisms. No magic, no hidden state.

🐾 Built in good company

This project was built during long coding sessions with my dog Honey by my side - the best coding partner I could have asked for. He listened to every idea, stayed up for every late night, and kept me company through every line of code. Honey passed away, but his presence is part of everything in this project.

✳️ Where to Find It

Harmonia Shortcuts is available now on the Visual Studio Code Marketplace.

✳️ A governance tool, not a productivity hack

Harmonia Shortcuts isn't about speed or optimization. It's about intention. It's a small, honest tool that gives you back something VS Code doesn't provide out of the box: the ability to consciously decide which shortcuts should be active in your environment.

The life has no shortcuts. But your editor should only have the ones you chose.

Coding in Peace - The Story Behind Harmonia Zen

Agustín Rodríguez — Sat, 31 Jan 2026 05:01:20 +0000

How the pursuit of distraction-free coding led me to build an extension that respects both your focus and your preferences.

The Distraction Problem

Every developer knows the feeling. You're deep in a complex problem, the logic is finally clicking into place, and then... a notification. A sidebar catches your eye. The minimap reminds you of that other bug you meant to fix. Your flow is broken.

VS Code's built-in Zen Mode was supposed to solve this. Toggle it on, and the UI disappears. But I found myself frustrated by its all-or-nothing approach. Sometimes I need line numbers. Sometimes I want the minimap but not the sidebar. The binary choice felt limiting.

The Control I Wanted

I started keeping notes on my ideal setup for different tasks:

Deep debugging: Keep line numbers and gutter, hide everything else
Writing documentation: Minimal interface, but keep the scrollbar for navigation
Quick edits: Almost everything visible for context
Long coding sessions: Just the essentials, plus something to structure my time

That last point led me to the Pomodoro Technique. I'd been using it for years with external timers, but context-switching to another app always felt like a small interruption in itself.

What if my editor could handle both? A truly customizable Zen Mode, plus a built-in timer that understands the rhythm of focused work?

Building Harmonia Zen

The core idea was simple: give developers granular control over their environment.

Instead of one Zen Mode toggle, Harmonia Zen offers 17 individual controls:

Editor elements: Line numbers, gutter, minimap, breadcrumbs, indent guides, bracket pairs, rulers
Scrollbars: Vertical and horizontal separately
Workbench: Activity bar, status bar, sidebar, panel, tabs
Behavior: Cursor blinking, whitespace rendering, line highlighting

Each one can be toggled independently. Your preferences are remembered. And when you exit Zen Mode, your original settings come back exactly as they were.

Preset Profiles

But remembering 17 toggles for different scenarios? That's its own cognitive load.

So I built presets:

Preset	Philosophy
Minimal	Everything hidden. Pure text and thought.
Writer	Clean but navigable. Good for prose and documentation.
Focus	Keep the coding aids (line numbers, indent guides), hide the distractions.
Custom	Save your own configuration and recall it instantly.

Switch between them with a single click. No friction.

The Pomodoro Integration

The Pomodoro Technique structures work into focused intervals (traditionally 25 minutes), followed by short breaks (5 minutes), with longer breaks after several sessions.

It's simple, but it works. The rhythm prevents burnout and keeps you aware of time passing.

I built the timer directly into the extension:

Visual indicator in the status bar showing time remaining
Session tracking so you know which interval you're on
Customizable durations because 25 minutes isn't right for everyone
Auto-start option for continuous flow without manual intervention

The timer respects your focus. No intrusive popups—just a status bar update when your session ends.

Focus Statistics

After using the timer for a while, I wanted to understand my patterns. When am I most productive? Am I consistent?

Harmonia Zen tracks:

Daily sessions and focus time
Current streak and longest streak
Weekly overview with visual charts
All-time cumulative statistics

It's not about gamification or pressure. It's about self-awareness. Some days I notice I've only completed two sessions—maybe it was a meeting-heavy day, or maybe I need to be more intentional tomorrow.

All data is stored locally. No cloud sync, no analytics, no telemetry. Your productivity data stays yours.

What I Hope You Get From It

If you've ever wished Zen Mode was more flexible, or if you've bounced between different Pomodoro apps looking for one that integrates with your workflow, Harmonia Zen might help.

It's not about forcing a specific productivity system on you. It's about giving you the controls to create the environment that works for your brain.

Some developers like minimal interfaces. Some need more context visible. Some thrive with strict time boundaries. Some prefer flowing without interruption. Harmonia Zen tries to accommodate all of these.

Privacy by Design

Like all Harmonia extensions, privacy is non-negotiable:

No telemetry or analytics
No external communication
All settings and statistics stored locally in VS Code
Open source under MIT license

Your focus is yours. Your data is yours.

Where to Find It

Harmonia Zen is available now on the Visual Studio Code Marketplace.

Thanks for Reading

We spend countless hours in our code editors. Making that environment comfortable, focused, and personalized feels like time well invested.

If you try Harmonia Zen, I'd love to hear how it fits into your workflow. What presets work for you? What Pomodoro durations feel right? Feedback helps shape future improvements.

Code in peace.

Cover image credit: Levi XU, via Unsplash

From Glasses to Code - The Personal Journey Behind Harmonia Vision

Agustín Rodríguez — Sun, 18 Jan 2026 22:36:51 +0000

After almost a decade wearing glasses for myopia and astigmatism, I built an extension that finally understands what my eyes need.

The Day Everything Changed

It was mid-2016 when I first put on glasses. Myopia and astigmatism - two words that would become permanent companions in my life as a developer.

I still remember that first moment of clarity. The world suddenly had edges again. Text on screens was crisp. But I also discovered something frustrating: the default settings in my code editor weren't designed with my eyes in mind.

The Endless Tweaking

Over the years, I developed a habit. Every time I set up a new machine or switched editors, I'd spend time adjusting font sizes, trying different fonts, playing with line heights. It was a ritual - sometimes taking hours to feel "right."

But it was always guesswork. How big should the font be? Should I increase line spacing? Why does this font feel blurry even at larger sizes?

I never had clear answers. Just trial and error, over and over.

From Harmonia Theme to Harmonia Vision

When I built Harmonia Theme, my focus was on colors - reducing visual noise, creating a calm palette that wouldn't strain my eyes during long sessions.

But colors are only half the story.

Typography matters just as much. For someone with astigmatism, letters that are too close together blur into each other. For someone with myopia, small text means constantly leaning toward the screen. And eye fatigue compounds everything.

I realized I needed something more systematic. Something that understood the why behind each adjustment, not just the what.

Understanding My Own Eyes

I started researching how different vision conditions affect screen readability:

Myopia makes distant objects blurry - on a screen, this translates to needing larger text to maintain a comfortable viewing distance.
Astigmatism causes light to scatter irregularly, making closely-spaced characters blur together - increased letter spacing helps.
Eye fatigue benefits from more vertical breathing room between lines.
Light sensitivity means high-contrast or heavy fonts can feel uncomfortable.

Each condition has its own needs. And when you have multiple conditions (like I do), they interact in complex ways.

Building the Calibrator

Harmonia Vision started as a simple idea: what if my editor could understand my prescription?

I built a calibration engine that considers:

Which conditions you have - select one or multiple from a list.
Your actual prescription values - sphere and cylinder, if you want precise recommendations.
Your current settings - as a baseline that recommendations won't go below.

The engine uses empirically-derived thresholds based on real comfort profiles.

When I ran the calibrator on my own setup, the results were eye-opening (pun intended). My manual settings after years of tweaking were:

Setting	My Manual Config
Font Size	18px
Line Height	0 (auto)
Letter Spacing	0
Cursor Width	1px

The extension analyzed my conditions and recommended:

Setting	Recommendation	Why
Font Size	19px	Slightly larger for sustained comfort
Line Height	1.6	Better line tracking with astigmatism
Letter Spacing	0.3px	Reduces character blur from astigmatism
Cursor Width	3px	Easier to track with myopia

The line height and letter spacing changes were things I'd never thought to adjust - but once I tried them, the difference was noticeable. Lines of code felt less cramped, and my eyes didn't have to work as hard to distinguish similar characters.

It was validating to see the algorithm suggest improvements I didn't even know I needed.

The Safe Apply Workflow

One thing I learned from years of tweaking: sometimes you make a change and it looks great... until it doesn't. Maybe the font is too big for your monitor. Maybe the line height feels wrong after an hour of coding.

So I built in a safety net:

Automatic snapshots of your settings before any change.
Live preview to test in real-time.
One-click revert to go back to your previous comfortable state.

No more digging through settings to remember what values you had before. Just click "Revert" and you're back.

Privacy by Design

Your prescription is personal medical information. I didn't want to build something that sent that data anywhere.

Harmonia Vision is completely local:

No telemetry or analytics.
Prescription values are used only for calculation, never stored permanently.
All settings live in your VS Code configuration.
The code is open source - you can verify every line.

What I Hope You Get From It

If you wear glasses, have eye strain, or just find yourself constantly tweaking editor settings - I built this for you.

It's not a replacement for proper eye care. Please see your optometrist regularly.

But it can help you find a starting point that actually considers your eyes, not just generic defaults designed for perfect vision.

A Decade Later

Almost ten years with glasses now. My prescription has changed a few times. My monitors have changed. My preferred themes have changed.

But the fundamental challenge remains: making text on screens comfortable for eyes that need a little help.

Harmonia Vision is my answer to that challenge. A small tool that applies what I've learned from years of adjusting, researching, and understanding my own vision.

I hope it helps your eyes as much as it helps mine.

Where to Find It

Harmonia Vision is available now on the Visual Studio Code Marketplace.

Thanks for Reading

Building developer tools that focus on accessibility and comfort feels meaningful to me. We spend so many hours looking at code - it should be as comfortable as possible.

If you try Harmonia Vision, I'd love to hear how it works for you. Especially if you have different vision conditions than mine - your feedback helps make it better for everyone.

Take care of your eyes.

Refactor Smart Today, Move Faster Tomorrow — Bonus Pack: 4 Lessons to Refactor Smarter

Agustín Rodríguez — Mon, 06 Oct 2025 18:29:58 +0000

Extra insights that make your refactors more strategic, collaborative, and sustainable

This Bonus Pack expands on everything we've covered so far with 4 focused lessons that address the people, process, and real-world constraints around refactoring.

Let's dive in.

🆕 Bonus 1 — When You Should Rewrite Instead of Refactor

Knowing when to let go and start over

Not every system deserves a refactor.

Sometimes the best move is to rebuild from scratch - but that decision should never be impulsive.

Red flags that suggest a rewrite is better:

No tests, no docs, nobody understands the code
Tech stack is outdated or unsupported
Bugs are symptoms of flawed architecture
Every change introduces 3 new bugs
You've already tried refactoring and failed

How to approach a rewrite responsibly:

Keep the business logic contract consistent
Build the new system next to the old one
Use feature flags or routing to slowly switch traffic
Mirror real data to test before cutting over
Remove the legacy system only when the new one is fully trusted

💡 Rewrites should be strategic, not emotional.

🆕 Bonus 2 — Refactoring in Teams

How to avoid stepping on each other and make the work collaborative

Refactoring as a team requires more than just splitting up files. You need shared direction, boundaries, and communication.

Tips to make it smooth:

Define clear scope and goals before anyone starts coding
Break work by responsibility, not line numbers
Use contracts or interfaces to reduce coupling between teammates' work
Set up PR templates to explain each change
Do a midpoint check-in before it's too late to adjust

Optional extras:

Use a shared kanban/board to track atomic refactor tasks
Write down agreed rules: naming, file structure, error handling

🧠 Don't just refactor code — refactor your collaboration.

🆕 Bonus 3 — The Printable Refactor Checklist

A step-by-step guide you can print or paste into Notion

Pre-Refactor

[ ] Do we have a clear why?
[ ] Are the goals measurable?
[ ] Are there existing tests or metrics?
[ ] Are stakeholders aware or involved?

Planning

[ ] Scope is defined
[ ] Strategy chosen (incremental, strangler, etc.)
[ ] Tools (CI, linters, test runners) are in place
[ ] Any risky parts flagged?

Execution

[ ] Each commit is purposeful
[ ] No behavior changed without reason
[ ] Tests updated along the way
[ ] Team is aware of changes in flow or interfaces

Aftermath

[ ] Cleanup done (flags, dead code, mocks)
[ ] Metrics re-evaluated
[ ] Docs updated
[ ] Lessons shared with the team

✅ Use this before every refactor.

🆕 Bonus 4 — Handling Pushback From Stakeholders

How to talk about refactors without sounding like a code snob

Refactors are often hard to "sell" to leadership or PMs. Here's how to translate value into their language.

Developer Speak	Stakeholder Language
"This code is unmaintainable"	"This slows down our delivery"
"We need to decouple this"	"This change is risky and expensive as-is"
"No tests, can't touch it"	"Without safety checks, we risk regressions"

Common objections:

❌ “Why fix something that works?”

✔️ “Because it's fragile, expensive, and slowing down progress.”

❌ “Won't this delay our release?”

✔️ “It's short-term cost for long-term speed and fewer bugs.”

❌ “Let's just patch it again.”

✔️ “Patches accumulate tech debt — we need a long-term fix.”

Refactoring is part of software health. Don't wait for things to break.

📌 Final Note: Refactoring Is a Head Start, Not a Free Ride

Refactoring doesn't eliminate maintenance — it just makes it manageable.

It gives you:

A cleaner foundation
Easier testing
Better boundaries
More confident teams

But it doesn't:

Freeze time
Prevent technical debt forever
Exempt you from good practices
Replace the need to update dependencies

🧠 Refactor smart today. Maintain smarter tomorrow.

📚 Series Index — Refactor Smart Today, Move Faster Tomorrow

A practical guide to refactoring without fear — from planning to validation.

1️⃣ Before You Touch a Line of Code

2️⃣ Plan Your Refactor Step by Step

3️⃣ Tools That Save You From Yourself

4️⃣ Refactoring Without Regret

5️⃣ After the Refactor: How to Know It Worked

✨ Bonus: 4 Lessons to Refactor Smarter (Not Harder)

Cover image credit: Luca Bravo, via Unsplash

Refactor Smart Today, Move Faster Tomorrow — Part 5: After the Refactor: How to Know It Worked

Agustín Rodríguez — Tue, 23 Sep 2025 18:43:21 +0000

Validation, Cleanup, and Wrapping Things Up Properly

You made it. The refactor is merged.

You didn't break production (hopefully).

Now what?

A refactor isn't truly done when the code is merged — it's done when you've validated its impact, cleaned up the mess, and learned from the process.

Let's go over what happens after the refactor.

✅ Validate That You Actually Improved Something

Compare your "before" and "after" metrics:

Metric	Before	After	Result
Test coverage	58%	85%	✅ Improvement
Average response time	600ms	320ms	✅ Faster
Cyclomatic complexity	18	7	✅ Cleaner logic
Bug reports/week	4	1	✅ More stable

If the results don't show improvement:

Re-evaluate the refactor goals
Check if you optimized the wrong thing
Or consider follow-up iterations

💡 Don't assume success — measure it.

🔍 Re-Test Everything One More Time

Now that it's in production or merged into main:

Run full test suites
Double-check edge cases
Monitor for logs, errors, anomalies
Verify integrations with other services

Optional: QA smoke tests or exploratory testing in staging environments.

🧹 Clean Up Technical Debris

During your refactor, you may have left behind:

Feature flags that are no longer needed
Deprecated functions
Temporary mocks or shims
Old config variables
Duplicated code (old + new logic)

Now's the time to remove the scaffolding.

💡 You built it safely — now you make it clean.

📚 Update Documentation

If your refactor introduced:

New public interfaces
New architectural conventions
Changed behavior (even subtle)
New environment/config requirements

...then update:

README files
Wiki pages or Confluence
Internal dev docs
Diagrams (if relevant)

🧠 Future-you (or your teammates) will thank you.

📣 Share Learnings With the Team

Whether your refactor was a solo mission or a team effort:

Do a quick retro or post-mortem
Share what worked (patterns, tools, strategies)
Document pitfalls or challenges
Leave suggestions for next time

💬 "Here's how I handled the legacy service and rolled it out safely" is gold for onboarding and reuse.

📦 Optional: Leave a Changelog or Migration Note

If your changes affect how others use the codebase, leave a clear, focused changelog with:

What changed
Why it changed
What to update
Any deprecated methods or structures
Links to examples or diffs

Even if it's just a comment in a PR or GitHub release notes, it saves a ton of time later.

🧠 Final Thought

A great refactor doesn't just clean code — it leaves the entire system healthier:

Faster
More stable
Easier to understand
Easier to extend
Safer to maintain

If you can say that about your project after a refactor, you did it right.

📚 Series Index — Refactor Smart Today, Move Faster Tomorrow

A practical guide to refactoring without fear — from planning to validation.

Cover image credit: Arnold Francisca, via Unsplash

Refactor Smart Today, Move Faster Tomorrow — Part 4: Refactoring Without Regret

Agustín Rodríguez — Tue, 16 Sep 2025 17:38:34 +0000

So you've got a plan, you've got tools, and you're ready to refactor.

This is where good intentions often go sideways.

Let's make sure your refactor doesn't turn into a rewrite you'll regret.

✅ Best Practices While Refactoring

1. Keep the System Green at All Times

Never let your tests stay red for too long. Every change should:

Keep the app working
Keep the test suite passing
Leave the code in a better state than before

💡 Broken code for more than a day = trouble ahead.

2. Small, Purposeful Commits

Break your refactor into atomic commits, each one:

Solves one thing
Is easy to understand
Is easy to revert

Bonus: Reviewing or debugging later becomes 10x easier.

3. Do Not Change Behavior Unless You Have To

Refactoring ≠ rewriting features. If the output or behavior changes, you need:

A reason
A test
A migration plan (if applicable)

🔍 The goal is to improve structure, not functionality — unless the behavior was already wrong.

4. Add Tests Before You Touch Untested Code

If you're about to refactor a method with zero tests:

Write tests first
Validate existing behavior
Then refactor

This way, you'll catch regressions instantly — and build trust in your changes.

5. Rename Things Intelligently

A good refactor often involves better naming — but don't get carried away.

Tips:

Rename only when it adds clarity
Avoid generic renames like Helper or Manager
Prefer domain language: DonationProcessor > ServiceHandler

Clear names are half the battle.

6. Make Invisible Progress

The best refactors go unnoticed by the end user.

No regressions
No broken flows
No "wait, why is this acting weird now?"

You can celebrate your refactor, but your product team shouldn't have to know it happened.

7. Document Complex Transitions

Some refactors introduce patterns, abstractions, or architectural shifts.

Leave breadcrumbs for future devs:

Inline comments (brief and useful)
Code examples in the README
GitHub issues or ADRs (Architecture Decision Records)
Migration guides (for APIs, configs, etc.)

🚨 Common Mistakes That Break Refactors

❌ 1. Refactoring Without Tests

You're walking blind. One wrong move and it's over.

❌ 2. Changing Everything at Once

This often leads to huge PRs that are impossible to review or roll back.

❌ 3. Focusing on Perfection

Perfect is the enemy of done. Refactor to improve, not to create utopia.

❌ 4. Forgetting to Communicate

If the team isn't aligned, your "clean code" might break their work.

❌ 5. Deleting Legacy Code Prematurely

Don't rip out old logic until the new one is 100% verified (and ideally, toggled off safely).

🧘‍♂️ Optional but Powerful: Use Feature Branches + PR Templates

Structure your PRs to be:

Reviewable in <15 mins
Linked to clear goals ("This PR isolates email logic from controller")
Labeled by type (refactor, chore, migration)

This avoids misunderstandings and makes your changes traceable.

📌 Summary

Refactoring isn't just about moving code — it's about moving with intention.

Keep these in mind:

Stay green (tests passing)
Work in small steps
Avoid changing behavior unless needed
Cover everything with tests
Communicate with the team
Celebrate clarity, not cleverness

📚 Series Index — Refactor Smart Today, Move Faster Tomorrow

A practical guide to refactoring without fear — from planning to validation.

Cover image credit: Mohammad Rahmani, via Unsplash

Refactor Smart Today, Move Faster Tomorrow — Part 3: Tools That Save You From Yourself

Agustín Rodríguez — Tue, 09 Sep 2025 17:47:01 +0000

Refactoring without tooling is like free climbing without a harness.

Yes, you can do it, but the chances of disaster increase with every step.

This part focuses on the tools that help you:

Catch mistakes early
Keep your code consistent
Detect broken logic or structure
Measure test coverage
Validate your progress continuously

Let's break it down by category.

🧹 Linters and Formatters: Keep it Clean, Automatically

Before you touch anything, set up tools that enforce style and catch basic issues.

Examples:

PHP: php-cs-fixer, PHP_CodeSniffer
JavaScript/TypeScript: ESLint, Prettier
Python: black, flake8

💡 Linters catch stuff like unused variables, bad formatting, unreachable code, etc.

Why it matters:

👉 They prevent you from reviewing whitespace in PRs and keep codebase consistent even if you refactor 20 files.

🧠 Static Analysis: See Problems Before They Happen

Static analyzers inspect your code without running it. They're great at finding:

Type mismatches
Unreachable code
Bad inheritance
Deprecated functions
Dangerous constructs

Examples:

PHP: PHPStan, Psalm, Rector
JS/TS: tsc --noEmit, SonarLint
Python: mypy, pylint

Why it matters:

👉 They give you an early warning system for logical bugs before runtime.

📏 Metrics and Quality: Understand Your Code's Shape

You can't improve what you don't measure. Tools like these give insight into:

Complexity per function/class
Code duplication
Coupling between modules
Files with too many responsibilities

Examples:

PHP: PHP Metrics, PHP Insights, PHP Mess Detector
JS: complexity-report, plato
CI plugins: Code Climate, SonarQube, etc.

Why it matters:

👉 Use them to prioritize your refactor targets — focus on the worst offenders first.

🧪 Tests and Coverage: Your Safety Net

No test, no refactor. Period.

Tests make sure your changes didn't break anything that used to work. They also help you refactor fearlessly — which is the entire point.

Make sure you have:

✅ Unit tests: Fast, focused, per module
✅ Integration tests: Do modules talk to each other correctly?
✅ Regression tests: Does the system still behave the same?

Use coverage tools to guide your testing:

PHP: Xdebug + PHPUnit, Infection (mutation testing)
JS: Jest --coverage, vitest, cypress for E2E
Python: coverage.py, pytest

Why it matters:

👉 If a module has no tests and you refactor it, you're flying blind.

🚦 Continuous Integration: Automate the Checks

A good CI setup runs your tests, linters, and checks on every push or PR.

This is your second parachute.

Useful CI/CD tools:

GitHub Actions
GitLab CI
CircleCI
Jenkins
Bitbucket Pipelines

A good pipeline should include:

✅ Linting
✅ Static analysis
✅ Tests
✅ Build (if applicable)
✅ Optional: visual diff, deploy preview, DB migration dry-run, etc.

🧯 Feature Flags (Optional but Life-Saving)

If your refactor affects live code paths, a feature flag system allows you to:

Deploy the code but disable it in production
Roll out to specific environments or users
Toggle back instantly if something goes wrong

Tools:

LaunchDarkly, Unleash, ConfigCat, or custom boolean flags in code

Why it matters:

👉 Gives you rollback safety without a full deploy.

📌 Suggested Tooling Stack Example (for a PHP+React project)

Area	Tool(s)
Linting (PHP)	`php-cs-fixer`, `PHP_CodeSniffer`
Linting (JS)	`ESLint`, `Prettier`
Static analysis	`PHPStan`, `tsc`
Test runner	`PHPUnit`, `Jest`, `React Testing Library`
Coverage	`Xdebug`, `jest --coverage`
Quality metrics	`PHP Insights`, `SonarQube`
CI/CD	`GitHub Actions` or similar
Feature toggles	Custom flags or service-based

✅ Takeaway

The right tools don't slow you down — they give you the confidence to go fast without breaking things.

Before you dive into your next refactor:

Automate what you can
Catch issues early
Make testing easy and visible
Let CI/CD do the boring stuff
Use tools to guide, not replace, your decisions

📚 Series Index — Refactor Smart Today, Move Faster Tomorrow

A practical guide to refactoring without fear — from planning to validation.

Cover image credit: Pankaj Patel, via Unsplash

Refactor Smart Today, Move Faster Tomorrow — Part 2: Plan Your Refactor Step by Step

Agustín Rodríguez — Wed, 03 Sep 2025 18:31:07 +0000

So, you've confirmed that your refactor is necessary.
Now it's time to plan it right — because a poorly scoped or unstructured refactor is a trap that can drain weeks of work and leave everything worse than before.

Let's break it down.

🎯 Choose the Right Strategy

There's no single "best" approach to refactoring, but here are common strategies — and when to use them:

1. Incremental Refactor (Recommended for Live Systems)

Refactor bit by bit, keeping the system functional at all times.

✅ Pros: Safe, gradual, easier to test
⚠️ Cons: Requires discipline and clear boundaries
✅ Best for: Actively used systems, critical codebases, or anything in production

2. Branch-based Refactor (When Changes Are Too Invasive)

Fork the code into a separate branch, refactor freely, and merge later.

✅ Pros: Total freedom to redesign
⚠️ Cons: Merge hell, risk of long-living branches, hard to keep in sync
✅ Best for: Isolated modules, internal tools, greenfield components

3. Strangler Fig Pattern (Great for Legacy Systems)

Wrap and slowly replace legacy logic, one endpoint or feature at a time.

✅ Pros: Legacy coexists with new code, safer evolution
⚠️ Cons: Requires architectural support (e.g., routing layers, boundaries)

🗂️ Control the Scope or You'll Never Finish

One of the biggest risks in a refactor is the infinite scope creep.
You touch one piece, which leads to another, and then another... and before you know it, it's a rewrite.

Avoid this by:

Defining clear boundaries — "Only refactor the email dispatch logic"
Having non-negotiable out-of-scope rules — "Don't rewrite the frontend now"
Splitting the work into atomic, testable steps

💡 Tip: Track tasks in a checklist. Treat each step like a mini-feature.

🧱 Pick an Architecture or Pattern (Don't Wing It)

Before you start moving code around, ask yourself:
What kind of structure are we aiming for?
Without a vision, you'll likely make it different, not better.

Examples:

Clean or Hexagonal architecture
Adapter pattern to swap external services
Strategy pattern to simplify logic by behavior
Service layer for reusable business logic
Ports and adapters to isolate frameworks

🧠 Refactor is not just renaming variables — it's about redesigning how things work internally.

📦 Stabilize Interfaces (Create Contracts)

Even during a refactor, some parts of your system can't change — external APIs, third-party expectations, or other modules still depending on them.

Define stable interfaces or DTOs (data transfer objects)
Keep method signatures consistent while you migrate under the hood
Use adapters to convert legacy format to the new one temporarily

This makes it easier to refactor one part without breaking everything else.

🚩 Use Feature Flags

If your refactor affects a feature that's already live, wrap the new version in a flag so you can:

Test it in staging
Gradually roll it out
Roll back instantly if needed

This adds safety — especially when combined with CI/CD pipelines.

🧪 Define a Refactor Testing Strategy

You need different levels of tests to support your refactor:

Unit tests for small modules
Integration tests for connections between modules
Regression tests to make sure nothing breaks
(Optional) Snapshots or visual diffs for UIs

🔍 Also, use coverage tools to find untested danger zones before you touch them.

🛠️ Checklist Before the First Commit

Before writing any code:

[ ] Refactor strategy selected (Incremental, Branch, Strangler)
[ ] Scope clearly defined and limited
[ ] Architectural target or pattern chosen
[ ] Interfaces/contracts stabilized
[ ] Feature flags planned (if needed)
[ ] Tests prepared or planned
[ ] Metrics defined (to validate results later)

📚 Series Index — Refactor Smart Today, Move Faster Tomorrow

A practical guide to refactoring without fear — from planning to validation.

Cover image credit: Chris Ried, via Unsplash

Refactor Smart Today, Move Faster Tomorrow - Part 1: Before You Touch a Line of Code

Agustín Rodríguez — Wed, 27 Aug 2025 16:21:04 +0000

👀 Do You Really Need a Refactor?

Sometimes we're tempted to refactor just because the code "looks ugly", but that's not always a good enough reason.
A solid refactor starts with a real, measurable need.

Here are signs that a refactor is truly worth the effort:

⚠️ One change breaks unrelated parts — butterfly effect everywhere
🔁 Duplicate logic all over the place
🧩 Code is hard to understand, even for the original author
🐌 Poor performance without obvious cause
❌ Low or no test coverage, making changes risky
🧱 Tightly coupled modules that prevent new features from being added
🤯 Huge functions doing 10 things at once

👉 When your codebase starts slowing you down, it's a clear sign that technical debt is taking its toll.

🎯 Define a Clear Goal

Refactoring is not a goal in itself. Ask yourself:

Are we doing this to improve performance?
Or to enable new features?
Reduce bugs?
Make code more testable?

🔍 Pick one or two primary objectives.
A refactor without a clear goal is just impulsive rewriting.

📊 Take a “Before” Snapshot

Before touching anything, capture some baseline metrics. You'll need these to prove the refactor was actually worth it. Examples:

Execution time or load time
Test coverage percentage
Number of reported bugs
Average dev time per feature
Class/service coupling indicators

💡 Even a simple comparison table can be powerful to demonstrate improvement post-refactor.

🤝 Talk to the Business

Technically, the code might scream "Refactor me!", but if business stakeholders don't see value, you'll face resistance or pressure to skip it.

Tips for making the case:

Translate it into risk: "this might fail in production if..."
Show future impact: "every new feature here takes 30% longer"
Sell it as an investment: "this will take 1 week and save 3 each month"

🚨 If you can't align with business goals, it might be better to postpone.

🧨 Evaluate the Risks!!!

Not all code is safe to touch. Some modules handle payments, email dispatch, automation, etc. Run a small internal risk audit:

Are there tests that cover this code?
How often is it used?
What happens if it fails?

✍️ Document the risks and decide if you need a rollback plan (feature flags, toggles, manual fallback, etc.).

🔒 Not Everything Needs Refactoring

Sometimes it's better to leave ugly but stable code alone than to risk breaking something that works fine.

✅ TL;DR — Your Refactor Pre-Flight Checklist

Before touching any code:

[ ] Know why you're refactoring
[ ] Define clear, measurable goals
[ ] Capture before-metrics
[ ] Talk to stakeholders
[ ] Understand the risks
[ ] Be ready with a fallback plan

📚 Series Index — Refactor Smart Today, Move Faster Tomorrow

A practical guide to refactoring without fear — from planning to validation.

Cover image credit: Mohammad Rahmani, via Unsplash

🎨 Making Long Coding Sessions More Pleasant — The Story Behind Harmonia Theme

Agustín Rodríguez — Fri, 15 Aug 2025 01:07:40 +0000

A good theme isn’t just a color palette — it’s a tool to protect your focus, reduce fatigue, and make your editor feel like home.

🧪 Why build a theme?

I’ve always enjoyed fine-tuning my development environment — from terminal fonts to keyboard shortcuts. But I could never quite settle on a theme that felt truly coherent, balanced, and comfortable for long hours of work.

So I decided to try something: build my own Visual Studio Code theme.

Not as a designer, but as a developer — out of curiosity, to learn, and to see how much impact a well-crafted theme could really have.

🌙 Dark, soft, and focused — that’s Harmonia

From the start, Harmonia had a clear goal: to be a dark, soft, visually consistent theme, especially tailored for web developers.

I focused on the languages and file types I use the most: PHP, JavaScript (and friends like TypeScript and JSX), JSON, config files, Docker, Apache, Nginx, and log files.

The idea was to highlight what matters without visual noise. A theme that feels calm and lets your code breathe.

🖌️ The color decisions

Instead of choosing flashy or high-contrast colors, I took a more subtle approach:
• Soft yet deep background: dark enough to reduce eye strain, but not harsh black.
• Readable, rich foreground: avoiding pure white or washed-out grays.
• Syntax colors with character — not chaos: strong enough to be useful, but not overwhelming.

Each color was tested and adjusted to feel consistent across different languages and syntaxes, without breaking the harmony of the overall palette.

👁️ Why colors matter

We spend countless hours looking at our editors. A bad theme can be a constant source of visual fatigue, even if you don’t realize it.

A well-balanced color scheme can help you:
• stay focused longer
• avoid headaches or eye strain
• actually enjoy the experience of coding a bit more

In my opinion, a theme is part of developer ergonomics. Just like a good chair or a calibrated monitor. You don’t notice the value — until you use one that’s actually well made.

🧠 What I learned along the way

Creating a theme is more technical than it might seem. I learned:
• how VS Code token scopes work
• how to group styles across languages and file types
• how to test palettes while keeping consistency
• how to package and publish to the VS Code Marketplace
• how to generate proper previews for other users to see what you see

It wasn’t hard — but it was detail-heavy.

And that made it fun.

⚠️ About updates

I work full-time, so updates may not come frequently — but I’ll continue improving Harmonia little by little, especially around the languages and tools I use most in web development.

That includes PHP, JS/TS, JSON, configs, Dockerfiles, and log files.

If time allows, I’d love to expand support for other languages and improve the theme’s scope coverage even more.

📦 Where to find it

Harmonia Theme is available now on the Visual Studio Code Marketplace.

🔗 Direct link to the extension
📸 Screenshots and changelog on GitHub

🙌 Thanks for reading

This was a small side project — but one that brought me a lot of satisfaction.

If it helps even one more developer feel a bit more comfortable during a long coding session, it was totally worth it.

And if you try it — I’d love to hear what you think.

Cover image credit: Pankaj Patel, via Unsplash

Blue-Green Deployment in a Local Environment with Docker

Agustín Rodríguez — Tue, 28 Jan 2025 17:07:10 +0000

Introduction

Blue-Green Deployment is a deployment strategy designed to minimize downtime and risks during application updates. This approach involves running two separate environments, Blue and Green, where one serves traffic (the active environment) while the other is idle or undergoing updates. Once the updates are validated in the idle environment, traffic is switched seamlessly, ensuring stability and minimizing disruptions.

In this guide, we demonstrate how to implement Blue-Green Deployment using Docker in a local environment with Laravel as the example application. This approach is tailored for educational purposes, offering a hands-on way to grasp the fundamentals of Blue-Green Deployment.

Why Docker for Blue-Green Deployment?

Docker provides an efficient way to isolate and simulate environments for Blue-Green Deployment in a local setup. Using Docker containers, you can create independent "Blue" and "Green" environments, test changes safely, and switch traffic between them.

This guide leverages Docker to:

Simulate real-world deployment behavior.
Visualize the Blue-Green Deployment process in an accessible way.
Replicate health checks and traffic routing, similar to setups on platforms like AWS ECS or Kubernetes.

While there are other ways to test deployments locally, this method focuses on simplicity and clarity, allowing developers to understand the strategy without the complexity of managing cloud infrastructure.

Why Test Locally?

Testing Blue-Green Deployment locally provides several benefits:

Safe debugging: Identify issues in deployment scripts without impacting production.
Replicating production workflows: Validate environment transitions, API integrations, and scheduled tasks.
Downtime-free testing: Switch traffic seamlessly between containers, ensuring smooth user experiences.
Hands-on learning: Gain a deep understanding of deployment strategies by observing their effects in real-time.

This local setup enables you to confidently refine deployment strategies before scaling them to production environments.

Demonstration Setup

For this demonstration, the following components are used:

Nginx: Acts as the reverse proxy to route traffic to the active environment.
Health checks: Monitor container readiness and decide when to switch traffic.
Laravel: Example application to visualize environment transitions.

The Vital Role of Health Checks in Blue-Green Deployment

One of the key components of this setup is the use of health checks. These checks continuously monitor the status of a container to determine if it is ready to handle traffic. Health checks are essential in Blue-Green Deployment, as they ensure stability and minimize risks during the transition between environments.

In this local setup, health checks play the following roles:
1. Simulating production behavior: Platforms like AWS ECS and Kubernetes rely heavily on health checks to determine if a service is operational. By defining health checks in our docker-compose.yml file, we replicate this behavior in a local environment, providing a close-to-real-world experience.
2. Automating deployment decisions: The deployment script uses health checks to decide whether traffic can be routed to the new environment. If a container fails its health checks, the script avoids switching traffic and triggers a rollback to maintain application availability.
3. Ensuring application readiness: Before switching traffic to a new environment, health checks validate that the new container is fully operational. This prevents downtime caused by incomplete deployments or application errors.

Health Check Configuration

healthcheck:
  test: ["CMD-SHELL", "curl -f http://localhost || exit 1"]
  interval: 30s
  timeout: 10s
  retries: 3
  start_period: 5s

test: Runs a command to check if the container is responding. In this case, it sends an HTTP request to the application and expects a successful response.
interval: Sets the frequency of health check execution.
timeout: Defines how long the health check can take before it’s considered a failure.
retries: Specifies the number of consecutive failures before the container is marked as unhealthy.
start_period: Allows a grace period for the container to fully initialize before health checks start.

Visual Representation of Blue-Green Deployment

Here’s a simplified diagram of the Blue-Green Deployment process:

+-------------------+                   +--------------------+
|                   |                   |                    |
|   Active (Blue)   |  <--- Traffic --->|    Idle (Green)    |
|                   |                   |                    |
+-------------------+                   +--------------------+
         ↑                                    ↑
         |                                    |
   Updates & Tests                     Updates & Tests
         |                                    |
         ↓                                    ↓
+-------------------+                   +--------------------+
|   New Green       |                   |   New Blue         |
|   Deployment      |                   |   Deployment       |
+-------------------+                   +--------------------+
         |                                    |
   Health Checks Passed              Health Checks Passed
         ↓                                    ↓
+-------------------+                   +--------------------+
|   Idle (Blue)     |   <--- Traffic ---|   Active (Green)   |
+-------------------+                   +--------------------+

Why Health Checks Are Critical

Health checks are the backbone of this Blue-Green Deployment strategy because they:

Prevent downtime: Only containers that pass health checks receive traffic, ensuring users are always directed to a functional environment.
Enable automated rollbacks: If a container fails its health checks, the script reverts to the previously active environment.
Promote confidence: By validating the readiness of the new environment, health checks reduce the risk of deploying faulty updates.

Components and Files

Here is an overview of the files used in this setup:

Deployment Script: Automates the creation, switching, and rollback of Blue-Green environments.

abin/install.sh

#!/bin/bash

set -e  # Stop script execution on error

NGINX_CONF_PATH="./docker/nginx/active_backend.conf"
NGINX_CONTAINER="app"
ENV_FILE=".env"

build_containers() {
    echo "📦 Building Docker containers..."
    docker compose build
    echo "✅ Docker containers built successfully."
}

prepare_nginx_config() {
    if [ ! -d "./docker/nginx" ]; then
        echo "📂 Nginx directory not found. Creating it..."
        mkdir -p ./docker/nginx
        echo "✅ Nginx directory created."
    fi
}

update_nginx_config() {
    local active_color=$1
    echo "🔄 Updating Nginx configuration to route traffic to '$active_color' containers..."

    cat > "$NGINX_CONF_PATH" <<EOL
upstream app_backend {
    server $active_color:9000 max_fails=3 fail_timeout=30s;
}
EOL

    echo "📋 Copying Nginx configuration to the container..."
    docker cp "$NGINX_CONF_PATH" "$NGINX_CONTAINER:/etc/nginx/conf.d/active_backend.conf"
    echo "🔁 Reloading Nginx to apply the new configuration..."
    docker exec "$NGINX_CONTAINER" nginx -s reload >/dev/null 2>&1
    echo "✅ Nginx configuration updated and reloaded successfully."
}

wait_for_health() {
    local container_prefix=$1
    local retries=5
    local unhealthy_found
    echo "⏳ Waiting for containers with prefix '$container_prefix' to become healthy..."

    while (( retries > 0 )); do
        unhealthy_found=false

        for container_name in $(docker ps --filter "name=$container_prefix" --format "{{.Names}}"); do
            health_status=$(docker inspect --format '{{if .State.Health}}{{.State.Health.Status}}{{else}}unknown{{end}}' "$container_name" || echo "unknown")
            if [[ "$health_status" != "healthy" ]]; then
                unhealthy_found=true
                echo "🚧 Container '$container_name' is not ready. Current status: $health_status."
            fi
        done

        if ! $unhealthy_found; then
            echo "✅ All containers with prefix '$container_prefix' are healthy."
            return 0
        fi

        echo "⏳ Retrying... ($retries retries left)"
        ((retries--))
        sleep 5
    done

    echo "❌ Error: Some containers with prefix '$container_prefix' are not healthy. Aborting deployment."
    rollback
    exit 0
}

rollback() {
    echo "🛑 Rolling back deployment. Ensuring the active environment remains intact."

    if [ -n "$PREVIOUS_COLOR" ]; then
        echo "🔄 Restoring CONTAINER_COLOR=$PREVIOUS_COLOR in .env."
        sed -i.bak "s/^CONTAINER_COLOR=.*/CONTAINER_COLOR=$PREVIOUS_COLOR/" "$ENV_FILE"
        rm -f "$ENV_FILE.bak"
        echo "✅ Restored CONTAINER_COLOR=$PREVIOUS_COLOR in .env."
    else
        echo "🚧  No previous CONTAINER_COLOR found to restore."
    fi

    if docker ps --filter "name=green" --format "{{.Names}}" | grep -q "green"; then
        echo "✅ Active environment 'green' remains intact."
        echo "🛑 Stopping and removing 'blue' containers..."
        docker compose stop "blue" >/dev/null 2>&1 || true
        docker compose rm -f "blue" >/dev/null 2>&1 || true
    elif docker ps --filter "name=blue" --format "{{.Names}}" | grep -q "blue"; then
        echo "✅ Active environment 'blue' remains intact."
        echo "🛑 Stopping and removing 'green' containers..."
        docker compose stop "green" >/dev/null 2>&1 || true
        docker compose rm -f "green" >/dev/null 2>&1 || true
    else
        echo "❌ No active environment detected after rollback. Manual intervention might be needed."
    fi

    echo "🔄 Rollback completed."
}

update_env_file() {
    local active_color=$1

    # check if .env file exists
    if [ ! -f "$ENV_FILE" ]; then
        echo "❌ .env file not found. Creating a new one..."
        echo "CONTAINER_COLOR=$active_color" > "$ENV_FILE"
        echo "✅ Created .env file with CONTAINER_COLOR=$active_color."
        return
    fi

    # backup previous CONTAINER_COLOR value
    if grep -q "^CONTAINER_COLOR=" "$ENV_FILE"; then
        PREVIOUS_COLOR=$(grep "^CONTAINER_COLOR=" "$ENV_FILE" | cut -d '=' -f 2)
        echo "♻️  Backing up previous CONTAINER_COLOR=$PREVIOUS_COLOR."
    else
        PREVIOUS_COLOR=""
    fi

    # update CONTAINER_COLOR value in .env
    if grep -q "^CONTAINER_COLOR=" "$ENV_FILE"; then
        sed -i.bak "s/^CONTAINER_COLOR=.*/CONTAINER_COLOR=$active_color/" "$ENV_FILE"
        echo "🔄 Updated CONTAINER_COLOR=$active_color in .env"
    else
        echo "CONTAINER_COLOR=$active_color" >> "$ENV_FILE"
        echo "🖋️ Added CONTAINER_COLOR=$active_color to .env"
    fi

    # remove backup file
    if [ -f "$ENV_FILE.bak" ]; then
        rm "$ENV_FILE.bak"
    fi
}

install_dependencies() {
    local container=$1
    echo "📥 Installing dependencies in container '$container'..."

    # Install Laravel dependencies
    docker exec -u root -it "$container" bash -c "composer install --no-dev --optimize-autoloader"
    docker exec -u root -it "$container" bash -c "mkdir -p database && touch database/database.sqlite"

    # Permissions setup
    docker exec -u root -it "$container" bash -c "chown www-data:www-data -R ./storage ./bootstrap ./database"
    docker exec -u root -it "$container" bash -c "chmod -R 775 ./storage ./bootstrap/cache"

    # Clear caches and run migrations
    docker exec -u root -it "$container" bash -c "php artisan cache:clear"
    docker exec -u root -it "$container" bash -c "php artisan config:clear"
    docker exec -u root -it "$container" bash -c "php artisan route:clear"
    docker exec -u root -it "$container" bash -c "php artisan view:clear"
    docker exec -u root -it "$container" bash -c "php artisan migrate --force"

    echo "✅ Dependencies installed and database initialized successfully in container '$container'."
}

deploy() {
    local active=$1
    local new=$2

    # Update .env before deploying
    update_env_file "$new"
    echo "🚀 Starting deployment. Current active environment: '$active'. Deploying to '$new'..."
    docker compose --profile "$new" up -d
    wait_for_health "$new"
    install_dependencies "$new"
    update_nginx_config "$new"
    echo "🗑️  Removing old environment: '$active'..."
    echo "🛑 Stopping '$active' containers..."
    docker compose stop $active >/dev/null 2>&1 || true
    echo "🗑️  Removing '$active' containers..."
    docker compose rm -f $active >/dev/null 2>&1 || true
    update_env_file "$new"
    echo "✅ Deployment to '$new' completed successfully."
}

get_active_container() {
    if [ -f "$ENV_FILE" ] && grep -q "CONTAINER_COLOR" "$ENV_FILE"; then
        grep "CONTAINER_COLOR" "$ENV_FILE" | cut -d '=' -f 2
    else
        echo ""
    fi
}

# Main script logic
prepare_nginx_config
build_containers

ACTIVE_COLOR=$(get_active_container)

if [ -z "$ACTIVE_COLOR" ]; then
    # if no active container found, deploy 'blue'
    echo "🟦 Initial setup. Bringing up 'blue' containers..."
    docker compose --profile blue up -d
    wait_for_health "blue"
    install_dependencies "blue"
    update_nginx_config "blue"
    update_env_file "blue"
elif [ "$ACTIVE_COLOR" == "green" ]; then
    # if the active is 'green', deploy 'blue'
    PREVIOUS_COLOR="green"
    deploy "green" "blue"
elif [ "$ACTIVE_COLOR" == "blue" ]; then
    # if the active is 'blue', deploy 'green'
    PREVIOUS_COLOR="blue"
    deploy "blue" "green"
else
    # if the active is neither 'green' nor 'blue', reset to 'blue'
    echo "🚧 Unexpected CONTAINER_COLOR value. Resetting to 'blue'..."
    PREVIOUS_COLOR=""
    docker compose --profile blue up -d
    wait_for_health "blue"
    install_dependencies "blue"
    update_nginx_config "blue"
    update_env_file "blue"
fi

echo "🎉 Deployment successful!"

Nginx Configuration: Handles traffic routing to the active environment.

nginx/default.conf

server {
    listen 80;
    index index.php index.html;
    client_max_body_size 20M;
    root /var/www/html/public;

    location / {
        try_files $uri $uri/ /index.php?$query_string;
    }

    location ~ \.php$ {
        fastcgi_pass app_backend;
        fastcgi_param SCRIPT_FILENAME $document_root$fastcgi_script_name;
        include fastcgi_params;
    }

    location ~ /\.ht {
        deny all;
    }
}

PHP-FPM Configuration: Manages PHP processes for Laravel.

php/www.conf

listen = 9000
user = www-data
group = www-data

[www]
pm = dynamic
pm.max_children = 20
pm.start_servers = 10
pm.min_spare_servers = 5
pm.max_spare_servers = 15

Dockerfile: Sets up the Laravel environment with required dependencies.

Dockerfile

FROM php:8.2.0-fpm
WORKDIR /var/www/html
RUN apt-get update && apt-get install -y \
    curl \
    dos2unix \
    git \
    libonig-dev \
    libpng-dev \
    libxml2-dev \
    libzip-dev \
    unzip \
    zip \
    libfcgi0ldbl \
    && apt-get clean && rm -rf /var/lib/apt/lists/* \
    && docker-php-ext-install pdo_mysql mbstring exif pcntl bcmath gd zip \
    && curl -sS https://getcomposer.org/installer | php -- --install-dir=/usr/local/bin --filename=composer \
    && mkdir -p /var/www/html/storage /var/www/html/bootstrap/cache && \
    chown -R :www-data ./bootstrap/cache && \
    mkdir -p storage && \
    cd storage/ && \
    mkdir -p logs && \
    mkdir -p app && \
    mkdir -p framework/sessions && \
    mkdir -p framework/views && \
    mkdir -p framework/cache && \
    chmod -R 775 framework logs app && \
    chown -R :www-data ./framework ./logs ./app && \
    git config --global --add safe.directory '*'

COPY ./scripts/start.sh /usr/local/bin/start.sh
RUN chmod +x /usr/local/bin/start.sh
CMD ["/usr/local/bin/start.sh"]

Docker Compose: Defines the Blue-Green containers, Nginx, and health check configurations.

docker-compose.yml

services:
  blue:
    container_name: blue
    env_file:
      - .env
    profiles:
      - blue
    build:
      context: ./docker
      dockerfile: Dockerfile
    volumes:
      - ./:/var/www/html
      - ./docker/supervisor/supervisord.conf:/etc/supervisor/supervisord.conf
      - ./docker/php/www.conf:/usr/local/etc/php-fpm.d/www.conf
    healthcheck:
      test: ["CMD-SHELL", "SCRIPT_FILENAME=/var/www/html/public/index.php REQUEST_METHOD=GET cgi-fcgi -bind -connect 127.0.0.1:9000 || exit 1"]
      interval: 30s
      timeout: 10s
      retries: 3
      start_period: 5s

  green:
    container_name: green
    profiles:
      - green
    env_file:
      - .env
    build:
      context: ./docker
      dockerfile: Dockerfile
    volumes:
      - ./:/var/www/html
      - ./docker/supervisor/supervisord.conf:/etc/supervisor/supervisord.conf
      - ./docker/php/www.conf:/usr/local/etc/php-fpm.d/www.conf
    healthcheck:
      test: ["CMD-SHELL", "SCRIPT_FILENAME=/var/www/html/public/index.php REQUEST_METHOD=GET cgi-fcgi -bind -connect 127.0.0.1:9000 || exit 1"]
      interval: 30s
      timeout: 10s
      retries: 3
      start_period: 5s

  app:
    image: nginx:alpine
    container_name: app
    profiles:
      - blue
      - green
    ports:
      - "${PORT-80}:80"
    volumes:
      - ./:/var/www/html
      - ./docker/nginx/default.conf:/etc/nginx/conf.d/default.conf
    healthcheck:
      test: ["CMD", "curl", "-f", "http://localhost"]
      interval: 30s
      timeout: 10s
      retries: 3
      start_period: 5s

Health Checks in Action

How It Works

When deploying updates:
- A new environment (Blue or Green) is started.
- Health checks validate the container’s readiness.
If health checks pass:
- Traffic is routed to the new environment.
- The old environment becomes idle, ready for future updates.
If health checks fail:
- A rollback is triggered, and the active environment remains unchanged.

Automated Rollback Example

The deployment script ensures a rollback occurs when health checks fail. For example:

Blue is active, and Green fails health checks.
Traffic remains routed to Blue.
The faulty Green container is removed, preserving application stability.

Examples:

🎥 Deployment demo: Visualizes the transition from Blue to Green.
🎥 Rollback demo: Demonstrates how rollbacks maintain stability when an update fails.

Conclusion

This guide demonstrates how to simulate and understand Blue-Green Deployment using Docker in a local environment. By leveraging health checks, traffic switching, and automated rollbacks, you can minimize downtime and ensure stability during deployments. While this approach is simplified, the concepts can easily extend to production-grade systems.

Use this setup to test and refine deployment strategies confidently before scaling to production.

Full code in this Repository

Cover image credit: Arnold Francisca, via Unsplash(https://unsplash.com/)

Understanding Technical Debt: An Ally and a Challenge in Software Development

Agustín Rodríguez — Sun, 10 Nov 2024 04:05:01 +0000

Technical debt is a common term in the world of software development, but for many, it remains a vague and sometimes intimidating concept. Is it something bad? Does it mean the code is poorly written? The reality is more nuanced. Much like financial debt, technical debt isn’t something to be ashamed of. Instead, it’s a tool that can help us move forward faster in our projects—as long as we manage it wisely.

What is Technical Debt?

Think of technical debt as those design and development shortcuts we sometimes take to deliver a product or feature faster. These decisions help us progress, but, just like financial debt, they come with “interest” that accumulates in the form of complexity, potential errors, and maintenance headaches down the road.

For example, imagine your team is under pressure to launch a new app quickly. You might decide to skip some unit tests or use a simplified database structure just to get the product out the door. It works for now, but those shortcuts might create future problems, making the code harder to understand, modify, or debug. Sound familiar? Many of us have been there, and that’s okay—as long as we have a plan to clean things up later.

Why Might It Be Necessary?

Let’s say your team is building a minimum viable product (MVP) and you’re racing against the clock to beat your competition to market. In these high-stakes moments, time is everything. The business needs to see results fast, validate the idea, attract customers, and start generating revenue. Here’s where technical debt becomes a strategic choice: you build something that works now, even if it’s not perfect, to grab that opportunity.

This isn’t just theory; it’s a reality for many startups and emerging companies. If you’re developing an e-commerce platform and you can roll out a basic payment feature in two days instead of spending two weeks on a perfect integration, you might choose speed. The key is knowing that you’ll need to revisit and improve that feature once you have the breathing room.

These decisions aren’t inherently bad. In fact, they can be what drives a company’s initial success. But you need to understand the trade-offs and have a strategy for dealing with those compromises later.

The Importance of “Paying” Technical Debt

Just like financial debt, technical debt needs to be paid off, or at least managed. If you keep ignoring it, the “interest” can pile up, making your system harder to maintain and slowing down your team’s ability to innovate. Here’s what that can look like:

Increased errors and failures: As your codebase grows, those quick-and-dirty solutions can start causing real problems. Bugs can spread more easily, and each change could have unexpected ripple effects.
Costly maintenance: Fixing bugs and adding new features takes longer. Developers might spend hours just trying to understand convoluted code before they can even begin making changes, driving up costs and slowing progress.
Talent loss: Working with messy, unmanageable code can be demotivating. Developers want to create, not constantly fight fires. If the frustration builds up, you might start losing valuable team members.
Plus, technical debt can hurt your company’s reputation. If users start experiencing frequent bugs or performance issues, their trust in your product can erode—and that can be devastating.

Impact on Innovation

Here’s a less obvious consequence: technical debt can stifle innovation. When your team is constantly patching up old problems or dealing with messy code, there’s less time and energy for brainstorming and developing new ideas. Companies that need to stay on the cutting edge can’t afford to have their innovation pipeline clogged by the past. Reducing technical debt frees up your team to focus on the future.

Project Lifecycle

Managing technical debt is not a one-size-fits-all approach. In the early stages of a project—like when you’re developing an MVP—it might make sense to take on more debt to move quickly. But as your product matures and gains stability, the focus should shift to paying off that debt. Think of it as adjusting your strategy as the project evolves, making sure the debt doesn’t turn into a long-term burden.

Prioritizing Technical Debt

Not all technical debt is equal. Some areas of your code might be critical, while others are less impactful. If a part of your application affects user experience or security, it should be a top priority. Taking a business impact approach helps you make smarter decisions about where to focus your refactoring efforts. Using project management tools to visualize and prioritize technical debt can also be a game changer.

Tracking Tools

Documenting and tracking technical debt is key to keeping it under control. Tools like Jira, Trello, or Notion let you log technical debt decisions, describe their impact, and set timelines for addressing them. This not only keeps the team on the same page but also shows stakeholders that you’re serious about maintaining code quality.

Investing in Quality Tools

To manage and reduce technical debt, investing in quality tools is a must. These tools help catch issues early and can be integrated into your workflow to prevent new problems.

For PHP: Tools like PHPStan, PHPMD, and PHP Metrics do a great job of analyzing code quality. PHPStan catches errors before they’re even run, PHPMD flags bad practices, and PHP Metrics provides complexity analysis.
For JavaScript and TypeScript:
- ESLint: This is a must-have for any JavaScript project. It can be configured to work seamlessly with TypeScript, catching more complex issues and ensuring clean code.
- Prettier: It’s just a code formatter, but having uniform code styling across your team can make a world of difference.
- JSHint: It’s not as popular in modern projects, but it’s still handy for older codebases or simpler setups.
- TypeScript: This is more than a tool—it’s a game changer. TypeScript’s static typing can catch errors before they become bugs, making your codebase safer and clearer. While many projects still use plain JavaScript, adopting TypeScript can be a smart move to reduce long-term debt. SonarQube: This tool works across multiple languages, including JavaScript, TypeScript, PHP, and more. It scans for security vulnerabilities, bugs, and other issues, giving you a clear view of your code quality.

Balancing with Team Productivity

Balancing technical debt reduction with productivity is tricky. Spending too much time on refactoring can slow down business goals, but ignoring it can create bigger problems later. One approach is to regularly schedule time for debt reduction without compromising key deliverables. It’s all about finding that sweet spot where you can address debt while still pushing forward.

Human and Motivational Aspects

Finally, let’s talk about the human side. Working with clean, maintainable code isn’t just about efficiency—it’s about team morale. Developers want to build and create, not feel bogged down by messy code. Addressing technical debt can boost motivation and make your team happier. A positive environment means better retention and a more energized team.

Conclusion

In the end, technical debt is a double-edged sword. It can accelerate progress when used wisely but become a serious liability if left unmanaged. The key is understanding that technical debt is part of the journey, not a failure. By making strategic decisions, investing in quality tools, and fostering a team culture that values maintainable code, you can leverage technical debt to your advantage while ensuring your projects remain sustainable and scalable in the long run.

So, don’t fear technical debt—manage it, plan for it, and use it as a tool to keep your projects moving forward. After all, the best codebase is one that balances short-term wins with long-term stability.

Cover image credit: Markus Spiske, via Pexels