Gatehouse edge proxy

Copy Markdown View Source

Gatehouse is the BEAM-native edge proxy/runtime for HostKit-managed hosts. HostKit can now build the Gatehouse release, render semantic ingress into Gatehouse.Config, install the systemd service, and wait until it is active.

The deployment has three pieces:

  1. gatehouse_release builds and installs the Gatehouse release.
  2. ingress declares routing in provider-neutral HostKit terms.
  3. gatehouse installs the runtime env/systemd scaffolding around the rendered config.
use HostKit.DSL, providers: [HostKit.Providers.Gatehouse]

project :edge do
  account :gatehouse, system: true, home: "/var/lib/gatehouse"

  service :hello_phoenix do
    endpoint :http, port: 4000, protocol: :http, health: "/health"
  end

  gatehouse_release :edge,
    source: [github: "dannote/gatehouse", ref: "main"],
    release_path: "/opt/gatehouse"

  service :edge do
    ingress :web,
      path: "/etc/gatehouse/config.exs",
      state: "/var/lib/gatehouse/state.etf" do
      server ":80" do
        route host: "app.example.com" do
          proxy to: endpoint(:hello_phoenix, :http)
        end
      end
    end
  end

  gatehouse :edge,
    release_path: "/opt/gatehouse",
    config_path: "/etc/gatehouse/config.exs",
    state_path: "/var/lib/gatehouse/state.etf",
    run_as: account(:gatehouse)
end

The same ingress declaration can also be consumed by the Caddy provider. HostKit resolves endpoint references at plan time, then renders Gatehouse targets as ordinary URLs.

ingress is the preferred public API for application routing. The lower-level proxy ..., provider: :gatehouse resource remains available as an advanced escape hatch when you need to express Gatehouse-specific listeners, services, balancing, health checks, drain behavior, or TLS details that are not yet modeled by provider-neutral ingress.

The deploy integration defaults to a target-side source build. This path is intentionally heavier, but validates the complete Linux deployment flow:

HOSTKIT_INTEGRATION=1 \
HOSTKIT_GATEHOUSE_DEPLOY_INTEGRATION=1 \
HOSTKIT_INTEGRATION_TOOL=incus \
HOSTKIT_INCUS_INTEGRATION=1 \
mix test test/integration/gatehouse_deploy_test.exs

There is also an experimental HOSTKIT_GATEHOUSE_DEPLOY_MODE=prebuilt path that builds a local release and uploads it to the target. Use it only when the local build host is ABI-compatible with the target OS; otherwise the release ERTS may require a newer glibc than the target provides.