Engineering Toolbox Essentials

Engineering Toolbox Essentials is a curated set of foundational tools and practices that every engineer should know, use, and maintain. It matters when you are setting up a new machine, debugging a service in production, or onboarding a teammate—this is the toolkit that turns a competent developer into a reliable, self-sufficient engineer.

Setting Up a Development Environment

Begin with a clean slate: a new laptop, a fresh VM, or a containerized workspace. The goal is to have a consistent, repeatable, and minimal environment across team members. The core tools are git, docker, kubectl, psql, and a shell configuration.

Start by installing the system’s package manager: apt (Debian/Ubuntu), brew (macOS), or pacman (Arch). Use it to install essential binaries:

sudo apt update && sudo apt install -y \
  git \
  curl \
  vim \
  docker.io \
  kubectl \
  postgresql-client \
  sqlite3 \
  jq \
  tmux

Enable Docker as a system service and ensure it starts on boot:

sudo systemctl enable docker
sudo systemctl start docker

Add your user to the docker group so you don’t need sudo for every command:

sudo usermod -aG docker $USER

Verify Docker is ready:

docker info | grep "Operating System"
# Output: Operating System: Ubuntu 22.04.3 LTS

Next, configure your shell (.zshrc or .bashrc) with common aliases and functions:

# ~/.zshrc
alias gs='git status'
alias ga='git add'
alias gc='git commit -m'
alias gpush='git push origin $(git branch --show-current)'
alias k='kubectl'
alias psql='psql -U postgres -h localhost'
alias ll='ls -la'
alias tmux='tmux -u'

Use git to clone a project and set up a local development environment:

git clone https://github.com/example/project.git
cd project
git checkout -b feature/new-login

Ensure git is configured globally with your name and email:

git config --global user.name "Jane Doe"
git config --global user.email "[email protected]"

Running and Debugging Services

With an environment ready, start services locally. Use docker-compose.yml to define the stack:

# docker-compose.yml
version: '3.8'
services:
  web:
    build: .
    ports:
      - "8080:8080"
    depends_on:
      - db
    environment:
      - DATABASE_URL=postgresql://user:pass@db:5432/app
    volumes:
      - ./logs:/app/logs
  db:
    image: postgres:15
    environment:
      POSTGRES_USER: user
      POSTGRES_PASSWORD: pass
      POSTGRES_DB: app
    volumes:
      - pgdata:/var/lib/postgresql/data
    ports:
      - "5432:5432"
volumes:
  pgdata:

Bring up the stack:

docker-compose up -d

Check the status:

docker-compose ps
# Output:
#        Name                 Command             State           Ports
# ---------------------------------------------------------------------
# web_1    npm start        Up      0.0.0.0:8080->8080/tcp
# db_1     docker-entrypoint.sh ...   Up      0.0.0.0:5432->5432/tcp

When a service fails, inspect it with docker logs and docker inspect:

docker logs web_1
# Output:
# > Starting server on port 8080
# > Failed to connect to database: timeout: could not connect to server

Use docker inspect web_1 to examine the container’s configuration, network, and volumes.

For deeper debugging, attach to a running container:

docker exec -it web_1 /bin/sh
# Inside the container:
/ # ps aux | grep node
# Output: 1234 node server.js
/ # netstat -tuln | grep 8080
# Output: tcp 0 0 0.0.0.0:8080 0.0.0.0:* LISTEN

Use kubectl to interact with Kubernetes services:

kubectl get pods
kubectl logs web-deployment-75f6c9d5b6
kubectl describe pod web-deployment-75f6c9d5b6
kubectl port-forward service/web 8080:80

Managing Configuration and Secrets

Configuration should be consistent across environments: local, staging, production. Use a standard format: application.yaml, config.json, or .env.

Define environment variables in a .env file:

DATABASE_URL=postgresql://user:pass@db:5432/app
REDIS_URL=redis://redis:6379/0
LOG_LEVEL=info
PORT=8080

In code, load configuration with a standard approach:

# Python: using `os.environ` and `dotenv`
import os
from dotenv import load_dotenv

load_dotenv()

DATABASE_URL = os.getenv("DATABASE_URL")
REDIS_URL = os.getenv("REDIS_URL")
LOG_LEVEL = os.getenv("LOG_LEVEL", "info")

Use psql to interact with the database directly:

psql -U postgres -h localhost app

Inside the psql prompt:

-- List all tables
\dt

-- Describe a table
\d users

-- Run a query
SELECT id, name FROM users WHERE created_at > '2023-01-01';

-- Export results to CSV
\copy (SELECT * FROM users) TO '/tmp/users.csv' WITH (FORMAT csv, HEADER true);

When a database query fails, check the connection details and verify the user and database exist:

-- Check if user exists
SELECT * FROM pg_user WHERE usename = 'user';

-- Check if database exists
SELECT datname FROM pg_database WHERE datname = 'app';

-- Create missing database
CREATE DATABASE app OWNER user;

Monitoring and Logging

When something goes wrong in production, the first step is to gather logs and metrics. Use journalctl for system-level logs, curl for API calls, and jq for JSON processing.

Check the status of a service:

sudo systemctl status web-service

View logs in real time:

sudo journalctl -u web-service -f

Tail logs with timestamps and process IDs:

sudo journalctl -u web-service -f --since "2023-10-01" --output=compact

When API requests fail, use curl to reproduce and inspect the request and response:

curl -v -X POST https://api.example.com/v1/users \
  -H "Content-Type: application/json" \
  -d '{"name": "Alice", "email": "[email protected]"}'

The response includes headers, status code, and body:

HTTP/2 400
content-type: application/json
date: Fri, 01 Oct 2023 12:00:00 GMT
{"error": "Validation failed", "details": {"email": "must be a valid email"}}

Use jq to filter and format JSON:

curl -s https://api.example.com/v1/users | jq '.[] | {name, email}'

Troubleshooting Common Failures

Silent failures often stem from subtle misconfigurations.

Service Fails to Start: "Connection Refused"

The most common error: a service is running but clients cannot connect. Use netstat or ss to check open ports:

ss -tuln | grep 8080
# Output: tcp 0 0 0.0.0.0:8080 0.0.0.0:* LISTEN

If port 8080 is not listening, check the service configuration and ensure the app binds to 0.0.0.0 (not 127.0.0.1):

# In code, ensure server listens on all interfaces
server.listen(8080, '0.0.0.0'); // not '127.0.0.1'

Database Connection Timeout

When a service cannot connect to the database, verify:

• The database container is running (docker ps)
• The database is accepting connections (docker exec -it db_1 pg_isready)
• The DATABASE_URL is correct, especially the host name

docker exec -it db_1 pg_isready -h localhost -p 5432 -U user -d app

If pg_isready returns pg_isready: could not connect to server, check the pg_hba.conf file inside the container:

docker exec -it db_1 cat /var/lib/postgresql/data/pg_hba.conf

Ensure the host entry allows connections from the app container:

# TYPE  DATABASE        USER            ADDRESS                 METHOD
host    all             all             172.18.0.0/16           md5

Missing Environment Variables

A service starts but behaves unexpectedly due to missing or incorrect environment variables. Use printenv and env to inspect the runtime environment:

# Inside a Docker container
printenv | grep DATABASE_URL
# Output: DATABASE_URL=postgresql://user:pass@db:5432/app

If the variable is missing, verify the .env file is mounted and the service loads it correctly. In a docker-compose.yml, ensure environment is properly defined:

environment:
  - DATABASE_URL=postgresql://user:pass@db:5432/app
  - LOG_LEVEL=debug

Kubernetes Pod Stuck in Pending State

A pod is not running. Use kubectl describe pod to get detailed status:

kubectl describe pod my-pod

Look for:

• Events: FailedScheduling, ContainerCreating, ImagePullBackOff
• Conditions: Ready=False, PodScheduled=False
• Volumes: MountVolume.SetUp failed

If the container image fails to pull, check the image name and registry:

kubectl get pods -o wide
kubectl logs my-pod

Use kubectl get events to see a timeline of events:

kubectl get events --sort-by=.metadata.creationTimestamp

Advanced: Automating Repetitive Tasks

Combine tools into scripts to reduce manual work.

Create a deploy.sh script:

#!/bin/bash
set -euo pipefail

echo "Building image..."
docker build -t myapp:latest .

echo "Pushing to registry..."
docker push myapp:latest

echo "Updating Kubernetes deployment..."
kubectl apply -f k8s/deployment.yaml

echo "Waiting for rollout..."
kubectl rollout status deployment/myapp

echo "Deploy complete."

Make it executable and run:

chmod +x deploy.sh
./deploy.sh

Use git hooks to automate tasks. In .git/hooks/post-commit, add:

#!/bin/bash
echo "Running tests..."
npm test

echo "Building documentation..."
npm run docs

echo "Pushing to origin..."
git push origin HEAD

Final Check: The Engineering Toolbox Checklist

Use this list to verify your toolbox is complete:

• [ ] git installed and configured
• [ ] docker running with docker-compose
• [ ] kubectl configured with cluster access
• [ ] psql available and connected to a database
• [ ] Shell aliases defined and loaded
• [ ] .env file in place with key variables
• [ ] journalctl used to monitor services
• [ ] curl and jq for HTTP and JSON
• [ ] docker logs, docker inspect, docker exec used regularly
• [ ] kubectl commands for pods, deployments, services
• [ ] ss or netstat for network debugging
• [ ] pg_isready for PostgreSQL health checks
• [ ] deploy.sh script for deployments
• [ ] Git hooks for automation

This is the foundation. Every engineer should recognize each tool, command, and error pattern as their own. When a system fails, they do not wait—they act.

This page was rewritten on 18 October 2026. It replaced a templated version that was not specific to its own title. How these pages are written and checked. If anything here is wrong, tell us at [email protected] and we will correct it.