Docs/Octet Browser/Guides/Deploy the Edge
MarkdownAsk ChatGPT ↗Ask Claude ↗

Deploy the Edge

The edge is a single static Linux binary, octet-edge. It accepts the browser's connection, terminates its TLS, and forwards the collected data to Octet with your license token. This guide sets it up on its own hostname, such as octet.example.com, with systemd.

Before you start

  • A Linux host, amd64 or arm64, with a public IP address.
  • A DNS name for the edge, such as octet.example.com, with an A record (and AAAA if you use IPv6) pointing straight at that host.
  • Inbound TCP 443 open to the internet, and TCP 80 open while you get the certificate.
  • Outbound TCP 443 to geo.octetproof.com.
  • Your license token. See Credentials.

Nothing may terminate TLS or TCP in front of the edge

The edge must be the machine that accepts the browser's TCP connection and terminates its TLS. It reads properties of that connection, including the user's IP address, and it ignores X-Forwarded-For and similar headers. Anything that terminates TCP or TLS in front of it replaces the browser's connection with its own. The edge then measures that device instead of the user, and verdicts become wrong.

These are not supported in front of the edge:

  • A reverse proxy such as nginx, Caddy, Apache, Traefik or Envoy
  • HAProxy, in HTTP or TCP mode
  • An HTTP(S) or application load balancer, such as AWS ALB or a Google Cloud HTTPS load balancer
  • A Kubernetes Ingress controller
  • A CDN or proxy service, such as Cloudflare's proxy, CloudFront, Fastly or Akamai

These are supported:

  • A public IP on the host itself, with an ordinary firewall or security group
  • A layer 4 load balancer in passthrough mode, which forwards packets without opening its own TCP connection and keeps the client's source IP. Examples are an AWS Network Load Balancer with a TCP listener and client IP preservation, or a Google Cloud passthrough Network Load Balancer.
  • DNS services that only answer queries, such as Cloudflare DNS with the proxy turned off

If you run more than one edge behind a passthrough load balancer, turn on source IP affinity. A browser's WebSocket and its POST are separate connections, and both must reach the same edge.

1. Download and verify the binary

Download the build for your CPU and the checksum file from the v1.2.0 release. On an arm64 host, use octet-edge-linux-arm64 in each command.

curl -fLO https://github.com/octetproof/octet-browser/releases/download/v1.2.0/octet-edge-linux-amd64
curl -fLO https://github.com/octetproof/octet-browser/releases/download/v1.2.0/SHA256SUMS

Check the binary against its checksum:

sha256sum --ignore-missing -c SHA256SUMS

The output must read octet-edge-linux-amd64: OK. If it reads anything else, delete the file and download it again.

To check that SHA256SUMS itself comes from the release workflow of octetproof/octet-browser, download its signature and certificate from the same release and verify them with cosign:

curl -fLO https://github.com/octetproof/octet-browser/releases/download/v1.2.0/SHA256SUMS.sig
curl -fLO https://github.com/octetproof/octet-browser/releases/download/v1.2.0/SHA256SUMS.pem
cosign verify-blob --signature SHA256SUMS.sig --certificate SHA256SUMS.pem \
  --certificate-oidc-issuer https://token.actions.githubusercontent.com \
  --certificate-identity-regexp '^https://github.com/octetproof/octet-browser/\.github/workflows/sign-release\.yml@' \
  SHA256SUMS

cosign prints Verified OK. Then install the binary:

sudo install -m 0755 octet-edge-linux-amd64 /usr/local/bin/octet-edge

2. Create a service user and config directory

sudo useradd --system --no-create-home --shell /usr/sbin/nologin octet-edge
sudo install -d -m 0750 -o root -g octet-edge /etc/octet-edge /etc/octet-edge/tls

3. Get a TLS certificate

The edge serves HTTPS itself, from certificate files you provide. It does not obtain or renew certificates. This example uses Let's Encrypt with certbot in standalone mode, which needs port 80 free while it runs:

sudo certbot certonly --standalone -d octet.example.com

Install a deploy hook, so each issued or renewed certificate is copied to the edge and the edge restarts to load it:

sudo tee /etc/letsencrypt/renewal-hooks/deploy/octet-edge.sh >/dev/null <<'EOF'
#!/bin/sh
set -e
install -m 0640 -o root -g octet-edge "$RENEWED_LINEAGE/fullchain.pem" /etc/octet-edge/tls/fullchain.pem
install -m 0640 -o root -g octet-edge "$RENEWED_LINEAGE/privkey.pem" /etc/octet-edge/tls/privkey.pem
systemctl restart octet-edge || true
EOF
sudo chmod 0755 /etc/letsencrypt/renewal-hooks/deploy/octet-edge.sh
sudo RENEWED_LINEAGE=/etc/letsencrypt/live/octet.example.com /etc/letsencrypt/renewal-hooks/deploy/octet-edge.sh

The edge loads its certificate once, at startup, which is why the hook restarts it.

4. Write the environment file

Create /etc/octet-edge/edge.env:

PORT=443
OCTET_URL=https://geo.octetproof.com
LICENSE=octet_live_v4.public.REPLACE_WITH_YOUR_LICENSE_TOKEN
ALLOWED_ORIGIN=https://www.example.com
EDGE_TLS_CERT_FILE=/etc/octet-edge/tls/fullchain.pem
EDGE_TLS_KEY_FILE=/etc/octet-edge/tls/privkey.pem

Set ALLOWED_ORIGIN to the origin of the pages that load the collector. Separate several origins with commas, with no spaces. Then lock the file down:

sudo chown root:octet-edge /etc/octet-edge/edge.env
sudo chmod 0640 /etc/octet-edge/edge.env

Every setting is described in Edge Configuration.

5. Create the systemd unit

Create /etc/systemd/system/octet-edge.service:

[Unit]
Description=Octet edge
After=network-online.target
Wants=network-online.target

[Service]
User=octet-edge
Group=octet-edge
EnvironmentFile=/etc/octet-edge/edge.env
ExecStart=/usr/local/bin/octet-edge
Restart=on-failure
RestartSec=2
AmbientCapabilities=CAP_NET_BIND_SERVICE
CapabilityBoundingSet=CAP_NET_BIND_SERVICE
NoNewPrivileges=true
ProtectSystem=strict
ProtectHome=true
PrivateTmp=true

[Install]
WantedBy=multi-user.target

CAP_NET_BIND_SERVICE lets the service user listen on port 443. Start the edge:

sudo systemctl daemon-reload
sudo systemctl enable --now octet-edge
sudo journalctl -u octet-edge -n 20

The log shows listening :443 (TLS) when TLS is configured. If it shows plain HTTP, the certificate settings are missing.

6. Check it

From any machine:

curl -s https://octet.example.com/health

The edge answers:

{"ok":true,"role":"octet-edge"}

A healthy /health shows that the edge is up and serving TLS. It does not contact Octet. To check that Octet accepts your license token, send an empty body to /v1/signals:

curl -s -X POST https://octet.example.com/v1/signals -H 'content-type: application/json' -d '{}'

Octet checks the license before it reads the body, so a valid license gets 400 with "reason":"missing_fields", and a refused one gets 401. See Go-Live Checklist for the full test plan.

Update the edge

Download and verify the new release's binary as in step 1, install it over /usr/local/bin/octet-edge, and restart the service:

sudo systemctl restart octet-edge

Next

Embed the Collector on your pages, with apiUrl: 'https://octet.example.com'.