The 2 AM Bandwidth Crisis
It was 2 AM on a Tuesday when the network monitoring alerts started screaming. My WAN link was pinned at 100%, and my ping in Discord jumped from a smooth 20ms to a jittery 400ms.
I checked the router: three different machines in my house were fighting for bandwidth to download a massive 120GB Call of Duty update. My ISP-provided 100Mbps connection stood no chance. This is the classic bottleneck every HomeLab enthusiast eventually hits—the frustrating gap between internal 1Gbps (or 10Gbps) LAN speeds and the limited pipe to the outside world.
In my real-world experience, this is one of the essential skills to master. If you are running multiple PCs, consoles, or virtual machines, downloading the same 5GB Ubuntu ISO or 100GB Steam game multiple times is a waste of time and money. LanCache solves this by acting as a transparent caching proxy. The first time a file is requested, it’s pulled from the internet and stored on your server. Every subsequent request from any machine on your network is served at local hardware speeds.
Context & Why: Why Your HomeLab Needs a Cache
Modern gaming and OS management are increasingly hostile to slow internet. Between Steam, Epic Games, Windows Updates, and Linux Distros, a typical week can easily see half a terabyte of redundant data crossing your gateway. LanCache (specifically the lancachenet/monolithic project) targets specific CDN traffic—like Valve, Microsoft, and Apple—caching the chunks of data they serve via HTTP.
Why not just use a generic Squid proxy? Because many of these services use complex range requests and specific headers that a standard proxy might ignore. LanCache is pre-configured to handle the quirks of game launchers and system updates out of the box. By redirecting DNS queries to the LanCache container, your clients don’t even know they are talking to a local server; they just see their download bar fly at 110MB/s.
Installation: Deploying LanCache via Docker
I prefer using Docker Compose for this because it allows me to manage the DNS and the Cache services as a single unit. You’ll need a machine with a decent amount of storage—I recommend at least 1TB if you plan on caching more than two or three AAA games.
1. Prepare the Storage
Ensure your cache directory has the correct permissions. I usually mount a dedicated SSD or a high-speed HDD array to /mnt/cache.
sudo mkdir -p /mnt/cache/data /mnt/cache/logs
sudo chown -R 1000:1000 /mnt/cache2. The Docker Compose File
Create a directory for your configuration and drop in this docker-compose.yml. Replace LANCACHE_IP with the static IP of your HomeLab server.
version: '2'
services:
dns:
image: lancachenet/lancache-dns:latest
env_file: .env
restart: always
ports:
- ${LANCACHE_IP}:53:53/udp
- ${LANCACHE_IP}:53:53/tcp
sniproxy:
image: lancachenet/sniproxy:latest
env_file: .env
restart: always
ports:
- ${LANCACHE_IP}:443:443/tcp
monolithic:
image: lancachenet/monolithic:latest
env_file: .env
restart: always
ports:
- ${LANCACHE_IP}:80:80/tcp
volumes:
- /mnt/cache/data:/data/cache
- /mnt/cache/logs:/data/logsConfiguration: Tuning the Environment
The magic happens in the .env file. This is where we define what to cache and how much space to allocate. If you misconfigure the UPSTREAM_DNS, your whole house loses internet access, so be careful here.
# .env file configuration
LANCACHE_IP=192.168.1.50
DNS_BIND_IP=192.168.1.50
UPSTREAM_DNS=1.1.1.1
# Cache Tuning
CACHE_DISK_SIZE=1000g
CACHE_INDEX_SIZE=500m
CACHE_MAX_AGE=3650d
# Optional: Specific services to cache
USE_GENERIC_CACHE=trueI set CACHE_DISK_SIZE to slightly less than the actual disk capacity to prevent the OS from choking if the drive fills up. Once the limit is reached, LanCache uses an LRU (Least Recently Used) algorithm to purge old data. This is crucial—I’ve seen many setups crash because they didn’t account for filesystem overhead.
Network Integration
For this to work, your clients need to use the LanCache server as their DNS provider. You have two choices:
- Manual: Change the DNS settings on your gaming PC to
192.168.1.50. - Automated: Update your DHCP settings in your router (pfSense, OPNsense, or standard ISP router) to hand out the LanCache IP as the primary DNS server.
Verification & Monitoring: Is it actually working?
After bringing the containers up with docker-compose up -d, I always verify the logs. There is nothing worse than thinking you are caching files only to realize everything is bypassing the server due to a DNS mismatch.
1. Testing DNS Resolution
From a client machine, run a dig command against a known game CDN:
nslookup steamcontent.comIf the result returns your Local LanCache IP (192.168.1.50) instead of a public Valve IP, the redirection is working perfectly.
2. Watching the Cache Logs
This is where the satisfaction kicks in. Open a terminal and tail the access logs while you start a download on Steam:
docker logs -f monolithicLook for TCP_HIT or TCP_MISS. A TCP_MISS means it’s fetching from the internet (the first time). A TCP_HIT means it’s serving from your local disk. When you see that TCP_HIT and your Steam download speed spikes to 900Mbps+, you’ll know the 2 AM troubleshooting was worth it.
3. Monitoring Throughput
If you have a dashboard like Grafana (which I’ve used in other HomeLab projects), you can monitor the network interface of the LanCache container. During a cache hit, you should see high outbound traffic from the container with almost zero inbound traffic from the WAN. It’s a beautiful sight to see three PCs updating at full speed while the external internet remains completely idle, leaving plenty of bandwidth for everyone else to stream 4K movies or game without lag.
Setting this up transformed my HomeLab from a simple file server into a high-performance network asset. No more scheduling downloads for the middle of the night—just click ‘Update’ and let the local storage do the heavy lifting.
