Setting up LanCache on the Raspberry Pi

In this tutorial, we will be showing you how to run LanCache on your Raspberry Pi.

LanCache is a unique system that allows you to cache the games you download through various game clients, such as Steam. This ability to cache the content allows it to serve the files to the next person who downloads them. If you are hosting a LAN event or have a poor internet connection, this can save you considerable time.

This software acts as a reverse proxy and a DNS server. It uses its DNS server to reroute requests to servers like the Steam CDN through its proxy. This proxy then caches the requested files locally. LanCache will then serve future requests the file you have already downloaded rather than have to fetch them fresh from the content delivery network.

A Raspberry Pi is a great tool for running LanCache as it is a relatively low-cost device to run. With the newer versions, such as the Pi 4 and 5, it also has enough network capacity to be useful in most setups.

Of course, you will want to have an external hard drive plugged into your Pi to make the most of this tool. Most SD cards are relatively small and aren’t great for lots of reading and writing. If you are using a Raspberry Pi 5, you can even use a high-capacity NVME drive to get great speeds.

If you plug in an external drive, it’s recommended that it be formatted using “ext4.” Formats like NTFS and FAT32 do not properly support Linux permissions.

Equipment

Below is a list of equipment we used when setting up LanCache on our Raspberry Pi.

Optional

Raspberry Pi Case ( Amazon | SunFounder )
USB Keyboard ( Amazon | SunFounder )
USB Mouse ( Amazon | SunFounder )
HDMI Cable ( Amazon | SunFounder )

We last tested this tutorial on a Raspberry Pi 5 running a 64-bit release of Raspberry Pi OS Bookworm.

Installing and Running LanCache on the Raspberry Pi

In this section, we will show you how to install the LanCache software on your Raspberry Pi. To make running this software significantly easier, we will use a Docker container.

We are using a Docker Container by jrichra as it provides ARM builds for systems like the Raspberry Pi. The official version of LanCache only provides builds for AMD64 systems.

Please note that before you proceed, you must set your Raspberry Pi to use a static IP address.

Preparing your Pi to run LanCache

1. Before setting up LanCache on our Raspberry Pi, we should update the package list cache and upgrade any out-of-date packages.

You can perform both tasks by using the following commands in the terminal.

sudo apt update
sudo apt upgrade

2. After updating your Raspberry Pi, you must install Docker on your device.

Follow our guide then return to this tutorial once you have the Docker runtime installed.

https://pimylifeup.com/raspberry-pi-docker/

3. With Docker installed, your next step is to create a folder to store the LanCache cache. This cache can get big so you will likely want to store it on an external drive and not the Pi’s SD card.

For the example below we are creating a directory called “lancache” on our mounted drive.

sudo mkdir -p /mnt/example/lancache

4. Your next step is to use the mkdir command to create a folder where we will store the Docker Compose file on our Pi.

We like to keep all our Compose files within the “/opt/stacks” directory.

sudo mkdir -p /opt/stacks/lancache

5. Once you have created the directory listed above, you can change into it using the cd command.

cd /opt/stacks/lancache

Writing a Docker Compose file for LanCache on the Raspberry Pi

6. We must write a Docker Compose file that will run the LanCache software on your Raspberry Pi.

You can begin writing this Compose file by using the following command in the terminal.

sudo nano compose.yaml

7. Within this file, type out the following lines. These lines define the two LanCache Docker containers we will run on our Raspberry Pi, the DNS server, and the cache system.

You don’t need to change anything in this file, as values will be controlled by an environment file.

services:
  dns:
    image: jrcichra/lancachenet-lancache-dns:latest
    env_file: .env
    ports:
      - 53:53/udp
      - 53:53/tcp
    restart: always

  monolithic:
    image: jrcichra/lancachenet-monolithic:latest
    env_file: .env
    ports:
      - 80:80/tcp
      - 443:443/tcp
    restart: always
    volumes:
      - ${CACHE_ROOT}/:/data/cache
      - ./logs:/data/logs

8. After entering the lines above, you can save and quit by pressing CTRL + X, Y, and then ENTER.

Writing the Environment File

9. After writing the Docker Compose file, we can move on to writing the environment file. The Compose file we wrote earlier will pull in values from this file

To begin writing this file, use the nano text editor as shown below.

sudo nano .env

10. Within this file, you will want to fill out the following information. These lines set environment variables that will be used by the LanCache Docker container when it starts on your Raspberry Pi.

<IPADDRESS>: Replace this element with the IP Address of your Raspberry Pi.
<UPSTREAMDNS>: Swap this placeholder with the IP of the upstream DNS provider you want to use. If you have Pi-Hole running on your home network, you can also point it to that service.

We have listed two of the more popular choices below.
- Google DNS: 8.8.8.8
- Cloudflare: 1.1.1.1
<CACHEDIRECTORY>: Set this to the directory where you want to store the cache. For the Raspberry Pi, you will likely want to mount an external drive and set this to a directory located on that drive.

For this example, we will be using “/mnt/example/lancache“.
<MAXDISKSIZE>: Set this value to the maximum size the cache should grow to. This size is specified in Gigabytes by using the letter “g” after the number.

For example, to set a maximum size of 1 TB, you would use “1000g“.
<TIMEZONE>: Set this to the timezone identifier for where you live. You can find a list of the identifiers on Wikipedia.

For example, where we live, we would use “Australia/Hobart“.

USE_GENERIC_CACHE=true

LANCACHE_IP=<IPADDRESS>
DNS_BIND_IP=<IPADDRESS>
UPSTREAM_DNS=<UPSTREAMDNS>

CACHE_ROOT=<CACHEDIRECTORY>
CACHE_DISK_SIZE=<MAXDISKSIZE>
CACHE_INDEX_SIZE=500m
CACHE_MAX_AGE=3650d

TZ=<TIMEZONE>

11. Once you have finished filling out this file, you can save and quit by pressing CTRL + X, Y, and then ENTER.

Starting up the LanCache Container on your Raspberry Pi

12. We can now bring up the LanCache service using the following command on your Raspberry Pi.

Depending on your internet connection, this process may take a couple of minutes to complete. By using the “-d” option, Docker will detach

docker compose up -d

13. Now that LanCache is working, you must now set your various device’s DNS settings to use your Raspberry Pi.

When a game client such as Steam downloads a game, it is routed through the Raspberry Pi and cached in the directory you selected.

We won’t be covering how to change your DNS settings, as this varies drastically between operating systems and routers.

Verifying that LanCache is Working Correctly

14. Using the nslookup tool, we can verify that the device you have configured to run through LanCache’s DNS server is properly rerouting traffic.

If you are testing this on a Linux system, you must install the “dnsutils” package to use this command. For example, we are testing this from our Windows PC, which we have installed Steam on and configured to use the LanCache DNS server running on our Raspberry Pi.

The simplest way to verify if LanCache is routing traffic is to use the following command within the command line.

nslookup lancache.steamcontent.com

If everything is working correctly, you should see “Address:” followed by your Raspberry Pi’s IP address as shown below.

Server:  UnKnown
Address:  192.168.0.32

Non-authoritative answer:
Name:    steam.cache.lancache.net
Address:  192.168.0.32
Aliases:  lancache.steamcontent.com

15. If you have already started downloading games through LanCache, you can check the directory you set for storing the cache.

Below we are using the path from our example, but you should swap this to where you selected the cache to be stored.

ls -/mnt/example/lancache/cache

The response below shows that data has already started to be cached. This folder structure might look a bit strange due to the way NGINX caches.

01  06  12  17  1f  27  30  39  44  4c  4e  5f  64  6e  79  7f  95  99  9f  bd  c7  ca  de  ee  f6  fa

Updating the LanCache Docker Container

While the LanCache container isn’t updated very often, you will want to know how to update it to the latest version.

Luckily, using Docker Compose makes the update process relatively simple. By the end of this section, you will have the latest version of LanCache on your Raspberry Pi.

1. Your first step is to change to the folder where we originally wrote the Docker Compose file.

You can change to this directory using the following terminal command.

cd /opt/stacks/lancache

2. Once we are in the correct place, we can tell Docker to download the latest version of LanCache to our Pi by using the following command.

This will download the latest images but won’t upgrade the already running containers.

docker compose pull

3. Luckily, updating running containers is fairly easy. Use the same command you use to start LanCache in the first place to get Docker to move over to the new release.