nullforge 0.1.0__py3-none-any.whl

nullforge/runes/containers.py

@@ -0,0 +1,212 @@
+"""Containers deployment module."""
+
+from pyinfra.context import host
+from pyinfra.facts.files import File
+from pyinfra.facts.server import Arch, Which
+from pyinfra.operations import apt, files, server, systemd
+
+from nullforge.models.containers import ContainersBackendType
+from nullforge.molds import ContainersMold, FeaturesMold, UserMold
+from nullforge.smithy.arch import deb_arch
+from nullforge.smithy.http import CURL_ARGS
+from nullforge.smithy.packages import get_pm
+from nullforge.smithy.versions import GPG_KEYS, STATIC_URLS
+
+
+def deploy_containers() -> None:
+    """Deploy containers runtime and related tools."""
+
+    features: FeaturesMold = host.data.features
+    containers_opts: ContainersMold = features.containers
+    user_opts: UserMold = features.users
+
+    match containers_opts.backend_type:
+        case ContainersBackendType.DOCKER:
+            _install_docker()
+            if user_opts.manage:
+                _add_user_to_docker_group(user_opts.name)
+            _install_gvisor()
+        case ContainersBackendType.PODMAN:
+            _install_crun()
+            _install_podman()
+        case ContainersBackendType.CRIO:
+            raise ValueError("CRIO is not supported yet")
+
+    if containers_opts.skopeo:
+        _install_skopeo()
+
+
+def _install_gvisor() -> None:
+    """Install gVisor runtime."""
+
+    pm = get_pm()
+    if pm.is_debian_based:
+        _install_gvisor_debian()
+    elif pm.is_rhel_based:
+        _install_gvisor_rhel()
+    else:
+        host.noop(f"gVisor install skipped: unsupported distro {pm.distro_name}")
+
+
+def _install_gvisor_debian() -> None:
+    """Install gVisor on Debian/Ubuntu via the official APT repo."""
+
+    gvisor_key_path = "/usr/share/keyrings/gvisor-archive-keyring.gpg"
+    apt.key(
+        name="Install gVisor GPG key",
+        src=GPG_KEYS["gvisor"],
+        dest=gvisor_key_path,
+        _sudo=True,
+        _retries=3,
+        _retry_delay=10,
+    )
+
+    apt.sources_file(
+        name="Write gVisor repository source",
+        filename="gvisor",
+        uris="https://storage.googleapis.com/gvisor/releases",
+        suites="release",
+        components="main",
+        architectures=deb_arch(),
+        signed_by=gvisor_key_path,
+        _sudo=True,
+    )
+
+    pm = get_pm()
+    pm.update(
+        name="Update package repositories after adding gVisor repository",
+        _sudo=True,
+    )
+
+    pm.install(
+        name="Install gVisor",
+        packages=["runsc"],
+        _sudo=True,
+    )
+
+
+def _install_gvisor_rhel() -> None:
+    """Install gVisor binaries manually and register as Docker's default runtime."""
+
+    runsc_path = "/usr/local/bin/runsc"
+    if host.get_fact(File, runsc_path):
+        host.noop("gVisor already installed")
+        return
+
+    arch = host.get_fact(Arch)
+    base_url = f"https://storage.googleapis.com/gvisor/releases/release/latest/{arch}"
+
+    files.download(
+        name="Download gVisor runsc binary",
+        src=f"{base_url}/runsc",
+        dest=runsc_path,
+        mode="0755",
+        extra_curl_args=CURL_ARGS,
+        _sudo=True,
+        _retries=3,
+        _retry_delay=10,
+    )
+
+    files.download(
+        name="Download gVisor containerd-shim",
+        src=f"{base_url}/containerd-shim-runsc-v1",
+        dest="/usr/local/bin/containerd-shim-runsc-v1",
+        mode="0755",
+        extra_curl_args=CURL_ARGS,
+        _sudo=True,
+        _retries=3,
+        _retry_delay=10,
+    )
+
+    register_runtime = server.shell(
+        name="Register gVisor as Docker's default runtime",
+        commands=[
+            # `runsc install` creates/updates /etc/docker/daemon.json with the runsc runtime entry.
+            f"{runsc_path} install",
+            # Promote runsc to default-runtime so containers use it without `--runtime=runsc`.
+            'jq \'. + {"default-runtime": "runsc"}\' /etc/docker/daemon.json'
+            " > /etc/docker/daemon.json.tmp && mv /etc/docker/daemon.json.tmp /etc/docker/daemon.json",
+        ],
+        _sudo=True,
+    )
+
+    systemd.service(
+        name="Reload Docker to pick up gVisor runtime",
+        service="docker",
+        reloaded=True,
+        _sudo=True,
+        _if=register_runtime.did_change,
+    )
+
+
+def _install_docker() -> None:
+    """Install Docker using official installation script."""
+
+    if host.get_fact(Which, command="docker"):
+        return
+
+    get_docker_path = "/tmp/get-docker.sh"
+    files.download(
+        name="Download Docker installation script",
+        src=STATIC_URLS["docker_install"],
+        dest=get_docker_path,
+        mode="0755",
+        extra_curl_args=CURL_ARGS,
+        _retries=3,
+        _retry_delay=10,
+    )
+
+    server.shell(
+        name="Install Docker",
+        commands=[f"bash {get_docker_path}"],
+        _sudo=True,
+    )
+
+
+def _add_user_to_docker_group(username: str) -> None:
+    """Add user to docker group."""
+
+    server.user(
+        name=f"Add user {username} to docker group",
+        user=username,
+        groups=["docker"],
+        append=True,
+        _sudo=True,
+    )
+
+
+def _install_skopeo() -> None:
+    """Install skopeo."""
+
+    pm = get_pm()
+    pm.install(
+        name="Install skopeo",
+        packages=["skopeo"],
+        _sudo=True,
+    )
+
+
+def _install_podman() -> None:
+    """Install Podman."""
+
+    pm = get_pm()
+    pm.install(
+        name="Install Podman",
+        packages=[
+            "podman",
+            "podman-compose",
+        ],
+        _sudo=True,
+    )
+
+
+def _install_crun() -> None:
+    pm = get_pm()
+    pm.install(
+        name="Install crun",
+        packages=["crun"],
+        _sudo=True,
+    )
+
+
+deploy_containers()

nullforge/runes/dns.py

@@ -0,0 +1,256 @@
+"""DNS configuration deployment module."""
+
+from pyinfra.context import host
+from pyinfra.facts.files import Link
+from pyinfra.operations import files, server, systemd
+from pyinfra.operations.util import any_changed
+
+from nullforge.models.dns import (
+    DnsMode,
+    DnsProtocol,
+    DnsServer,
+    DnsServerDoH,
+    DnsServerDoT,
+    DnsServerDoU,
+    dns_providers,
+)
+from nullforge.molds import DnsMold, FeaturesMold
+from nullforge.smithy.blocky import BLOCKY_GROUP, BLOCKY_USER, ensure_blocky_binary
+from nullforge.smithy.network import has_ipv6
+from nullforge.smithy.service import ensure_service_user
+from nullforge.templates import BLOCK_TRIM_ENV, get_template_path
+
+
+def deploy_dns_configuration() -> None:
+    """Deploy DNS configuration based on selected mode."""
+
+    ipv6_enabled = has_ipv6()
+    features: FeaturesMold = host.data.features
+    dns_opts: DnsMold = features.dns
+
+    upstream_protocol = (
+        DnsProtocol.DOH
+        if dns_opts.mode == DnsMode.BLOCKY
+        else DnsProtocol.DOT
+        if dns_opts.mode == DnsMode.DOT_RESOLVED
+        else None
+    )
+
+    upstreams: list[DnsServer] = (
+        dns_providers.get_upstreams(
+            dns_opts.upstream_provider,
+            upstream_protocol,
+            ipv6_enabled,
+            dns_opts.ecs,
+        )
+        if upstream_protocol
+        else []
+    )
+
+    match dns_opts.mode:
+        case DnsMode.DOU:
+            raise ValueError("DNS over UDP is not supported yet.")
+        case DnsMode.DOT_RESOLVED:
+            _deploy_dot_resolved(dns_opts, upstreams)
+        case DnsMode.BLOCKY:
+            _deploy_blocky_configuration(dns_opts, upstreams)
+        case DnsMode.NONE:
+            return
+        case _:
+            raise NotImplementedError(f"Unsupported DNS mode: {dns_opts.mode}")
+
+
+def _format_resolved_upstreams(upstreams: list[DnsServer]) -> list[str]:
+    """Render DoT upstreams in `address[:port]#SNI` form for systemd-resolved."""
+
+    servers: list[str] = []
+    for srv in [u for u in upstreams if isinstance(u, DnsServerDoT)]:
+        addr = str(srv.host)
+        endpoint = f"[{addr}]:{srv.port}" if ":" in addr else f"{addr}:{srv.port}"
+        servers.append(f"{endpoint}#{srv.sni}" if srv.sni else endpoint)
+    return servers
+
+
+def _deploy_dot_resolved(opts: DnsMold, upstreams: list[DnsServer]) -> None:
+    """Deploy DNS over TLS configuration."""
+
+    systemd.service(
+        name="Stop and disable blocky DNS proxy",
+        service="blocky",
+        running=False,
+        enabled=False,
+        _sudo=True,
+        _ignore_errors=True,
+    )
+
+    systemd.service(
+        name="Stop and disable dns-internal interface",
+        service="dns-internal",
+        running=False,
+        enabled=False,
+        _sudo=True,
+        _ignore_errors=True,
+    )
+
+    resolved_conf = files.template(
+        name="Configure systemd-resolved for DoT",
+        src=get_template_path("dns/resolved.conf.j2"),
+        dest="/etc/systemd/resolved.conf",
+        mode="0644",
+        DOT=True,
+        DOH=False,
+        DNS_SERVERS=_format_resolved_upstreams(upstreams),
+        _sudo=True,
+    )
+
+    stub_resolv_conf = "/run/systemd/resolve/stub-resolv.conf"
+    resolv_conf = "/etc/resolv.conf"
+    resolved_link = files.link(
+        name="Create symlink to resolv.conf for DoT with systemd-resolved",
+        path=resolv_conf,
+        target=stub_resolv_conf,
+        force=True,
+        _sudo=True,
+    )
+
+    systemd.service(
+        name="Restart systemd-resolved on change",
+        service="systemd-resolved",
+        restarted=True,
+        _sudo=True,
+        _if=any_changed(resolved_conf, resolved_link),
+    )
+
+    systemd.service(
+        name="Ensure systemd-resolved is running and enabled",
+        service="systemd-resolved",
+        running=True,
+        enabled=True,
+        _sudo=True,
+    )
+
+    server.shell(
+        name="Flush DNS cache",
+        commands=[
+            "resolvectl flush-caches",
+        ],
+        _sudo=True,
+        _if=any_changed(resolved_conf, resolved_link),
+    )
+
+
+def _format_blocky_upstreams(upstreams: list[DnsServer]) -> list[str]:
+    result = []
+    for srv in upstreams:
+        if isinstance(srv, DnsServerDoH):
+            result.append(srv.url)
+        elif isinstance(srv, DnsServerDoT):
+            addr = f"[{srv.host}]" if ":" in str(srv.host) else str(srv.host)
+            result.append(f"tcp-tls:{addr}:{srv.port}")
+        elif isinstance(srv, DnsServerDoU):
+            addr = f"[{srv.host}]" if ":" in str(srv.host) else str(srv.host)
+            result.append(f"udp://{addr}:{srv.port}")
+    return result
+
+
+def _deploy_blocky_configuration(opts: DnsMold, upstreams: list[DnsServer]) -> None:
+    """Deploy blocky DNS proxy on the internal link-local interface."""
+
+    ensure_service_user(BLOCKY_USER, BLOCKY_GROUP, "/etc/blocky")
+    binary_op = ensure_blocky_binary()
+    listen = opts.listen_address
+
+    if opts.needs_custom_interface:
+        iface_service_path = "/etc/systemd/system/dns-internal.service"
+        iface_service = files.template(
+            name="Configure dns-internal dummy interface service",
+            src=get_template_path("systemd/dns-internal.service.j2"),
+            dest=iface_service_path,
+            mode="0644",
+            LISTEN_ADDRESS=listen,
+            LISTEN_CIDR=f"{listen}/{listen.max_prefixlen}",
+            _sudo=True,
+        )
+
+        systemd.daemon_reload(
+            name="Reload systemd daemon for dns-internal",
+            _sudo=True,
+            _if=iface_service.did_change,
+        )
+
+        systemd.service(
+            name="Ensure dns-internal interface is running and enabled",
+            service="dns-internal",
+            running=True,
+            enabled=True,
+            _sudo=True,
+        )
+
+    # Deploy blocky config
+    config_dir = "/etc/blocky"
+    config_path = f"{config_dir}/config.yaml"
+    config_template = files.template(
+        name="Configure blocky DNS YAML config",
+        src=get_template_path("dns/blocky.yaml.j2"),
+        dest=config_path,
+        mode="0644",
+        user=BLOCKY_USER,
+        group=BLOCKY_GROUP,
+        jinja_env_kwargs=BLOCK_TRIM_ENV,
+        UPSTREAMS=_format_blocky_upstreams(upstreams),
+        LISTEN_ENDPOINT=f"[{listen}]:53" if listen.version == 6 else f"{listen}:53",
+        _sudo=True,
+    )
+
+    service_path = "/etc/systemd/system/blocky.service"
+    service_template = files.template(
+        name="Configure blocky DNS proxy service",
+        src=get_template_path("systemd/blocky.service.j2"),
+        dest=service_path,
+        mode="0644",
+        CONFIG_PATH=config_path,
+        _sudo=True,
+    )
+
+    systemd.daemon_reload(
+        name="Reload systemd daemon for blocky",
+        _sudo=True,
+        _if=service_template.did_change,
+    )
+
+    restart_ops = [op for op in (binary_op, config_template, service_template) if op]
+    systemd.service(
+        name="Restart blocky on change",
+        service="blocky",
+        restarted=True,
+        _sudo=True,
+        _if=any_changed(*restart_ops),
+    )
+
+    systemd.service(
+        name="Ensure blocky is running and enabled",
+        service="blocky",
+        running=True,
+        enabled=True,
+        _sudo=True,
+    )
+
+    if host.get_fact(Link, path="/etc/resolv.conf"):
+        files.link(
+            name="Remove /etc/resolv.conf symlink",
+            path="/etc/resolv.conf",
+            present=False,
+            _sudo=True,
+        )
+
+    files.template(
+        name="Configure resolv.conf for blocky",
+        src=get_template_path("dns/resolv.conf.j2"),
+        dest="/etc/resolv.conf",
+        mode="0644",
+        LISTEN_ADDRESS=opts.listen_address,
+        _sudo=True,
+    )
+
+
+deploy_dns_configuration()

nullforge/runes/haproxy.py

@@ -0,0 +1,135 @@
+"""HAProxy deployment module."""
+
+from pyinfra import logger
+from pyinfra.context import host
+from pyinfra.facts.files import Directory
+from pyinfra.operations import apt, files
+
+from nullforge.molds import FeaturesMold, HaproxyMold
+from nullforge.smithy.admin import ensure_acl_access
+from nullforge.smithy.packages import get_pm
+from nullforge.smithy.versions import GPG_KEYS, KEYRING_DIR
+
+
+def deploy_haproxy() -> None:
+    """Deploy HAProxy proxy server."""
+
+    features: FeaturesMold = host.data.features
+    haproxy_opts: HaproxyMold = features.haproxy
+
+    _install_haproxy(haproxy_opts)
+    _ensure_pki_dir()
+    if features.users.manage:
+        _setup_acls(features.users.name)
+
+
+def _install_haproxy(opts: HaproxyMold) -> None:
+    """Install HAProxy proxy server."""
+
+    haproxy_version = opts.version
+
+    pm = get_pm()
+
+    if pm.is_debian_based:
+        if pm.is_ubuntu:
+            pm.install(
+                name="Install software-properties-common",
+                packages=["software-properties-common"],
+                no_recommends=True,
+                _sudo=True,
+            )
+
+            apt.ppa(
+                name="Add HAProxy PPA",
+                src=f"ppa:vbernat/haproxy-{haproxy_version}",
+                _sudo=True,
+            )
+
+            pm.update(
+                name="Update package repositories after adding HAProxy PPA",
+                _sudo=True,
+            )
+
+            pm.install(
+                name="Install HAProxy",
+                packages=[f"haproxy={haproxy_version}.*"],
+                _sudo=True,
+            )
+
+        else:
+            # Debian 13 = trixie, Debian 12 = bookworm
+            if pm.distro_major == 13:
+                repo_version = f"trixie-backports-{haproxy_version}"
+            elif pm.distro_major == 12:
+                repo_version = f"bookworm-backports-{haproxy_version}"
+            else:
+                raise ValueError("Unsupported distribution version")
+
+            gpg_key_path = f"{KEYRING_DIR}/haproxy-archive-keyring.gpg"
+            apt.key(
+                name="Install HAProxy GPG key",
+                src=GPG_KEYS["haproxy"],
+                dest=gpg_key_path,
+                _sudo=True,
+                _retries=3,
+                _retry_delay=10,
+            )
+
+            apt.sources_file(
+                name="Write HAProxy repository source",
+                filename="haproxy",
+                uris="https://haproxy.debian.net",
+                suites=repo_version,
+                components="main",
+                signed_by=gpg_key_path,
+                _sudo=True,
+            )
+
+            pm.update(
+                name="Update package repositories after adding HAProxy repository",
+                _sudo=True,
+            )
+
+            pm.install(
+                name="Install HAProxy",
+                packages=[f"haproxy={haproxy_version}.*"],
+                _sudo=True,
+            )
+
+    elif pm.is_rhel_based:
+        logger.warning(
+            f"HAProxy version pin '{haproxy_version}' is Debian/Ubuntu-only; "
+            f"installing version shipped within {pm.distro_name}"
+        )
+        pm.install(
+            name="Install HAProxy",
+            packages=["haproxy"],
+            _sudo=True,
+        )
+
+
+def _ensure_pki_dir() -> None:
+    """Ensure the HAProxy PKI directory exists for ACME certificate management."""
+
+    pki_dir = "/usr/local/etc/haproxy/pki"
+    if not host.get_fact(Directory, pki_dir):
+        files.directory(
+            name="Create HAProxy PKI directory",
+            path=pki_dir,
+            user="root",
+            group="root",
+            mode="0755",
+            _sudo=True,
+        )
+
+
+def _setup_acls(username: str) -> None:
+    """Set up ACLs on HAProxy directories for ACME certificate management."""
+
+    haproxy_dir = "/etc/haproxy"
+    pki_dir = "/usr/local/etc/haproxy/pki"
+    ensure_acl_access(username, haproxy_dir, [f"{haproxy_dir}/haproxy.cfg"])
+    ensure_acl_access(username, pki_dir)
+
+
+deploy_haproxy()

nullforge/runes/monitoring.py

@@ -0,0 +1,21 @@
+"""Monitoring agent deployment module."""
+
+from pyinfra.context import host
+
+from nullforge.molds import FeaturesMold, MonitoringMold
+from nullforge.molds.monitoring import NezhaBackend
+from nullforge.smithy.monitoring.nezha.deploy import deploy_nezha
+
+
+def deploy_monitoring() -> None:
+    """Deploy configured monitoring agent."""
+
+    features: FeaturesMold = host.data.features
+    monitoring: MonitoringMold = features.monitoring
+
+    match monitoring.backend:
+        case NezhaBackend():
+            deploy_nezha(monitoring.backend)
+
+
+deploy_monitoring()