Introduction to Lancache

Lancache is a caching proxy specifically designed for caching game downloads from services like Steam, Origin, Battle.net, Epic Games, and others. It can significantly reduce bandwidth usage in environments with multiple gamers.

This guide will walk you through the complete process of setting up, configuring, maintaining, and monitoring a Lancache server on Ubuntu 20.04 LTS.

Prerequisites

What You'll Need

  • Ubuntu Server 20.04 LTS or newer
  • Minimum 4GB RAM, large storage capacity (500GB+ recommended)
  • Root or sudo privileges
  • Static IP address configured on your server
  • Basic knowledge of Linux command line and Docker

Installation

1 Update System and Install Dependencies

Start by updating your system and installing the necessary dependencies:

sudo apt update && sudo apt upgrade -y
sudo apt install -y curl git docker.io docker-compose

This ensures your system is up to date and installs Docker which is required for running Lancache.

2 Install Lancache

Create the directory structure and clone the necessary repositories:

# Create lancache directory
sudo mkdir -p /srv/lancache
cd /srv/lancache

# Clone the UK Lancans repository
git clone https://github.com/uklans/cache-domains.git

# Clone the lancache-docker repository
git clone https://github.com/lancachenet/monolithic.git
cd monolithic

These repositories contain the necessary configuration and Docker setup for Lancache.

3 Configure Lancache

Create and edit the environment configuration file:

cp .env.example .env
nano .env

Edit the .env file with your settings. Replace the IP address with your server's static IP:

# Server IP and network configuration
LANCACHE_IP=192.168.1.100  # Replace with your server's static IP
CACHE_ROOT=/cache/data
CACHE_DISK_SIZE=500g
CACHE_MAX_AGE=3650d
UPSTREAM_DNS=1.1.1.1 8.8.8.8

# Service ports
HTTP_PORT=80
HTTPS_PORT=443
Note: Make sure to use your server's actual IP address, not the example one shown here.

4 Create Cache Directory Structure

Create the directory where cached data will be stored and set appropriate permissions:

sudo mkdir -p /cache/data
sudo chown -R $USER:$USER /cache

This ensures the cache directory exists and your user has the necessary permissions to write to it.

5 Start Lancache Services

Start the Lancache services using Docker Compose:

cd /srv/lancache/monolithic
docker-compose up -d

This will download the necessary Docker images and start the Lancache service in the background.

Configuration

1 Configure DNS (BIND9)

Install and configure BIND9 for DNS redirection to your Lancache server:

sudo apt install -y bind9

Create the Lancache DNS configuration file:

sudo nano /etc/bind/named.conf.lancache

Add the following content (replace 192.168.1.100 with your server IP):

zone "lancache" {
    type master;
    file "/etc/bind/db.lancache";
};

# Include game domains
include "/etc/bind/named.conf.lancache-domains";

2 Generate Domain Lists

Generate the list of gaming domains that Lancache will handle:

# Navigate to cache-domains
cd /srv/lancache/cache-domains

# Generate the domain list
./scripts/create-list.sh

This script creates output/list.txt with all the gaming domains that Lancache will cache.

3 Generate Domain Configuration

Use the Python script to generate the BIND configuration for all game domains:

cd /srv/lancache/cache-domains
sudo python3 /srv/lancache/cache-domains/scripts/create-bind-config.py \
    --config /srv/lancache/cache-domains/config.json \
    --output /etc/bind/named.conf.lancache-domains \
    --ip 192.168.1.100

Update the main BIND configuration to include the Lancache configuration:

sudo nano /etc/bind/named.conf

Add this line at the end of the file:

include "/etc/bind/named.conf.lancache";

Restart BIND9 to apply the changes:

sudo systemctl restart bind9

Maintenance

1 Regular Updates

Keep your system and Lancache components updated:

# Update system packages
sudo apt update && sudo apt upgrade -y

# Update Docker images
cd /srv/lancache/monolithic
docker-compose pull
docker-compose up -d

# Update cache-domains repository
cd /srv/lancache/cache-domains
git pull origin master
Tip: Set up a cron job to automatically update the cache-domains repository weekly.

2 Backup Strategy

Implement a backup strategy for your Lancache configuration:

# Backup script for Lancache configuration
#!/bin/bash
BACKUP_DIR="/backup/lancache"
DATE=$(date +%Y%m%d_%H%M%S)

mkdir -p $BACKUP_DIR/$DATE

# Backup Docker compose files
cp -r /srv/lancache/monolithic $BACKUP_DIR/$DATE/

# Backup DNS configuration
cp -r /etc/bind $BACKUP_DIR/$DATE/

# Backup environment configuration
cp /srv/lancache/monolithic/.env $BACKUP_DIR/$DATE/

echo "Backup completed: $BACKUP_DIR/$DATE"

Schedule regular backups using cron:

# Edit crontab
sudo crontab -e

# Add this line to run backup weekly
0 3 * * 0 /path/to/backup-script.sh

3 Cache Management

Monitor and manage your cache storage:

# Check cache disk usage
du -sh /cache/data

# Find largest cached items
find /cache/data -type f -exec du -ah {} + | sort -rh | head -20

# Set up log rotation for Docker containers
sudo nano /etc/logrotate.d/docker-lancache

Add the following log rotation configuration:

/var/lib/docker/containers/*/*.log {
    rotate 7
    daily
    compress
    missingok
    delaycompress
    copytruncate
}

Cache Domain Updates

1 Manual Update Process

When cache domain changes are released, update your configuration:

# Navigate to cache-domains directory
cd /srv/lancache/cache-domains

# Pull the latest changes
git pull origin master

# Regenerate the domain list
./scripts/create-list.sh

# Regenerate BIND configuration
sudo python3 scripts/create-bind-config.py \
    --config config.json \
    --output /etc/bind/named.conf.lancache-domains \
    --ip YOUR_SERVER_IP

# Restart BIND9 to apply changes
sudo systemctl restart bind9

# Restart Lancache containers
cd /srv/lancache/monolithic
docker-compose restart

2 Automated Update Script

Create an automated script to handle domain updates:

#!/bin/bash
# /usr/local/bin/update-lancache-domains.sh

LOG_FILE="/var/log/lancache-updates.log"
CACHE_DOMAINS_DIR="/srv/lancache/cache-domains"
LANCACHE_IP="YOUR_SERVER_IP"

echo "$(date): Starting Lancache domain update" >> $LOG_FILE

# Update the repository
cd $CACHE_DOMAINS_DIR
git fetch origin

# Check if updates are available
if [ $(git rev-parse HEAD) != $(git rev-parse @{u}) ]; then
    echo "$(date): Updates found, pulling changes" >> $LOG_FILE
    git pull origin master
    
    # Regenerate domain list
    ./scripts/create-list.sh
    
    # Regenerate BIND configuration
    python3 scripts/create-bind-config.py \
        --config config.json \
        --output /etc/bind/named.conf.lancache-domains \
        --ip $LANCACHE_IP
    
    # Restart services
    systemctl restart bind9
    cd /srv/lancache/monolithic
    docker-compose restart
    
    echo "$(date): Update completed successfully" >> $LOG_FILE
else
    echo "$(date): No updates available" >> $LOG_FILE
fi

Make the script executable and schedule it with cron:

sudo chmod +x /usr/local/bin/update-lancache-domains.sh

# Add to crontab to run daily at 2 AM
sudo crontab -e
# Add: 0 2 * * * /usr/local/bin/update-lancache-domains.sh

Monitoring

1 Basic Health Checks

Create scripts to monitor your Lancache server health:

#!/bin/bash
# /usr/local/bin/check-lancache-health.sh

# Check if Docker containers are running
if [ ! "$(docker ps -q -f name=monolithic_nginx_1)" ]; then
    echo "Nginx container is not running!" | mail -s "Lancache Alert" admin@example.com
fi

if [ ! "$(docker ps -q -f name=monolithic_sniproxy_1)" ]; then
    echo "SNIproxy container is not running!" | mail -s "Lancache Alert" admin@example.com
fi

# Check DNS resolution
if ! nslookup steam.cache.lancache.net 127.0.0.1 >/dev/null 2>&1; then
    echo "DNS resolution failed!" | mail -s "Lancache Alert" admin@example.com
fi

# Check disk space
DISK_USAGE=$(df /cache | awk 'END{print $5}' | sed 's/%//')
if [ $DISK_USAGE -gt 90 ]; then
    echo "Cache disk is $DISK_USAGE% full!" | mail -s "Lancache Alert" admin@example.com
fi

Schedule health checks with cron:

# Run every 5 minutes
*/5 * * * * /usr/local/bin/check-lancache-health.sh

2 External Monitoring

Use external monitoring services to check if your Lancache server is accessible:

UptimeRobot Configuration

Set up monitors in UptimeRobot for:

  • HTTP monitoring on port 80
  • HTTPS monitoring on port 443
  • DNS monitoring on port 53

Pingdom Configuration

Create checks in Pingdom for:

  • HTTP service validation
  • DNS resolution tests
  • Transaction checks for specific game platforms

Simple curl-based monitoring

#!/bin/bash
# Check various endpoints
ENDPOINTS=(
    "http://lancache.example.com"
    "http://steam.cache.lancache.net"
    "http://origin.cache.lancache.net"
)

for endpoint in "${ENDPOINTS[@]}"; do
    if ! curl -s -f --head $endpoint >/dev/null; then
        echo "Endpoint $endpoint is down!" | mail -s "Lancache Alert" admin@example.com
    fi
done

3 Performance Monitoring

Set up monitoring tools to track Lancache performance:

Install and configure Netdata

# Install Netdata
bash <(curl -Ss https://my-netdata.io/kickstart.sh)

# Access Netdata at http://your-server-ip:19999

Monitor key metrics:

  • Bandwidth usage
  • Cache hit ratio
  • DNS query volume
  • Disk I/O and storage capacity
  • Docker container resource usage

Troubleshooting

1 Common Issues

DNS Resolution Problems

# Check if BIND is running
sudo systemctl status bind9

# Check DNS resolution
nslookup steam.cache.lancache.net localhost

# Check BIND logs
sudo tail -f /var/log/bind9/query.log

Docker Container Issues

# Check container status
docker ps -a
docker logs monolithic_nginx_1
docker logs monolithic_sniproxy_1

# Restart containers
cd /srv/lancache/monolithic
docker-compose restart

Cache Not Working

# Check if cache is being used
docker exec monolithic_nginx_1 tail -f /var/log/nginx/access.log

# Check cache directory
ls -la /cache/data
du -sh /cache/data/* | sort -rh

2 Log Analysis

Important log files to check when troubleshooting:

# Nginx access logs
docker logs monolithic_nginx_1

# Nginx error logs
docker exec monolithic_nginx_1 tail -f /var/log/nginx/error.log

# SNIproxy logs
docker logs monolithic_sniproxy_1

# BIND9 logs
sudo tail -f /var/log/bind9/query.log
sudo tail -f /var/log/bind9/error.log

3 Debug Mode

Enable debug mode for more detailed logging:

# Edit the .env file
cd /srv/lancache/monolithic
nano .env

# Add or change these lines
NGINX_WORKER_PROCESSES=1
DEBUG=1

# Restart containers
docker-compose down
docker-compose up -d

With debug mode enabled, you'll get more verbose logging which can help identify issues.