Docker Compose freezes EC2 t2.micro instances primarily because the default 1 GB RAM limit is exceeded by container overhead, causing the Linux kernel to kill processes or hang. The most effective solution is to configure Docker’s memory limits and enable swap space to prevent out-of-memory crashes that render the instance unresponsive.
Understanding the Resource Constraints
The Amazon EC2 t2.micro instance type provides only 1 GiB of RAM and limited CPU credits. When you run multiple services via
docker-compose up, each container requires a base amount of memory for the Docker daemon, the container runtime, and the application itself. Without explicit limits, containers may consume all available system RAM.
When RAM is exhausted, the Linux kernel enters an OOM (Out of Memory) state. In this state, the kernel attempts to free memory by killing processes, but it may also freeze system calls like
ssh or
systemctl. This results in the instance appearing "frozen" to the user, even though the underlying hypervisor is still running.
The Role of Swap Space
Swap space acts as a safety valve. It allows the OS to move inactive pages from RAM to disk storage. While slower than RAM, swap prevents immediate crashes when memory pressure spikes. On a t2.micro instance, enabling swap is critical for stability during peak usage.
Configuring Docker Memory Limits
To prevent any single container from consuming all available RAM, you should set explicit memory limits in your
docker-compose.yml file. This ensures fair resource distribution among services.
Use the
mem_limit or
deploy.resources.limits.memory directive. For example:
version: '3.8'
services:
web:
image: nginx
mem_limit: 256m
db:
image: postgres
mem_limit: 512m
This configuration restricts the
web service to 256 MB and the
db service to 512 MB. If these limits are exceeded, the container will be killed rather than freezing the entire host. Always monitor actual usage with
docker stats to adjust these values accurately.
Enabling Swap on EC2
Since t2.micro instances have no guaranteed swap partition, you must create a swap file manually. This process involves allocating disk space and configuring the kernel to use it.
First, create a swap file of 1 GB:
sudo fallocate -l 1G /swapfile
sudo chmod 600 /swapfile
sudo mkswap /swapfile
sudo swapon /swapfile
Verify that swap is active using
free -h. To make this persistent across reboots, add the following line to
/etc/fstab:
/swapfile none swap sw 0 0
Adjusting the
vm.swappiness value can also optimize performance. A lower value (e.g., 10) tells the kernel to prefer keeping data in RAM, while a higher value encourages more aggressive swapping. For t2.micro, a value of 10-20 is often optimal.
Monitoring and Maintenance
Regular monitoring helps identify potential bottlenecks before they cause freezes. Use tools like
htop or
dstat to observe CPU and memory usage in real-time. Additionally, check Docker logs for signs of excessive memory consumption using
docker logs.
Consider using lightweight base images for your containers to reduce baseline memory usage. Alpine-based images are significantly smaller than Ubuntu or Debian images, which can save hundreds of megabytes per container.
For deeper insights into network isolation and container behavior, you might find
Understanding Docker Compose Network Isolation on Linux useful. Proper network configuration can sometimes reduce overhead and improve overall system responsiveness.
If you encounter issues with SSH connectivity after making these changes, ensure that firewall rules and security groups are correctly configured. See
Misconfigured File: Emulated SSH Server Pinging, Traceroute Fails for Docker on Host VM for troubleshooting steps related to network diagnostics.
Frequently Asked Questions
How do I check if my EC2 instance is out of memory?
Run the command
free -h to view available memory. If the "available" column is near zero and swap is heavily used, you are likely hitting memory limits. You can also check system logs with
dmesg | grep -i oom for Out of Memory errors.
Can I increase the RAM on a t2.micro instance without changing the instance type?
No, the hardware specifications of a t2.micro instance are fixed at launch. To get more RAM, you must stop the instance and change its type to something larger, such as t2.small or t3.micro. However, enabling swap can mitigate the need for more physical RAM.
Why does Docker freeze the instance instead of just killing the container?
When the host system runs out of RAM, the kernel may struggle to execute essential system calls, including those required to gracefully stop containers. This can lead to a complete system hang where even root commands fail to respond, making the instance appear frozen.
Is it safe to use swap on SSD-backed EBS volumes?
Yes, it is generally safe, but frequent swapping can wear down SSDs over time. Since t2.micro instances use EBS volumes, monitor the write intensity. Using a modest swap size (1-2 GB) minimizes wear while providing necessary buffer space during memory spikes.
What happens if I don't set memory limits in Docker Compose?
Without limits, containers can consume all available host memory, leading to OOM kills of other critical processes or the Docker daemon itself. This unpredictability makes it difficult to maintain stable services and increases the risk of instance freezes during traffic peaks.