Docker FastAPI

Troubleshooting Commands

After being caught out with the "It works on my machine" I decided to use docker for deploying projects. Though this is not without a few other gotchas. Here are a few of the useful commands that helped me trackdown my memory issues on a single CPU instance on Digital ocean.

My symptoms where uvicorn being killed due to running out of memory and having no swap memory allocated.

Memory and Resource Monitoring

Command	Description
`free -h`	Check system memory usage
`docker stats --no-stream`	Show container resource usage
`docker stats <container-name>`	Monitor specific container resources
`sudo dmesg \\| grep -i "killed process\\|out of memory"`	Check for OOM kills in system logs
`ps aux --sort=-%mem \\| head -10`	Show top memory-consuming processes

Container Status and Logs

Command	Description
`docker ps -a`	Show all containers (running and stopped)
`docker logs <container-name> --tail 50`	Show recent container logs
`docker logs <container-name> --follow`	Follow container logs in real-time
`docker inspect <container-name>`	Show detailed container information
`docker events --filter container=<container-name>`	Monitor container events

Docker Compose Management

Command	Description
`docker-compose config`	Validate and show compose configuration
`docker-compose ps`	Show compose services status
`docker-compose logs <service-name>`	Show service logs
`docker-compose restart <service-name>`	Restart specific service
`docker-compose down && docker-compose up -d`	Full restart

Network and Connection Debugging

Command	Description
`ss -ant state fin-wait-2`	Show FIN-WAIT-2 connections
`ss -ant state fin-wait-2 \\| grep :8000`	Show FIN-WAIT-2 on port 8000
`ss -tulpn \\| grep :8000`	Check what's listening on port 8000
`netstat -tulpn \\| grep :8000`	Alternative port check
`curl -v http://localhost:8000/`	Test direct connection to FastAPI

SSL/TLS Debugging

Command	Description
`openssl s_client -connect domain.com:443`	Test SSL handshake
`sudo certbot certificates`	Check Let's Encrypt certificates
`sudo certbot renew --dry-run`	Test certificate renewal
`sudo nginx -t`	Test nginx configuration
`sudo systemctl reload nginx`	Reload nginx config

File and System Checks

Command	Description
`df -h`	Check disk space
`ls -la /var/log/`	Check log files
`du -sh ./data/`	Check data directory size
`find /var/log -name "*.log" -size +100M`	Find large log files
`journalctl -u docker -n 50`	Check Docker service logs

FastAPI Specific Debugging

Command	Description
`docker exec -it <container-name> bash`	Enter container shell
`docker exec <container-name> curl -s http://localhost:8000/`	Test FastAPI from inside container
`docker exec <container-name> ps aux`	Check processes inside container
`docker exec <container-name> ls -la /data/`	Check data files in container

Performance and Monitoring

Command	Description
`htop`	Interactive process viewer
`iotop`	Monitor disk I/O
`watch -n 2 "docker stats --no-stream"`	Monitor container stats continuously
`watch -n 5 "ss -ant state fin-wait-2 \\| wc -l"`	Monitor connection count

Garbage Collection and Python Memory

Command	Description
`docker exec <container-name> python -c "import gc; print(gc.collect())"`	Force garbage collection in container
`docker exec <container-name> python -c "import psutil, os; print(f'Memory: {psutil.Process(os.getpid()).memory_info().rss/1024/1024:.1f}MB')"`	Check Python process memory

Emergency Fixes

Command	Description
`docker system prune -a`	Clean up Docker resources (use carefully)
`sudo systemctl restart docker`	Restart Docker daemon
`docker-compose down --remove-orphans`	Stop and remove orphaned containers
`echo 1 > /proc/sys/vm/drop_caches`	Clear system cache (as root)
`sudo swapoff -a && sudo swapon -a`	Reset swap

Memory Troubleshooting Commands

System Memory Overview

Command	Description
`free -h`	Show memory usage (RAM + swap) in human-readable format
`free -m`	Show memory usage in megabytes
`cat /proc/meminfo`	Detailed memory information
`vmstat`	Virtual memory statistics
`vmstat 2 5`	Monitor memory stats every 2 seconds, 5 times

Process Memory Usage

Command	Description
`ps aux --sort=-%mem \\| head -10`	Top 10 memory-consuming processes
`ps aux --sort=-%mem \\| grep docker`	Memory usage of Docker processes
`top -o %MEM`	Interactive view sorted by memory usage
`htop`	Enhanced interactive process viewer
`pmap <pid>`	Memory map of a specific process

Docker Container Memory

Command	Description
`docker stats --no-stream`	Current container resource usage
`docker stats <container-name>`	Monitor specific container continuously
`docker inspect <container> \\| grep Memory`	Container memory limits
`docker system df`	Docker disk and memory usage
`docker exec <container> ps aux`	Processes inside container

OOM (Out of Memory) Detection

Command	Description
`dmesg \\| grep -i "killed process"`	Find OOM kills in kernel log
`dmesg \\| grep -i "out of memory"`	Search for OOM messages
`grep -r "Out of memory" /var/log/`	Search OOM in all log files
`journalctl --dmesg \\| grep -i oom`	OOM messages in systemd journal
`awk '/killed process/ { print $0 }' /var/log/kern.log`	Parse OOM kills from kernel log

Swap Memory Management

Command	Description
`swapon --show`	Show current swap usage
`cat /proc/swaps`	Detailed swap information
`sudo fallocate -l 1G /swapfile`	Create 1GB swap file
`sudo mkswap /swapfile`	Format file as swap
`sudo swapon /swapfile`	Enable swap file
`sudo swapoff /swapfile`	Disable swap file
`cat /proc/sys/vm/swappiness`	Check swap aggressiveness (0-100)

Memory Monitoring & Analysis

Command	Description
`watch -n 2 "free -h"`	Monitor memory every 2 seconds
`watch -n 1 "docker stats --no-stream"`	Monitor container memory continuously
`iotop`	Monitor disk I/O (swap usage)
`smem`	Advanced memory reporting tool
`cat /proc/<pid>/status \\| grep VmRSS`	Specific process memory usage

Memory Cleanup Commands

Command	Description
`sync && echo 1 > /proc/sys/vm/drop_caches`	Clear page cache
`sync && echo 2 > /proc/sys/vm/drop_caches`	Clear dentries and inodes
`sync && echo 3 > /proc/sys/vm/drop_caches`	Clear all caches
`docker system prune -a`	Clean up Docker resources
`docker container prune`	Remove stopped containers
`docker image prune -a`	Remove unused images

Python/Application Memory Debugging

Command	Description
`docker exec <container> python -c "import gc; print(gc.collect())"`	Force garbage collection
`docker exec <container> python -c "import psutil,os; print(f'{psutil.Process().memory_info().rss/1024/1024:.1f}MB')"`	Python process memory
`ps -o pid,vsz,rss,comm -p <pid>`	Specific process memory details
`pgrep -f uvicorn`	Find uvicorn process IDs

System Limits & Configuration

Command	Description
`ulimit -a`	Show current user limits
`cat /proc/sys/vm/overcommit_memory`	Memory overcommit setting
`cat /proc/sys/vm/oom_kill_allocating_task`	OOM killer behavior
`systemctl status systemd-oomd`	Check if systemd OOM daemon is running

Emergency Memory Commands

Command	Description
`sudo pkill -f "uvicorn\\|python"`	Emergency kill Python/uvicorn processes
`docker kill $(docker ps -q)`	Kill all running containers
`sudo systemctl restart docker`	Restart Docker daemon
`sudo reboot`	Restart system (last resort)

Useful One-liners

Command	Description
`free -h && docker stats --no-stream`	Quick system + container memory check
`dmesg \\| tail -20 \\| grep -i "killed\\|oom"`	Recent OOM kills
`watch -n 3 "echo 'System:' && free -h && echo 'Containers:' && docker stats --no-stream"`	Monitor both system and containers
`ps aux \\| awk '{print $6/1024 " MB\t" $11}' \\| sort -n \\| tail -10`	Top memory users in MB

Day 25252