Running the reference server

Start it

BEACON_KEYS=$(openssl rand -hex 24) npx @snowseo/beacon-server

[beacon] listening on http://0.0.0.0:8787/v3/beacon/hits (1 key(s), ip mode: hash)

That is the whole thing. It refuses to start without at least one key, because a collector that accepts anything is worse than one that is down.

Point your sites at it

The key is whatever you generated. The endpoint may be a bare origin: the ingest path is appended for you.

createBeacon({
  siteUrl: "https://example.com",
  dir: "dist",
  analytics: {
    key: process.env.BEACON_KEY!,
    endpoint: "https://beacon.example.com",
  },
});

define('SNOWSEO_BEACON_ENDPOINT', 'https://beacon.example.com');
define('SNOWSEO_BEACON_KEY', 'the key you generated');

// wp-config.php, above the "stop editing" line
define('SNOWSEO_BEACON_ENDPOINT', 'https://beacon.example.com');
define('SNOWSEO_BEACON_KEY', 'the key you generated');

Docker

BEACON_KEYS=$(openssl rand -hex 24) docker compose up -d

The compose file runs SQLite on a named volume by default and ships a postgres profile:

export BEACON_STORE=postgres
export BEACON_POSTGRES_URL=postgres://beacon:beacon@postgres:5432/beacon
docker compose --profile postgres up -d

Configuration

Variable	Default	Meaning
`BEACON_KEYS`	required	Ingest keys, separated by whitespace or `;`.
`PORT`	`8787`
`HOST`	`0.0.0.0`
`BEACON_STORE`	`sqlite`	`sqlite`, `postgres` or `memory`.
`BEACON_SQLITE_PATH`	`beacon.db`
`BEACON_POSTGRES_URL`	`DATABASE_URL`	Also needs `npm install pg`.
`BEACON_IP_MODE`	`hash`	`hash`, `raw` or `discard`.
`BEACON_IP_SALT`	random	Set it, or hashes change on every restart.
`BEACON_MAX_BODY_BYTES`	`4194304`

Scoping a key to a site

Append @ and a host list to restrict what a key may report for. Wildcards cover any depth of subdomain, and the apex.

BEACON_KEYS="abc123@example.com,*.example.com  def456@other.test"

A key with no @ is unrestricted. Scoping narrows the blast radius if a key leaks: a stolen key can then only pollute the site it was already reporting for.

What happens to IP addresses

Verification runs against the raw address, always. It has to: the address is the one part of a request a crawler cannot dress up, and it is what the CIDR and reverse-DNS checks compare. What gets stored is your choice:

`BEACON_IP_MODE`	Stored	Use when
`hash` (default)	HMAC-SHA256, 32 hex chars	You want to count distinct crawlers without retaining addresses. What SnowSEO does.
`raw`	The address	It is your own collector, your own data, and you have a reason.
`discard`	`null`	You want verification but no address in the database at all.

Deferred reverse-DNS holds the raw address in memory only for as long as the lookup takes.

Set BEACON_IP_SALT. Without it a random salt is generated at boot and the same crawler hashes differently after every restart, which makes “how many distinct addresses” meaningless across a deploy.

What it stores

Two tables. beacon_hits is one row per classified hit; beacon_daily_stats is a pre-aggregated rollup per (date, agent), so a 500-hit batch costs one upsert per pair rather than 500. Both are created on start unless you disable migration. The verification columns are the interesting ones:

Column	Values
`verify_state`	`signed`, `verified`, `unverified`, `spoofed_suspected`
`verify_method`	`web_bot_auth`, `cidr`, `reverse_dns`, or null
`verified`	boolean, true for `signed` and `verified`

unverified and spoofed_suspected are not the same thing and should not be charted together. The first means there was nothing to check against. The second means something checkable contradicts the claim.

Deferred verification

Most hits are settled inline by a CIDR match, which does no I/O. Providers that publish no ranges but do publish an authenticating reverse-DNS suffix are settled after the response, because a DNS round-trip per hit is far too slow for a 500-hit batch. That backfill updates both the hit and its daily rollup. Nothing is lost if it fails; the hit simply stays unverified.

Embedding it instead

If you already have an app, you do not need the HTTP server. The pipeline is exported on its own:

import { ingestBatch, runDeferredVerification } from "@snowseo/beacon-server";

const result = await ingestBatch(host, hits);
await myStore.save(result.rows, result.rollups);
await runDeferredVerification(result.deferred, myStore);

ingestBatch is the same function hosted SnowSEO runs in production. Implement the HitStore interface to persist wherever you like, or extend SqliteHitStore, PostgresHitStore or MemoryHitStore.

Overview

Install

Self-hosting

Reference

Troubleshooting

Running the reference server

Start it

Point your sites at it

Docker

Configuration

Scoping a key to a site

What happens to IP addresses

What it stores

Deferred verification

Embedding it instead

​Start it

​Point your sites at it

​Docker

​Configuration

​Scoping a key to a site

​What happens to IP addresses

​What it stores

​Deferred verification

​Embedding it instead

Start it

Point your sites at it

Docker

Configuration

Scoping a key to a site

What happens to IP addresses

What it stores

Deferred verification

Embedding it instead