nixos/modules/containers/3x-ui.nix

{
  config,
  lib,
  pkgs,
  xlib,
  ...
}:
let
  panel = "${xlib.dirs.services-nodes-folder}/${xlib.device.hostname}/3x-ui";
  # Domain whose Let's Encrypt cert (at /var/lib/acme/<domain>/) gets mounted
  # read-only into the 3x-ui container so the panel can terminate TLS itself.
  # Null when 3x-ui serves plain HTTP and TLS is terminated by an upstream
  # nginx.
  certDomain = config.host."3x-ui".certDomain;
  certMounts =
    if certDomain == null then
      [ ]
    else
      # LE cert mounted read-only so 3x-ui can terminate TLS itself.
      # The 3x-ui settings table must point webCertFile / webKeyFile at
      # /root/cert/fullchain.pem and /root/cert/key.pem.
      map (f: "/var/lib/acme/${certDomain}/${f}:/root/cert/${f}:ro") [
        "fullchain.pem"
        "key.pem"
      ];
  basePorts = [
    # Local-only upstreams for the 3x-ui panel and subscription endpoint.
    # The direct Xray inbound remains publicly reachable on 8443.
    "127.0.0.1:2049:2049/tcp"
    "127.0.0.1:2096:2096/tcp"
    "0.0.0.0:8443:8443/tcp"
  ];
in
{
  # `host."3x-ui"` options are declared in modules/options.nix: they are set
  # by modules/server and modules/vds, so this module cannot be the only place
  # that knows they exist.
  config = {
    virtualisation = {
      podman = {
        enable = true;
        autoPrune = {
          enable = true;
          flags = [ "--all" ];
        };
        dockerCompat = true;
      };
      oci-containers = {
        backend = "podman";
        containers."3xui_app" = {
          image = "ghcr.io/mhsanaei/3x-ui:latest";
          environment = {
            "XRAY_VMESS_AEAD_FORCED" = "false";
            "XUI_ENABLE_FAIL2BAN" = "true";
            "TZ" = "Europe/Moscow";
          };
          volumes = [
            "${panel}/cert/:/root/cert:rw"
            "${panel}/db/:/etc/x-ui:rw"
          ]
          ++ certMounts;
          log-driver = "journald";
          # Adding a new inbound through the 3x-ui panel on a port outside
          # the 14380-15379 range requires extending basePorts and rebuilding.
          ports = basePorts;
        };
      };
    };

    systemd = {
      services = {
        "podman-3xui_app" = {
          serviceConfig = xlib.helpers.mkStorageGuard xlib // {
            Restart = lib.mkOverride 90 "always";
          };
          partOf = [ "podman-compose-3x-ui-root.target" ];
          wantedBy = [ "podman-compose-3x-ui-root.target" ];
        };
        # Auto-update was removed intentionally: the `podman pull` path on the
        # auto-update timer caused the declarative Nix state to diverge from the
        # runtime state in 2026-10-04 (see
        # .agent/decisions/notes/3x-ui-xray-26.9.md). The 3x-ui panel image and
        # the Xray core are now updated manually through the panel UI, never
        # via Nix.
      };
      # Starts/stops together with all 3x-ui compose resources.
      targets."podman-compose-3x-ui-root" = {
        unitConfig.Description = "Root target generated by compose2nix.";
        wantedBy = [ "multi-user.target" ];
      };
      tmpfiles.rules = [
        (xlib.helpers.mkTmpfile "d" xlib.dirs.services-mnt-folder "0755" "root" "root")
        (xlib.helpers.mkTmpfile "d" xlib.dirs.services-nodes-folder "0755" "root" "root")
        (xlib.helpers.mkTmpfile "d" "${xlib.dirs.services-nodes-folder}/${xlib.device.hostname}" "0755"
          "root"
          "root"
        )
        (xlib.helpers.mkTmpfile "d" panel "0755" "root" "root")
        (xlib.helpers.mkTmpfile "d" "${panel}/db" "0755" "root" "root")
        (xlib.helpers.mkTmpfile "d" "${panel}/cert" "0755" "root" "root")
        # Relabel panel dir for SELinux so containers can access it.
        (xlib.helpers.mkTmpfile "Z" panel "0755" "root" "root")
      ];
    };

    # Enable container name DNS for all Podman networks.
    networking.firewall = {
      interfaces =
        let
          matchAll = if !config.networking.nftables.enable then "podman+" else "podman*";
        in
        {
          "${matchAll}".allowedUDPPorts = [ 53 ];
        };
    };
  };
}