DEV Community

Overnight.Host
Overnight.Host

Posted on

Docker Compose on a 1 GiB VPS: memory limits, swap and log rotation that keep it up

Docker is not the problem on a 1 GiB server. The daemon idles under 50 MB. The real problem is that Compose will happily start five containers with no memory limits at all, and when memory runs out the kernel's OOM killer does not ask which one you meant to keep. Sometimes it picks sshd.

Here are six things to set up on a small box before you add a single container.

1. Install Docker Engine from Docker's repo, not docker.io

Ubuntu's own repository ships an old, renamed build called docker.io. Add Docker's official apt repository instead (the steps are in Docker's Ubuntu install guide), then:

sudo apt install -y docker-ce docker-ce-cli containerd.io docker-buildx-plugin docker-compose-plugin
sudo usermod -aG docker "$USER"
newgrp docker
Enter fullscreen mode Exit fullscreen mode

From here on it is docker compose, a subcommand of the docker CLI with no hyphen, not the old standalone docker-compose binary. The compose file syntax is the same either way.

2. Add swap before you add containers

A 1 GiB plan has exactly 1 GiB of RAM and nothing behind it. Swap does not make anything faster. It turns a hard crash into a slow one you can see coming with free -h.

sudo fallocate -l 2G /swapfile
sudo chmod 600 /swapfile
sudo mkswap /swapfile
sudo swapon /swapfile
echo '/swapfile none swap sw 0 0' | sudo tee -a /etc/fstab

echo 'vm.swappiness=10' | sudo tee /etc/sysctl.d/99-swappiness.conf
sudo sysctl --system
Enter fullscreen mode Exit fullscreen mode

Two gigabytes is a reasonable default on a 25 GB disk. The low swappiness keeps swap as an emergency buffer rather than an active memory tier.

3. Give every service a memory limit (and know which syntax works)

This one catches a lot of people. Many compose files use a deploy.resources.limits.memory block. On a plain docker compose up, that block is parsed and silently ignored. deploy is written for Swarm, and outside Swarm mode Compose only honours it when you run:

docker compose --compatibility up -d
Enter fullscreen mode Exit fullscreen mode

If you would rather not remember a flag on every run, use mem_limit directly. It is a legacy property that the compose plugin still fully supports, and it applies with a plain up:

services:
  uptime-kuma:
    image: louislam/uptime-kuma:1.23.16   # example tag only, check the current release
    restart: unless-stopped
    mem_limit: 200m
    memswap_limit: 400m
    volumes:
      - kuma_data:/app/data
    ports:
      - "127.0.0.1:3001:3001"

volumes:
  kuma_data:
Enter fullscreen mode Exit fullscreen mode

mem_limit caps physical memory. memswap_limit caps memory plus swap, so setting it to double lets the container spill a little into swap instead of being killed the moment it touches the ceiling. Set both on every service before you decide the box "isn't big enough". Four unbounded containers fighting each other is a resource allocation problem, not a RAM problem.

To check what is really using memory, docker stats shows live per-container cgroup usage, which is what your limits are measured against. Cross-check with free -h: if the containers look fine but swap is busy, something outside Docker, or a container without a limit, is the culprit.

4. Rotate logs, or the disk fills quietly

The default json-file logging driver keeps every line a container has ever printed, with no size cap. A chatty service can grow its log into gigabytes over a few months, and you only notice when the disk is full. Set a daemon-wide default in /etc/docker/daemon.json:

{
  "log-driver": "json-file",
  "log-opts": { "max-size": "10m", "max-file": "3" }
}
Enter fullscreen mode Exit fullscreen mode

Then sudo systemctl restart docker. It only applies to containers created after the restart, so run docker compose up -d --force-recreate for anything already running. Three files of 10 MB caps each service at 30 MB of logs.

5. Pin image tags and prune safely

latest is not a version. Pin an explicit tag (or a digest, image: name@sha256:..., for anything holding data you care about) and upgrade on purpose with docker compose pull && docker compose up -d after reading the changelog.

Every pull leaves old layers behind. The safe routine cleanup is:

docker image prune -f
Enter fullscreen mode Exit fullscreen mode

It removes only dangling images and never touches anything a running or stopped container still references. docker system prune -af --volumes is the aggressive version, and --volumes deletes every volume not attached to a container, including the data of a service you stopped but never removed. Run it by hand, read the list, and never put it in an unattended cron job.

6. HTTPS with one Caddy, and a note on NAT IPv4

For anything you open in a browser, Caddy requests and renews the certificate on its own:

app.example.com {
    reverse_proxy 127.0.0.1:3001
}
Enter fullscreen mode Exit fullscreen mode

Bind container ports to 127.0.0.1 (as above) so Caddy is the only thing reachable from the internet, and run one Caddy for everything. It idles comfortably under 50 MB.

One catch before you buy: cheap VPS plans often give you NAT IPv4, a shared address with a few forwarded ports. Caddy needs to own ports 80 and 443 on a public address to serve plain HTTPS. With NAT, either get a dedicated IPv4 or skip the reverse proxy for services that only make outbound calls, like a backup job, a sync agent or an outbound automation workflow.

What actually fits in 1 GiB

With limits in place, these fit comfortably: Uptime Kuma watching a few dozen endpoints (under 100 MB idle), Vaultwarden (under 50 MB idle), and a small n8n with a handful of workflows. One or two of them together still leaves headroom.

These realistically do not fit: Nextcloud with preview generation, Gitea plus CI runners, and anything built on Elasticsearch. The pattern is the same each time. The base app is fine, but one feature (thumbnails, CI jobs, a search index) spikes far above idle. Read the feature list with that in mind, not just the "runs on a Raspberry Pi" line.

That is the whole setup. If you want the longer version with the full apt repository steps and an FAQ, we keep it in our guides, written for our KVM VPS plans that run on single-tenant bare metal in Dallas, TX and Charlotte, NC: Docker Compose on a 1 GiB VPS.


Originally published on overnight.host.

Top comments (0)