Skip to content

Configuration Reference

This section is a lookup table. Skim the headers and dig in where you need to. The two settings with a real decision behind them have their own walkthroughs: database mode and prefill networking.

For a normal install, start from the checked-in docker-compose.yml. For every supported variable in one place, jump to the complete annotated Compose example at the end of this section.

Volumes

Volume Purpose Notes
/data PostgreSQL database, security, state and config, themes, cached images Required
/logs LANCache access logs Add :ro for read-only
/cache LANCache cached files Add :ro to monitor without touching files
/var/run/docker.sock Docker API access Optional. Needed for nginx log rotation and Steam/Epic/Battle.net/Riot/Xbox prefill

Required Settings

Variable Default Description
PUID 33 (shipped Compose file) User ID the app runs as. Match the owner of your cache and log files.
PGID 33 (shipped Compose file) Group ID the app runs as.
TZ UTC Timezone for log timestamps (e.g., America/Chicago). TimeZone is also accepted as a fallback.
LanCache__LogPath - Path inside the container to the LANCache access log.
LanCache__CachePath - Path inside the container to the LANCache cache directory.

Which PUID/PGID? Match the owner of your cache and log files - ls -n /path/to/cache shows it. The shipped Compose file uses 33:33 (www-data), which fits most stock lancache setups. Unraid uses 99:100. If you run the raw image without PUID or PGID, the entrypoint falls back to 1000 for whichever one is missing. Treat that as a fallback, not a recommended value.

PostgreSQL

The mode decision and full compose examples live in Choosing an Image and Database Mode. The variables:

Variable Default Description
POSTGRES_MODE embedded embedded or external.
POSTGRES_USER lancache PostgreSQL username. Both modes. In external mode this role must own the database or hold CREATE on it, because the schema installs the citext extension - see Choosing an Image and Database Mode.
POSTGRES_PASSWORD - PostgreSQL password. In embedded mode the UI shows a setup page if this is unset. Resetting that password from the config-error screen requires 12 characters and three character classes. In external mode it must be set (or entered via the UI fallback before the app can connect); that path accepts the server's existing password.
POSTGRES_HOST - External mode only. Hostname or IP of the Postgres server.
POSTGRES_PORT 5432 External mode only.
POSTGRES_DB lancache Database name. Both modes.

Security

Variable Default Description
Security__EnableAuthentication true Used only before a sign-in mode is saved. true selects API key, username and password. false selects Unauthenticated. A saved mode is not replaced by this variable.
Security__GuestSessionDurationHours 6 Default guest session length (also configurable in the UI).
Security__RequireAuthForMetrics false Require an API key on /metrics. Endpoint Access under Management → Integrations, or Prometheus Metrics under Users → Sign-in, overrides this when set.
Security__AllowedOrigins (empty) Comma-separated CORS allow list. Empty means same-origin only (the safe default). * allows any origin without credentials; an explicit list allows those origins with credentials.
Security__ApiKeyPath /data/security/api_key.txt Override the file path the installation API key is read from and written to. Useful if you bind-mount secrets from outside /data.
Security__KnownProxyNetworks (empty) Comma-separated CIDR list of trusted proxy networks for X-Forwarded-For (e.g. 172.16.0.0/12,10.0.0.0/8). Set this when nginx, Traefik, or another reverse proxy fronts the manager so client IPs are reported correctly. Loopback is always trusted. Leaving it empty behind a proxy on another host or container also means the sign-in rate limit counts every client against the proxy's address, so one person getting their password wrong repeatedly can lock everybody else out for a minute.
Security__TrustAllProxies false Trust every upstream proxy unconditionally. Convenient for local dev. Never enable on an internet-exposed host - anyone can spoof a client IP.
Security__ForceSecureCookies false Tells the manager that TLS ends at your reverse proxy. Every cookie it sets is then marked Secure, and the app treats the connection as HTTPS, which is what keeps the CSRF cookie policy from rejecting requests it would otherwise see arriving over plain HTTP. Turn it on only once HTTPS actually works in front of the app: with no TLS there, the browser stops sending the session cookie back and nobody can sign in. Setting Security__KnownProxyNetworks as well is still worth doing so client IPs and the sign-in rate limit stay accurate.

Not every /metrics setting has an environment variable. The update interval, the Prometheus scrape interval used in the sample config, and how many games the per-game series export are all set in Management → Integrations. See Prometheus Metrics.

Access Levels

Level What you can do Examples
Primary Owns the installation. The only account that can wipe every account or regenerate the API key. Hidden from every other account, including its sessions. Wipe accounts, regenerate the key
Account Signed-in access to the app. Sees the other ordinary accounts and changes only its own settings. Cannot see the Primary account or its sessions. Install-wide settings are admin-only. Browse downloads, change own settings
Guest View access through a guest session. Prefill is separate: the Primary account grants it per platform, for every new guest or for one session. Browse downloads, stats, events, client data

To give a user access without sharing an account:

  1. On the Users page, open Guest access and turn New guests can sign in on.
  2. Your guest clicks Continue as Guest on the sign-in screen.

Session length, and whether new guests get Prefill, are set in Guest access on the Users page.

Every page and action needs a signed-in account or a guest session. The exceptions are:

  • /metrics is public unless you set Security__RequireAuthForMetrics=true.
  • The /health liveness probe always answers.
  • Sign-in and first-run setup must be public so users can reach them.

Sign-in from environment variables

You can set the sign-in mode and single sign-on logins in the Compose file instead of the UI. Every name starts with Security__. The app reads these values once at start, so a change needs a restart.

Variable Meaning Default
Security__SignInMode The sign-in mode. Not case-sensitive. Values are listed in the next table. (unset)
Value Mode
Password Username and password
ApiKeyPassword API key, username and password
ApiKeyOidc API key and single sign-on (alias ApiKeyAndSso)
Oidc Single sign-on (alias Sso)
Unauthenticated Unauthenticated. Each start deletes every account, including one an environment login allows.

Each single sign-on login uses the same fields. The providers are custom OpenID Connect (Oidc), Google, GitHub, Microsoft and Apple.

Variable Meaning Default
Security__Oidc__ClientId
Security__Google__ClientId
Security__GitHub__ClientId
Security__Microsoft__ClientId
Security__Apple__ClientId
Client ID from the provider's application registration. (unset)
Security__Oidc__ClientSecret
Security__Google__ClientSecret
Security__GitHub__ClientSecret
Security__Microsoft__ClientSecret
Client secret. Prefer the ClientSecretFile form so the secret stays out of the Compose file. Apple has no client secret: it uses the private key below. (unset)
Security__Oidc__ClientSecretFile
Security__Google__ClientSecretFile
Security__GitHub__ClientSecretFile
Security__Microsoft__ClientSecretFile
Path inside the container to a file that holds the client secret. (unset)
Security__Oidc__DisplayName
Security__Google__DisplayName
Security__GitHub__DisplayName
Security__Microsoft__DisplayName
Security__Apple__DisplayName
Name shown on the sign-in button. (unset)
Security__Oidc__AllowedSubjects
Security__Google__AllowedSubjects
Security__GitHub__AllowedSubjects
Security__Microsoft__AllowedSubjects
Security__Apple__AllowedSubjects
Comma-separated provider account IDs allowed to sign in. See Allowing other users. (unset)
Security__Oidc__OwnerSubject
Security__Google__OwnerSubject
Security__GitHub__OwnerSubject
Security__Microsoft__OwnerSubject
Security__Apple__OwnerSubject
Provider account ID of the owner, who signs in as the primary administrator. (unset)
Security__Oidc__OwnerIssuer
Security__Google__OwnerIssuer
Security__GitHub__OwnerIssuer
Security__Microsoft__OwnerIssuer
Security__Apple__OwnerIssuer
Issuer that goes with OwnerSubject. The provider's validated authority. For GitHub, https://github.com.

Some providers need extra fields.

Variable Meaning Default
Security__Oidc__Authority HTTP or HTTPS issuer URL of the custom OpenID Connect provider. For a provider with a self-signed or private certificate, put its CA certificate (PEM, .crt) in /data/certs/ and restart. (unset)
Security__Microsoft__Tenant Directory (tenant) GUID, or consumers for personal accounts. (unset)
Security__Apple__TeamId Apple Team ID. (unset)
Security__Apple__KeyId Apple Key ID. (unset)
Security__Apple__PrivateKey Contents of the Apple .p8 key. (unset)
Security__Apple__PrivateKeyFile Path inside the container to the Apple .p8 key file. (unset)

How the values behave:

Situation Result
A *File variable The file's text, trimmed, is the value. An unreadable file logs an error that names the variable, never the value. The field then uses the inline variable when one is set, and stays unset when none is.
A field set inline and by file The file wins. A warning names both variables.
A field set by environment and in the UI The environment wins for that field. A field the environment does not set keeps the UI value.
Where the UI shows an environment field It shows as set by environment variable and cannot be edited. The mode picker is read-only when the mode comes from the environment.
Secrets from the environment They are never written to state.json.
Oidc or ApiKeyOidc with no valid login The app falls back to ApiKeyPassword, never to Unauthenticated, and logs an error that names the missing fields.
An invalid Security__SignInMode value The app logs it once and ignores it.
First-run setup with Password or ApiKeyPassword The access step is skipped. The database and first-account steps still run.
First-run setup with Unauthenticated The access step is skipped. Each start deletes every account, including one an environment login allows. No first account is created.
First-run setup with Oidc or ApiKeyOidc The access step still shows, read-only. The owner signs in there through the environment login.
You remove the variables later The access step returns. A stored login that lost its environment fields, with no environment left to fill them, is no longer listed.

While sign-in is on, an account that an environment login allows, by OwnerSubject or AllowedSubjects, cannot be removed:

  • Delete and bulk delete refuse it.
  • API key rotation keeps the account.
  • Account reset keeps the account and its saved Steam, Epic and Xbox logins.
  • The refusal reads: "An environment variable allows this account. Remove it from that variable and restart the app before deleting the account."
  • A login service with any environment field cannot be removed in the UI.

Turning sign-in off deletes that account too, like every other account. If sign-in is turned back on while the variable is still set, that user's next sign-in creates the account again.

If a fallback locks the owner out, follow Password Recovery.

Prefill settings

Prefill auto-detects the right values for almost everything in this table. Three things to know before reaching for it:

  • Set Prefill__LancacheIp to your cache server's IP and prefill stops depending on DNS. It matters most for Battle.net, whose CDN domains are often missing from lancache DNS and can make prefill hang.
  • Leave it unset and the manager auto-detects your cache. It probes likely candidates with a quick health check and only uses an address that answered like a real lancache.
  • Reach for the other variables only when auto-detection gets them wrong. The decision table lives in Network setup.
Variable Default Description
Prefill__LancacheIp (unset) IP or hostname of your cache server (the HTTP server holding cached files, port 80). Forwarded to the daemon as LANCACHE_IP; the daemon then connects directly with a spoofed Host: header and skips DNS for CDN traffic. The single most reliable override - set this whenever your DNS isn't a stock lancache-dns.
Prefill__LancacheDnsIp auto IP of your DNS server (lancache-dns, AdGuard, Pi-hole - port 53). Written into the prefill container's /etc/resolv.conf so the daemon resolves CDN hostnames against it. Used in bridge mode only - LANCache Manager sets it only on bridge-mode prefill containers; in host mode the container uses the host's own DNS. auto reuses the IP of your detected lancache-dns container.
Prefill__NetworkMode auto Docker network mode for prefill containers. Accepts host, bridge, or a Docker network name. auto infers the mode from your lancache-dns container.
Prefill__SteamDockerImage ghcr.io/regix1/steam-prefill-daemon:latest Docker image used for Steam prefill containers.
Prefill__EpicDockerImage ghcr.io/regix1/epic-prefill-daemon:latest Docker image used for Epic prefill containers.
Prefill__BattlenetDockerImage ghcr.io/regix1/battlenet-prefill-daemon:latest Docker image used for Battle.net prefill containers.
Prefill__RiotDockerImage ghcr.io/regix1/riot-prefill-daemon:latest Docker image used for Riot prefill containers.
Prefill__XboxDockerImage ghcr.io/regix1/xbox-prefill-daemon:latest Docker image used for Xbox prefill containers.
Prefill__SessionTimeoutMinutes 120 Total lifetime of a non-persistent prefill session. Guest and persistent sessions use their own limits.
Prefill__StallTimeoutSeconds 180 Advanced. No-progress time before a prefill counts as stalled.
Prefill__AbandonedLoginTimeoutSeconds 900 Advanced. Seconds a prefill sign-in may sit waiting in the browser before the app ends it.
Prefill__DaemonBasePath /data/prefill Container path where prefill session state is stored.
Prefill__HostDataPath auto Host path that maps to the manager's /data volume. Detected from the manager's mount config; set explicitly only when detection fails (unusual platforms, custom volume drivers).
Prefill__UseTcp auto Communicate with the daemon over TCP instead of a Unix domain socket. auto resolves to true on Windows, false on Linux. Linux users only need to set this if they want to force TCP mode.
Prefill__TcpPort 45555 TCP port the daemon listens on inside its container. Used in TCP mode only - Windows by default, Linux only when Prefill__UseTcp=true.
Prefill__HostTcpPort (random free port) TCP port the daemon's container publishes on the host. TCP mode only.
Prefill__TcpHost 127.0.0.1 Host the daemon binds to and the manager connects to over TCP. TCP mode only.

Note

TCP mode is the platform divide. On Windows, prefill containers communicate over TCP because Windows doesn't expose Unix domain sockets to Docker. On Linux, prefill uses a Unix domain socket by default - the four TCP variables above are ignored unless you set Prefill__UseTcp=true. Stock Linux installs can skip the TCP rows entirely.

Paths and Datasources

Variable Default Description
LanCache__EnvFilePath (auto) Path to the lancache .env file (used to read CACHE_DISK_SIZE). Searches common locations if unset.
LanCache__AutoDiscoverDatasources false Auto-detect datasources from matching subdirectories under /cache and /logs, up to three levels deep.
LanCache__DataSources__<n>__SchemeOverride auto Cache-key scheme for one datasource: auto, monolithic, or bare_metal. Only needed when custom log filenames defeat auto-detection and the datasource is left read-only for disk actions. Also settable per datasource in the UI.

If you run more than one cache instance or split services across drives, see Multiple Datasources.

Nginx Log Rotation

Variable Default Description
NginxLogRotation__Enabled true Tell nginx to reopen its logs after the app rewrites them. Containerized nginx uses the Docker socket; nginx running directly on the host uses the host PID namespace and sufficient signal privilege.
NginxLogRotation__ContainerName (empty = auto-detect) LANCache container name. When empty (or set to auto), the app finds containers with "lancache" in the name.
NginxLogRotation__ScheduleHours 24 How often to check whether rotation is needed.

API and Advanced

Variable Default Description
ApiOptions__MaxClientsPerRequest 1000 Max clients returned in a single stats request.
ApiOptions__DefaultClientsLimit 100 Default client limit when none is provided.
ASPNETCORE_URLS http://+:80 Internal port binding. Don't change unless you know exactly why.
ConnectionStrings__DefaultConnection (auto) Full PostgreSQL connection string override. For power users with complex setups not covered by individual POSTGRES_* variables.
CacheSnapshots__RetentionDays 90 How long to keep cache snapshots. Older snapshots are automatically deleted.
CacheSnapshots__IntervalMinutes 60 Advanced. How often to record a cache-size snapshot.
GitHubMappings__HttpsProxy (unset) Proxy for the GitHub depot-map download only. Used for HTTPS on port 443 to github.com and *.githubusercontent.com, redirects included; every other host connects directly. Must be an absolute HTTP or HTTPS URL, for example http://proxy:3128; http://user:pass@proxy:3128 signs in to the proxy. Unset: the download uses HTTPS_PROXY, HTTP_PROXY and NO_PROXY like the rest of the app.

Cache slice size

The Cache slice size setting sits in Management, in the Cache Settings card at the top of Cache Operations. It tells the app how large the slices in your cache are, which your LANCache sets with CACHE_SLICE_SIZE. The app uses it to find every slice of a cached file.

Value Meaning
Auto (default) The app reads the size from the KEY: headers of the cache files.
Manual size The page offers the powers of two from 1 to 64 MiB. For any other whole number of MiB, use the PATCH request below. Set it to match CACHE_SLICE_SIZE.
  • The app always checks the sizes it finds on disk, so files written at an older size stay visible.
  • The app tries the manual size first, then the sampled sizes, then 1 MiB. When none matches, it tries every power of two from 1 MiB to 64 MiB.
  • A size that is not a power of two, such as CACHE_SLICE_SIZE=10m, is not in the page's list. Set it with PATCH /api/system/cache-slice-size and sliceSizeBytes of 10485760. Without that, the app matches it only through sampled files. Once saved, the page lists that size and shows it as selected.
  • A game whose files all use one size shows a size badge, such as 8 MB slices. A game with several sizes shows Mixed slices. A game that detection has not scanned yet shows no badge.
  • Eviction in remove mode, game and service removal, and corruption repair stop with an error before they delete anything when a sample file cannot be read for a reason other than "not found".
  • Eviction in remove mode also stops when the slice size is Auto and its sample finds no usable KEY: range while the cache path holds files. To let it run, set a manual slice size that matches CACHE_SLICE_SIZE.
Request Body Notes
GET /api/system/cache-slice-size none Returns sliceSizeBytes; null means Auto.
PATCH /api/system/cache-slice-size sliceSizeBytes null selects Auto. Any other value must be a positive multiple of 1 MiB.

Both requests need an account-holder session.

Complete annotated Compose example

The example below is a complete, working compose file. The active lines match Quick Start; every optional setting is present but commented, with its default and when it matters, so copying it is safe.

Complete annotated Compose example - every supported variable
services:
  lancache-manager:
    image: ghcr.io/regix1/lancache-manager:latest
    container_name: lancache-manager
    restart: unless-stopped
    ports:
      - "8080:80"
    volumes:
      - ./data:/data                                # database, API key, themes, prefill state
      - /mnt/lancache/logs:/logs:ro                 # LANCache access logs
      - /mnt/lancache/cache:/cache:ro               # drop :ro to allow cache clearing and game removal
      - /var/run/docker.sock:/var/run/docker.sock   # optional: prefill and containerized nginx log rotation
    environment:
      # --- Required (same as Quick Start) ---
      - PUID=33                                 # user id the app runs as; 33 = shipped Compose value (www-data). Unraid: 99
      - PGID=33                                 # group id; 33 = shipped Compose value. Unraid: 100
      - TZ=America/Chicago                      # IANA timezone; default UTC
      - LanCache__LogPath=/logs/access.log      # access log inside the container
      - LanCache__CachePath=/cache              # cache dir inside the container

      # --- PostgreSQL (the defaults run embedded Postgres with no extra setup) ---
      # - POSTGRES_MODE=embedded                # embedded (default) or external; the slim image is external-only
      # - POSTGRES_USER=lancache                # default lancache
      # - POSTGRES_PASSWORD=                    # secret; leave unset and the first-run page asks for one
      # External mode only:
      # - POSTGRES_HOST=lancache-db
      # - POSTGRES_PORT=5432
      # - POSTGRES_DB=lancache

      # --- Security ---
      # - Security__EnableAuthentication=true     # before a mode is saved: false selects Unauthenticated
      # - Security__SignInMode=Oidc               # Password, ApiKeyPassword, ApiKeyOidc, Oidc or Unauthenticated; when set, it fixes the mode
      # - Security__Google__ClientId=             # one provider block; Oidc, GitHub, Microsoft and Apple use the same fields
      # - Security__Google__ClientSecretFile=/run/secrets/google_client_secret   # file text, trimmed, is the secret
      # - Security__Google__OwnerSubject=         # provider account ID of the owner
      # - Security__Google__AllowedSubjects=      # CSV of provider account IDs allowed to sign in
      # - Security__RequireAuthForMetrics=false   # true = /metrics needs a Bearer token
      # - Security__GuestSessionDurationHours=6
      # - Security__AllowedOrigins=               # CSV of CORS origins; empty = same-origin only, * = any origin (no credentials)
      # - Security__ForceSecureCookies=false      # set true behind a TLS-terminating proxy
      # - Security__KnownProxyNetworks=           # CSV CIDRs of trusted proxies, e.g. 172.16.0.0/12
      # - Security__TrustAllProxies=false         # never true on an internet-exposed host
      # - Security__ApiKeyPath=/data/security/api_key.txt

      # --- Prefill (auto-detected; set these only when detection fails) ---
      # - Prefill__LancacheIp=192.168.1.10        # cache server IP; the most reliable override
      # - Prefill__NetworkMode=auto               # host, bridge, a Docker network name, or auto
      # - Prefill__LancacheDnsIp=auto             # DNS server IP; bridge mode only
      # - Prefill__SteamDockerImage=ghcr.io/regix1/steam-prefill-daemon:latest
      # - Prefill__EpicDockerImage=ghcr.io/regix1/epic-prefill-daemon:latest
      # - Prefill__BattlenetDockerImage=ghcr.io/regix1/battlenet-prefill-daemon:latest
      # - Prefill__RiotDockerImage=ghcr.io/regix1/riot-prefill-daemon:latest
      # - Prefill__XboxDockerImage=ghcr.io/regix1/xbox-prefill-daemon:latest
      # - Prefill__SessionTimeoutMinutes=120      # lifetime of a non-persistent prefill session
      # - Prefill__StallTimeoutSeconds=180        # advanced: stall cutoff for non-persistent sessions
      # - Prefill__AbandonedLoginTimeoutSeconds=900   # advanced: cleans up sign-ins nobody finishes
      # - Prefill__DaemonBasePath=/data/prefill   # must stay under /data
      # - Prefill__HostDataPath=auto              # host path of /data; set only if detection fails
      # - Prefill__UseTcp=auto                    # auto = TCP on Windows, Unix socket on Linux
      # - Prefill__TcpPort=45555                  # TCP mode only
      # - Prefill__HostTcpPort=                   # TCP mode only; empty picks a free port
      # - Prefill__TcpHost=127.0.0.1              # TCP mode only

      # --- Nginx log rotation (docker.sock for containers; pid: host for host nginx) ---
      # - NginxLogRotation__Enabled=true
      # - NginxLogRotation__ContainerName=        # empty or "auto" finds the "lancache" container
      # - NginxLogRotation__ScheduleHours=24

      # --- API, optimization, cache snapshots ---
      # - ApiOptions__MaxClientsPerRequest=1000
      # - ApiOptions__DefaultClientsLimit=100
      # - CacheSnapshots__RetentionDays=90        # cache-size history retention
      # - CacheSnapshots__IntervalMinutes=60      # advanced: how often to record a snapshot
      # - ASPNETCORE_URLS=http://+:80             # internal bind; leave as-is

      # --- Paths and datasources ---
      # - LanCache__EnvFilePath=/lancache/.env    # unset = auto-search common locations
      # - LanCache__AutoDiscoverDatasources=false # scan /cache and /logs for matching subfolders, up to 3 levels deep
      # Multiple datasources replace LogPath/CachePath above. Keep the numbers
      # contiguous and add more the same way: __2__, __3__, ...
      # - LanCache__DataSources__0__Name=Default
      # - LanCache__DataSources__0__CachePath=/cache
      # - LanCache__DataSources__0__LogPath=/logs
      # - LanCache__DataSources__0__Enabled=true
      # - LanCache__DataSources__1__Name=Steam
      # - LanCache__DataSources__1__CachePath=/steam-cache
      # - LanCache__DataSources__1__LogPath=/steam-logs
      # - LanCache__DataSources__1__Enabled=true

      # --- Power users ---
      # - ConnectionStrings__DefaultConnection=Host=/var/run/postgresql;Database=lancache;Username=lancache;Maximum Pool Size=20;Minimum Pool Size=2   # base string; POSTGRES_* values you also set override its user/password/host/port/db fields; secret if it embeds a password
      # - Logging__LogLevel__LancacheManager.Infrastructure.Platform=Debug   # any logging category; values Trace..None

Coming from 1.10.3? Existing Compose files keep working; nothing was renamed or removed. Four optional variables were added:

Variable What it is for
Prefill__XboxDockerImage Xbox, the fifth prefill platform
Prefill__StallTimeoutSeconds Advanced. How long a prefill may make no progress
Prefill__AbandonedLoginTimeoutSeconds Advanced. How long a prefill sign-in may wait
LanCache__DataSources__<n>__SchemeOverride Bare-metal installs whose log file names defeat auto-detection

You can delete Security__MaxAdminDevices. Current versions ignore it.