# compose.yaml for Open Source SageTV
# Image: sagetvopen/sagetv-server-java11 (most stable as of 2024/2025)
#
# CRITICAL: network_mode must be "host". Without it, the SageTV server
# cannot distinguish LAN extenders (HD300) from remote Placeshifter
# clients, and the HD300 will be greeted with a login prompt instead
# of the SageTV UI.
#
# Because of host networking, the "ports:" section is omitted —
# the container shares the host's network stack directly.
# The port list below is for firewall reference only.
#
# Ports used by SageTV (all on host network):
#   8080/tcp  - Jetty web UI (SageTV web interface)
#   42024/tcp - Primary client<->server communication
#   7818/tcp  - Media streaming (large file transfers to clients)
#   8270/udp  - Automatic server discovery (HD300 "find server" scan)
#   31099/tcp - Extender & Placeshifter server port
#   31100/udp - Extender communication
#   16867/udp - Extender media port
#   16869/udp - Extender media port
#   16881/tcp - Extender media port

services:
  sagetv:
    image: sagetvopen/sagetv-server-java11:latest
    container_name: sagetv
    network_mode: host
    restart: unless-stopped

    environment:
      # --- SageTV Version ---
      # "latest" pulls the newest release on each container start.
      # Pin to a specific version (e.g., "9.2.16.368") to prevent
      # automatic upgrades. Before upgrading, the container automatically
      # backs up Sage.jar, Sage.properties, and Wiz.bin.
      VERSION: "latest"

      # --- Java Heap Memory ---
      # Amount of RAM to give the SageTV JVM, in MB.
      # 768 MB is the default; 1024–2048 is reasonable for a media server
      # with a large library (several hundred recordings).
      JAVA_MEM_MB: "1024"

      # --- File Permissions ---
      # PUID and PGID should match the UID/GID of the user on your HOST
      # that owns the media and appdata directories. This avoids permission
      # conflicts between the container process and your host filesystem.
      #
      # To find your UID/GID, run on your host:  id $(whoami)
      # Common values on a standard Linux system: UID=1000, GID=1000
      PUID: "1000"
      PGID: "1000"

      # --- Optional: License Key ---
      # SageTV v9+ is fully open source and does not require a license.
      # Leave blank.
      LICENCE_DATA: ""

      # --- Optional Add-ons ---
      # OPT_GENTUNER: Installs the GenericTuner plugin (not needed if
      # you have no tuner hardware — set to N for a playback-only setup)
      OPT_GENTUNER: "N"

      # OPT_COMSKIP: Installs comskip binaries for commercial detection.
      # Useful later but not needed for initial bring-up.
      OPT_COMSKIP: "N"

      # OPT_COMMANDIR: CommandIR IR blaster support. Leave N unless you
      # have CommandIR hardware.
      OPT_COMMANDIR: "N"

      # OPT_SETPERMS: If Y, resets ownership/permissions on all SageTV
      # files at every startup. Slower start, but fixes permission issues.
      # Set to Y temporarily if you hit "permission denied" errors.
      OPT_SETPERMS: "N"

    volumes:
      # --- SageTV Application Data ---
      # This is where SageTV stores its configuration: Sage.properties,
      # Wiz.bin (the recording database), plugins, and logs.
      # Map to a persistent directory on your host.
      # The container expects /opt/sagetv; it will create a "server"
      # subdirectory here on first run.
      - /opt/docker/sagetv/appdata:/opt/sagetv

      # --- Recordings / Primary Media Directory ---
      # SageTV will create a "tv" subdirectory here for recordings.
      # Point this at the directory containing your existing SageTV
      # recordings (.mpg files). Read-write so SageTV can manage them.
      - /your/sagetv/recordings:/var/media

      # --- Additional Media (Videos, Music, Photos) ---
      # For your imported video library. SageTV will be configured
      # (via its UI) to look here for non-recorded content.
      # Read-only is fine if SageTV should not modify these files.
      - /your/other/media:/var/mediaext:ro

    # host networking has no "ports:" mapping — the container
    # uses the host's ports directly. Shown here as documentation only:
    #
    # 8080/tcp   Jetty web UI
    # 42024/tcp  Client/server protocol
    # 7818/tcp   Media streaming
    # 8270/udp   Server autodiscovery
    # 31099/tcp  Extender server port
    # 31100/udp  Extender comms
    # 16867/udp  Extender media
    # 16869/udp  Extender media
    # 16881/tcp  Extender media