Guides
Not just "how to write the command", but "what to do when things break". Original long-form troubleshooting and best-practice articles from the LaoHand team, with copy-ready commands.
Git Accident Recovery: Fix Wrong Commits, Wrong Branches and Deleted Branches
Wrong commit, wrong push, or deleted branch? Copy-ready recovery commands with clear safety boundaries for each.
Read →Docker Image Slimming: 5 Steps from 1.2GB to 120MB
Five steps to shrink a Docker image from 1.2GB to 120MB, each with a reusable Dockerfile snippet and verification.
Read →Nginx 502 Bad Gateway? Locate It in 5 Steps
A 502 means Nginx itself is fine but got an invalid response from the upstream (backend/proxy). This guide gives the shortest path: process → config → timeout → resources → logs.
Read →Linux Disk Full: Locate the Real Culprit with df, du and lsof
A "No space left on device" error does not mean you should delete files at random. This guide walks through the full path — filesystem water level, directory drill-down, and "deleted but still held" files — plus a safe cleanup order that will not destroy data.
Read →Linux CPU at 100%: the Shortest Path from top to the Thread Stack
A reusable path to find why Linux CPU is pegged: classify the load, pin the thread, and capture what it is executing.
Read →MySQL Slow Query Tuning: Slow Log, EXPLAIN and Indexing
"The database is slow" usually means a handful of slow SQL statements. This guide offers a repeatable flow: use the slow log to circle the most expensive queries, read the plan with EXPLAIN, decide whether an index pays off, and spot the most common index-defeating patterns.
Read →Redis Slowdown Playbook: Big Keys, Blocking Commands and Eviction
Redis processes commands on a single thread, so one blocking hotspot slows the whole instance. This guide follows the order "memory level → big keys → blocking commands → eviction and persistence", each step with copy-ready commands.
Read →Kubernetes CrashLoopBackOff: Diagnose a Restart-Looping Pod in 5 Steps
CrashLoopBackOff is not one error but a state: the container dies on start, and Kubernetes retries with backoff. This guide gives the shortest path — exit code → previous logs → probes → resources → dependencies.
Read →SSH Passwordless Login: from ssh-keygen to Permission denied
Passwordless SSH boils down to one sentence: put the public key into the remote authorized_keys. What blocks you is usually the three hidden gates — file permissions, the home directory, and SELinux. This guide covers the full setup and a step-by-step debugging path.
Read →Python Virtual Environments in Practice: venv, Dependency Pinning and Cross-Platform Gotchas
"Works on my machine" usually means mixed environments. This guide builds a clean flow with the stdlib venv: create, activate, pin and reproduce — plus the three frequent pitfalls: Windows activation, version drift and cross-platform dependencies.
Read →VSCode Remote Development: Remote-SSH Setup and Connection Debugging
A weak laptop, code on an intranet server, GPUs in the cluster — Remote-SSH keeps the UI local while code and terminal run remotely, feeling native. This guide covers setup, passwordless auth, common connection failures and experience tuning.
Read →Bash Script Safety: set -euo pipefail and trap for Trustworthy Scripts
A Bash script that "finishes" is not a script that "worked": failed commands do not stop it, empty variables pass silently, and pipes hide upstream crashes. This guide fixes all of them with a copy-ready skeleton (set -euo pipefail + trap + quoting discipline).
Read →YAML Gotchas: Type Coercion, Indentation and Multiline Strings
YAML files that "look right but run wrong" usually fail in three places: silently coerced scalars, misplaced indentation, and ambiguous multiline strings. This guide dissects each trap with detection methods and a toolchain.
Read →HTTP Caching in Practice: Configuring Cache-Control and ETag Correctly
Misconfigured caching ends one of two ways: users never see updates, or origin traffic explodes. This guide covers the split between freshness and validation caching, the hashed-asset vs HTML strategy divide, plus ready-to-use Nginx config and verification commands.
Read →Git Merge and Rebase Conflict Resolution in Practice
For developers branching daily, this guide reads merge conflict markers end to end with reproducible cases and shows how to handle merge, rebase, and rename conflicts.
Read →Bisecting: Pinpoint the Commit That Introduced a Bug
For anyone tired of hunting commits by gut feel, this is the binary-search way to find the commit that broke something, including making the check scriptable so bisect runs hands-free.
Read →Git Submodule Management and Its Common Traps
A field guide to when a submodule actually makes sense, how to add, clone, and update it, and the standard escape hatches for empty dirs after clone, branch drift, and nesting.
Read →Parallel Development with git worktree: Multiple Branches at Once
For devs juggling several branches who fear stash chaos while switching, here is how to keep one clean worktree per task and never stash-swap again.
Read →docker compose Multi-Service Integration and Startup Troubleshooting
Getting to the bottom of ordering, environment variables, port collisions, and service-name DNS inside the compose network, with copyable yaml and debugging commands.
Read →Kubernetes HPA: Configuring and Verifying Autoscaling
For engineers comfortable with Deployments but new to autoscaling: from installing metrics-server, writing an HPA, to load-testing and actually watching replicas scale out.
Read →Dockerfile Security Hardening: Shrinking the Attack Surface
A landing checklist for image maintainers and service containerizers: non-root user, read-only root FS, dropping capabilities, layer hygiene, and image scanning.
Read →JavaScript Error Handling: From try/catch to Global Fallbacks and Retry
A practical catalog for backend and full-stack JS: catching sync and async errors, Promise unhandledrejection, global fallbacks, and exponential-backoff retries.
Read →Python Packaging and Dependency Locking: From pyproject.toml to PyPI
For turning scripts into publishable packages: pyproject.toml for metadata, venv isolation, lock files for reproducible environments, and releasing to PyPI with twine.
Read →Linux Memory Exhaustion and OOM Hunting: From dmesg to the Process Likely Out of Control
When a server claims it is out of memory it rarely tells the whole truth; this guide shows how to use free, /proc/meminfo, cgroups, and dmesg to close in on the process actually eating memory, and how to configure against recurring OOM kills.
Read →Linux Network Troubleshooting Field Manual: Connectivity, Packet Loss, Latency, and DNS
From unreachable pings to crawling slowness and flaky domain resolution, this guide walks layer by layer—link, IP, transport, application—showing which command and which field to look at, with copy-run experiments along the way.
Read →Debugging systemd Service Startup Failures: From status and Dependencies to Ordering Deadlocks
systemctl is-failed is just the first step; this guide splits failures into four kinds—launcher error, process instantly exiting, dependency not ready, and port never listening—with the right log entry and fix for each.
Read →Linux File Permissions and sudo in Practice: chmod/ACL/setuid and Privilege Boundaries
From bit permissions to ACLs to why setuid exists, this guide clarifies exactly how read/write/execute are computed, when the special bits backfire, and why sudo should not be a blanket ALL—plus a safer habit before you break something.
Read →Nginx Reverse Proxy in Practice: location Priority, proxy_pass, and Upstream Balancing Done Right
Misconfigured proxies usually come down to location matching order and trailing-slash traps; this guide corrects the most commonly botched configs line by line and walks you through wiring a real Node backend into a load-balanced reverse proxy.
Read →HTTPS Certificates and Let's Encrypt Auto-Renewal: From Issuance to a cron Fallback
Manually requesting a cert is easy; the hard part is renewing it before expiry automatically. This guide walks certbot through webroot and HTTP-01 validation, configures renewal on port 80, and pairs it with two fallbacks so missing a renewal still does not take the site down.
Read →Debugging REST APIs End-to-End with curl: Methods, Headers, Auth, Upload, and Diagnosis
curl is the first scene of most API debugging; this guide starts from "see exactly what a request sent", covering GET/POST, query vs body, Bearer/JWT auth, Multipart uploads, and reading status code plus timing from one response.
Read →MySQL Logical Backup and Restore: mysqldump, Faster Imports, and Recovering from Accidental Deletes
Exporting with mysqldump is easy; the hard parts are whether the dump restores cleanly, whether the restores fast enough, and whether an accidental delete comes back. This guide covers consistency flags, single-transaction isolation, import-acceleration knobs, and a binlog-based recovery flow.
Read →PostgreSQL Slow-Query Diagnosis and Tuning: From EXPLAIN to shared_buffers
Slow query tuning is a three-step ladder: find the query, read the plan, tune the config. This guide covers enabling the slow log, telling Seq Scan from Index Scan in EXPLAIN, and the core knobs that give the best bang for buck on buffers and concurrency.
Read →Cache Penetration, Breakdown and Avalanche: Identify and Protect Three Redis Faults
When your API suddenly slows down or your database collapses, three kinds of cache faults are usually to blame. This guide uses realistic log symptoms to help you tell apart penetration, breakdown and avalanche, then lays out practical defenses including mutex locks, null-caching and never-expiring hot keys.
Read →MySQL Index Design and EXPLAIN Analysis: From Wasteful to Zero Slow Queries
You keep adding indexes yet slow queries do not go away — that usually means the indexes themselves are misdesigned. Starting from real business SQL, this guide covers composite index column order, covering indexes and index-failure scenarios, then walks through EXPLAIN output section by section so you can actually read a plan.
Read →tmux Session Management and Reuse: Remote Dev That Survives SSH Drops
One dropped SSH and a half-run build, open files and a dozen panes are all gone. This guide shows how tmux named sessions, detach/attach reuse and window/pane layout let you reconnect after a network drop and pick up exactly where you left off.
Read →VSCode Debugging Primer: From launch.json to Hovering Over a Variable
Compared with sprinkling console.log everywhere, debugging lets you pause and inspect the call stack and every variable at each step. Starting from editing launch.json, this guide gets Node and front-end projects debugging, then walks through the sidebar, watch expressions and conditional breakpoints.
Read →Environment Variables and .env Management: Practical Details Beyond 12-Factor
Secrets in code, environment variables drifting across environments, and .env committed to git — almost every project trips on these. Following the 12-factor principle, this guide clarifies precedence, injection methods, and how to manage local and CI config safely.
Read →Prettier and ESLint Together: Formatting and Linting That Do Not Fight
Prettier handles formatting and ESLint enforces quality, but when their rules overlap they fight each other and pre-commit runs get messy. This guide explains how to divide responsibilities, turn off conflicting rules, unify config, and enforce everything in CI.
Read →Take Claude Code Through a Real Bug-Fix Flow
Walk a real bug from reproduction and tests to surgical fixes and regression verification, with exact instructions.
Read →Prompt Engineering for Coding Agents: Make Claude Code / Codex a Reliable Collaborator
Getting a coding agent right on the first try is not about the model but the instruction quality. This guide explains context constraints, minimal-change rules, test-first practice and review prompts, so you can craft reproducible prompts with fewer hallucinations.
Read →systemd Timers in Practice: Replacing cron with Timer Units
cron gives you five environment variables, no catch-up, no dependencies, and logs scattered across syslog. systemd timers give unified logging, inspectable failures, Persistent catch-up, and a far richer scheduling language — plus a clean mapping from existing crontab entries.
Read →Diagnosing Disk IO Bottlenecks: from iostat to Per-Process Attribution
Slow system at 30% CPU usually means the disk queue is the bottleneck. This guide covers what %util and %await actually mean, why %util 100% is not a verdict, how to read iostat -x, how PSI pressure reveals who is being slowed, and how to attribute wait time to specific processes.
Read →inode Exhaustion: The Disk Is Not Full but Writes Still Fail
The classic symptom is "No space left on device" while df -h shows only 20% used. The filesystem has run out of inodes — every file, directory, and symlink consumes one, regardless of how much data it holds. This guide explains the two independent ledgers, why small-file workloads are the danger, how to count files per directory, and how to clean up safely.
Read →TCP Connection Troubleshooting and Tuning: TIME_WAIT, Port Exhaustion and Backlog
Cannot assign requested address, connect failures, dropped SYNs — most TCP-layer failures are readable from the connection state distribution. This guide covers ss state filtering, the real causes of port exhaustion and TIME_WAIT buildup, the three layers behind somaxconn and backlog, and the correct boundary for tcp_tw_reuse.
Read →Prometheus Metric Design: Type Selection and Cardinality Control
Choosing the wrong metric type makes rate() and alerting rules produce wrong conclusions, and a single user_id label can take down a Prometheus cluster. This guide gives decision rules for Counter, Gauge, Histogram and Summary, a method for estimating and bounding cardinality, naming and label conventions, and how to catch high-cardinality metrics during review.
Read →Kubernetes Probe Tuning: How liveness and readiness Should Be Split
Misconfigured probes are a top cause of phantom restarts and pods stuck in NotReady. This guide separates the semantics of the three probe types, shows how startupProbe removes restart loops, and gives a repeatable debugging path with kubectl events.
Read →How to Set Kubernetes Resource Requests and Limits
Requests drive scheduling and QoS class; limits cap runtime usage, and CPU and memory behave nothing alike under a cap. This guide covers QoS classification, CFS throttling versus OOMKill, LimitRange defaults, and how to correctly attribute an OOMKilled container.
Read →Docker Compose Networks and Volumes in Practice
Why containers cannot reach each other over localhost, and when to choose a named volume over a bind mount. This guide covers the DNS difference between the default bridge and user-defined networks, service name resolution, published ports versus exposed ports, and the operational trade-offs of both mount styles.
Read →Nginx Rate Limiting: Combining limit_conn and limit_req
A misconfigured limit is worse than none: without a shared zone, throttling degrades to per-worker accounting. This guide distinguishes limit_req from limit_conn, explains burst queues and the nodelay flag, covers why the shared memory zone is mandatory, and orders the debugging steps for a 429 spike.
Read →HTTPS and TLS Tuning: Session Resumption, OCSP and Handshake Cost
TLS handshakes are the dominant latency source for short-lived connections. This guide covers session cache versus session tickets, what changes in TLS 1.3, how OCSP stapling removes a client round trip, and a prioritized optimization and verification path for high-connection-churn sites.
Read →WebSocket Reverse Proxy: Nginx Configuration and Timeout Traps
WebSocket connections keep dropping behind Nginx, handshakes return 400, or messages vanish in a cluster? Start from the minimal Upgrade header setup, then fix silent disconnects caused by the 60s proxy_read_timeout default, sticky sessions, and a copy-paste debugging checklist.
Read →MySQL Deadlock Troubleshooting: From SHOW ENGINE INNODB STATUS to Root Cause
ERROR 1213 keeps killing production transactions and nobody knows which two statements circled each other. This guide walks the full path: reading every line of the deadlock report, matching the lock holder to the waiter, understanding gap-lock impact, rewriting batch updates in primary-key order, and keeping evidence with innodb_print_all_deadlock.
Read →PostgreSQL Connection Pooling: PgBouncer and the Connection Explosion
Production dies with FATAL: sorry, too many clients already and the connection count grows like a stock chart. This guide covers the exact symptoms of exhausted max_connections, a comparison of the three PgBouncer pooling modes and their feature limitations, and concrete queries to locate a connection storm.
Read →Redis Persistence Options: RDB, AOF and Hybrid Strategies
RDB or AOF? appendfsync everysec or always? Starting from the multi-part AOF of Redis 7, this guide compares the data-loss windows and throughput cost of the three fsync policies, explains how writes during an RDB snapshot are handled, and covers data-integrity considerations during failover plus a working configuration template.
Read →Python Async in Practice: asyncio Pitfalls and Concurrency Patterns
Wrote asyncio code but the service is still serial? This guide covers five frequent pitfalls: isolating blocking calls with to_thread or run_in_executor, the exception-propagation difference between asyncio.gather and TaskGroup, forgetting to create an event loop, connection-pool capacity traps, and correct use of wait_for and Semaphore for timeouts and rate limiting.
Read →Practical TypeScript Type Design: From any to Maintainable Types
any silently spreads into a type black hole. Discriminated unions, generic constraints and a debugging path for narrowing failures that actually scale.
Read →Engineering Nginx Configuration: Layout and Organization
How to keep nginx.conf from becoming a 3000-line monolith: include boundaries, map and geo usage, and locking location priority down with tests.
Read →Config Management Evolution: From .env Files to Secret Managers
A four-stage path from local .env to a secret manager, with applicability boundaries, rotation mechanics and failure modes for each stage.
Read →CI Cache Design: Repository Size, Shallow Clones and Cache Keys
When CI stalls at the clone step, repository size and cache policy are usually to blame. Shallow clone, partial clone, filter flags, cache key design, and separating artifacts from source.
Read →Troubleshooting Sluggish VS Code: Extensions, Indexing and File Watching
Input lag and stalled saves are rarely editor bugs. A reproducible order: bisect with an empty window to isolate extensions, clean up extension hosts, control index scope with files.exclude and search.exclude, and tune watching on large repositories.
Read →Kubernetes Network Policies in Practice: From Open-by-Default to Least Privilege
Pods talk to each other by default, and having zero NetworkPolicy objects means fully open, not locked down. This guide starts from that default behaviour, explains why ingress and egress must be reasoned about separately, clarifies that the CNI plugin is where policy is actually enforced, and walks through six common reasons a policy you wrote never takes effect.
Read →Kubernetes Autoscaling in Practice: Dividing Work Between HPA, VPA, and Node Scaling
"Scale out at 80% CPU" is not how Kubernetes actually behaves. This guide draws the boundaries between the three autoscaling layers: which signals HPA can use, why metrics-server is a hard dependency, why VPA and HPA fight over the same resource fields, and when Custom Metrics or plain node scaling is the right answer.
Read →Log Analysis in Practice: journald, logrotate, and Multi-Line Troubleshooting
Disk filled by logs, a systemd unit that refuses to start, yesterday's logs suddenly "missing" — all three trace the same pipeline: write, rotate, query. This guide filters with journald's structured fields, gives the correct order for emergency disk reclamation plus handling of files already written after a journal vacuum, and covers logrotate's copytruncate hazard and how multi-line logs get joined differently in journald, logrotate, and the collection agent.
Read →Nginx Load Balancing in Practice: Upstream, Rate Limiting, and Health Checks
proxy_pass is only the entry point — all traffic distribution logic lives in the upstream block. This guide compares the three built-in balancing methods and their distribution pitfalls, shows how max_fails and proxy_next_upstream combine into real failover, explains what upstream keepalive actually buys and where it hurts, and covers the three directives WebSocket needs plus a reusable rate-limiting setup.
Read →SQL Query Optimization in Practice: Locating Slow Queries Through Execution Plans
Every slow query investigation starts with the execution plan, not with guesswork. This guide walks MySQL EXPLAIN field by field — type, possible_keys, key, rows, filtered, Extra — explains which type values really mean a full table scan and which Extra entries are warning signs, then catalogues six classic index-failure scenarios (implicit type conversion, wrapping a column in a function, leading-wildcard LIKE, broken leftmost-prefix on a composite index, OR mixing, mismatched sort direction) and closes with what SELECT * actually costs and how to rewrite it.
Read →Redis Caching in Practice: Hot-Key Breakdowns, Penetrations, and Avalanches
Cache breakdown, penetration, and avalanche sound alike but have completely different causes: a hot key expiring under concurrency, repeated lookups of keys that do not exist, and mass simultaneous invalidation or instance loss. This guide works through each root cause, then covers mutex rebuilds, logical expiry, null-value caching, Bloom filters, TTL jitter, and two-level local caching for hot keys.
Read →MySQL Index Design in Practice: Composite Indexes and the Leftmost Prefix
Column order in a composite index is a structural decision, not a matter of taste, because it determines whether the index can be used at all. Starting from B+ tree ordering, this guide explains why the leftmost prefix rule holds, why a range condition stops further index usage, how to order columns by selectivity, equality, and sort direction, how covering indexes remove table lookups, and which scenarios genuinely break index usage: function wrapping, implicit type conversion, leading wildcards, and charset mismatches.
Read →CSS Grid Layout in Practice: From Two Columns to Fully Responsive
The hard part of CSS Grid is not syntax but how fr units distribute space, when auto and minmax are resolved, and how the implicit grid is filled. Starting from the coordinate system of a grid container, this guide explains the precise meaning of fr remainder distribution, why 1fr can overflow, the difference between minmax and auto-fill versus auto-fit, how grid-auto-flow changes placement, and closes with a copy-ready responsive recipe, canonical centering solutions, and a rule for choosing between Grid and Flexbox.
Read →Team Git Workflows in Practice: Branching Models and Conflict Resolution
Branch model choice, the boundary between rebase and merge, and why conflicts keep recurring all point to the same underlying problem: a team without an explicit commit contract. This guide compares the applicable boundaries of trunk-based development and gitflow, gives concrete rules for "rebase locally, merge on shared branches", explains the destructive edge of history rewriting plus recovery options, analyzes common causes of conflict — parallel edits to the same file, formatters, case-insensitive filesystems — and lays out a message and formatting convention that keeps history readable.
Read →Terraform State Management in Practice: Remote Backends and State Splitting
The state file is the source of truth in Terraform: it is the collaboration bottleneck and the file most likely to cause a catastrophe. A lost local state means orphaned resources, and concurrent applies mean two engineers acting on the same resource. This guide covers remote backend selection and configuration, the real semantics of state locking including who may unlock and how to unlock safely, correct state splitting by environment and by component, and how import blocks and moved blocks reshape resource addresses without recreating anything.
Read →