# Prepare a Gateway host

## Purpose

Prepare a Linux host to run Keystone Gateway from the release tarball. V1 release CI cross-compiles Linux `amd64` and `arm64`; these are the supported release platforms, published as `Linux_x86_64.tar.gz` and `Linux_arm64.tar.gz`. Other Go targets are not a support commitment.

## Required

-   A Linux `amd64` or `arm64` host with `tar`, `systemd`, and `sudo` or root access to install beneath `/opt/particle_horizon`. The Gateway is distributed only as a release tarball; there is no RPM, DEB, or container image.
-   A dedicated unprivileged service account with read access to configuration, license, certificate, and key files, and write access to state and report directories.
-   A persistent local filesystem for `storage.directory`, by default under `/opt/particle_horizon/local_data/keystone-gateway`; in HA, each replica has its own local directory. The process creates its state directory with private permissions.
-   A customer-generated **32-byte raw AES-256-GCM state key** in `storage.encryption_key_file`. Use the same key on both HA replicas. Do not append a newline.
-   DNS or fixed addresses for every configured `advertise_url` and, in HA, peer target. Keep system clocks synchronized; a replica refuses leadership when clock skew exceeds `leases.max_clock_skew_seconds`.
-   One client listener: HTTPS with `mtls` or `none`, or explicitly acknowledged private HTTP with `bearer` or `none`. Exactly one listener is enabled.
-   For mapping-based authentication, one customer-issued client identity or opaque bearer credential per product installation. Each principal is scoped to exactly one of `phocol` or `lmc_exporter`; configure separate principals when serving both types.
-   A signed Gateway license and a release tarball built with the vendor verification key.

## Recommended

-   TLS with mutual TLS for client traffic outside a fully controlled private network.
-   A stable DNS name or load balancer for clients, host firewall rules, encrypted backups, and monitoring of `/readyz`.
-   Separate, owner-readable secret files. Do not place private keys, bearer tokens, state keys, or telemetry headers in source control or command lines.

## Optional

-   A customer-operated OTLP collector for metrics and traces. Telemetry is disabled by default and is never sent to Keystone.
-   HA: a second host, peer TLS certificates, and two private peer ports.

See [security and network flows](https://portal.cjcit.io/knowledge-base/keystone_gateway/0.2/security/deployment-security/) for ports, certificates, and permissions.