Skip to content

Bare-Metal LANCache

zeropingheroes/lancache-bare-metal runs the cache's nginx directly on the host instead of in Docker.

  • It writes one log file per service to /srv/lancache/logs/http/: steam-access.log, blizzard-access.log, epicgames-access.log, riot-access.log, windows-update-access.log, and fallback-access.log.
  • The logs use an http-detailed format with no service tag.

LANCache Manager reads this layout as-is. Mount the log and cache directories and traffic appears. No nginx changes are needed.

Full Compose example

services:
  lancache-manager:
    image: ghcr.io/regix1/lancache-manager:latest
    container_name: lancache-manager
    restart: unless-stopped
    # Share the host PID namespace so the manager can find the host nginx and
    # ask it to reopen its logs after a removal or rewrite.
    pid: host
    # Docker grants CAP_KILL by default and the image keeps it while dropping
    # to the non-root PUID below. Uncomment only if your deployment uses
    # cap_drop to trim the default capability set.
    # cap_add:
    #   - KILL
    ports:
      - "8080:80"
    environment:
      - PUID=33          # keep your normal non-root IDs; root is not required
      - PGID=33
      - TZ=America/Chicago
      - LanCache__LogPath=/logs
      - LanCache__CachePath=/cache
    volumes:
      - ./data:/data                       # database, API key, themes, prefill state
      - /srv/lancache/logs/http:/logs:ro   # bare-metal per-service logs
      - /srv/lancache/data:/cache:ro       # drop :ro to allow cache clearing and game removal

With docker run, the matching options are --pid=host and, only after a cap_drop, --cap-add=KILL. Mounting the parent /srv/lancache/logs also works; the manager finds the http/ folder on its own.

Why pid: host: after a removal the manager rewrites a log file, and nginx must reopen it or it keeps writing to the deleted inode. Host PID visibility plus CAP_KILL lets the manager signal the host nginx automatically. Without them, removals still complete, but the reopen is reported as failed so you can run nginx -s reopen yourself.

Containerized nginx with bare-metal logs: if nginx runs in a container but writes the per-service log layout, skip pid: host and mount the Docker socket instead (/var/run/docker.sock:/var/run/docker.sock).

Log rotation

The manager never truncates or rotates bare-metal log files; its scheduled job only asks nginx to reopen the current ones. Keep log growth under the host's logrotate, and have the rule reopen nginx afterwards:

postrotate
    nginx -s reopen
endscript

What works

Everything log-based and disk-based, for the five services bare-metal caches:

  • Monitoring: live activity, the dashboard, download history, client and service stats, and game naming (Steam depots, Blizzard products, Riot hosts).
  • Logs: per-service log counts, log removal, and deleting log files.
  • Disk: game and service removal, repeated-miss corruption scanning, eviction tracking, and clearing the whole cache. Every deletion double-checks the file's own embedded cache key first.

A note on hit rates: Blizzard and Windows Update downloads arrive in slices of your install's CACHE_SLICE_SIZE (1 MiB by default; see Cache slice size), and nginx logs the cache status of only the first slice. Their hit/miss ratio is therefore an approximation (byte counts stay exact). Container installs slice the same way, so this is not bare-metal specific.

What doesn't: Xbox

Bare-metal serves five services - Steam, Blizzard, Epic, Riot, and Windows Update - and upstream ships no Xbox Live vhost, so it never writes an xboxlive-access.log. Xbox traffic that does reach the cache lands in the catch-all fallback-access.log, and the manager never ingests that series because its records cannot be attributed to a service.

So Xbox prefill is not supported on a bare-metal cache. A session will run to completion, but no Xbox download ever reaches the dashboard, history, or service stats, and no disk feature can act on what it wrote. Xbox prefill needs a container-based lancache. The other four platforms - Steam, Epic, Battle.net, and Riot - each have their own bare-metal log and prefill normally.

Alternative: switch bare-metal to the standard log format

To use the container-style combined log instead, patch the bare-metal nginx config. Add the standard format to the http {} block of nginx.conf:

log_format cachelog '[$cacheidentifier] $remote_addr / $http_x_forwarded_for - - [$time_local] "$request" $status $body_bytes_sent "$http_referer" "$http_user_agent" "$upstream_cache_status" "$host" "$http_range"';

Version note: logging $http_x_forwarded_for needs a LANCache Manager release newer than v1.10.6; v1.10.6 and older drop every line where that field is filled. :dev images built before 29 Sep 2026 also drop those lines, even though they show version 1.10.7.

Then in each site file under caches-available/, set the service name and replace the site's existing access_log directive (the one that writes its per-service http-detailed log) with the shared one below, so nginx writes each request to one log file only:

set $cacheidentifier steam;   # blizzard / epicgames / riot / wsus per site
access_log /srv/lancache/logs/http/access.log cachelog;

Reload with sudo nginx -s reload (or systemctl reload nginx) and mount /srv/lancache/logs/http as above.

Do not remove games or scan for corruption on a patched cache

  • With the combined log, LANCache Manager treats the install as a standard container. The files on disk still use bare-metal cache keys, so game removal and corruption scans look for files that do not exist.
  • While the old per-service logs sit next to the combined log, LANCache Manager refuses those features.
  • Clear Cache works either way.