Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
321 changes: 206 additions & 115 deletions src/content/docs/docs/configuration.md

Large diffs are not rendered by default.

2 changes: 1 addition & 1 deletion src/content/docs/docs/export-streams.md
Original file line number Diff line number Diff line change
Expand Up @@ -100,7 +100,7 @@ own copy the same way to find the rows (`lower(hex(SHA256(lower(email))))` in Cl
Events by Contact and Visitor. Use the hashes on Contacts and Outbound messages.

Erasure rows are kept for the instance's Event retention window
(`SPHERICON_EVENTS_RETENTION_DAYS`, 400 days by default), and for good when retention is off.
(`SPHERICON_EVENTS_RETENTION`, 400 days by default), and for good when retention is off.
Deletion by retention is not announced: your copy follows your own retention. Apply the erasures
after loading the other streams, on every run: deleting twice is harmless.

Expand Down
2 changes: 1 addition & 1 deletion src/content/docs/docs/guide/tracking.md
Original file line number Diff line number Diff line change
Expand Up @@ -176,7 +176,7 @@ curl https://sphericon.example.com/api/events/batch \
webhook endpoint receives it, so loading history never sends mail.
- Every backfilled event needs an `occurredAt` that has already passed.
- Without `backfill`, an event whose `occurredAt` is more than 72 hours old is refused with a
message that names `backfill` (the window is `SPHERICON_EVENT_LIVE_WINDOW_HOURS`). `/collect` is
message that names `backfill` (the window is `SPHERICON_EVENT_LIVE_WINDOW`). `/collect` is
not limited.
- An event with a `clientEventId` that is already stored changes nothing, so a load that broke off
halfway is resent from the start. The id is unique within the Workspace.
Expand Down
2 changes: 1 addition & 1 deletion src/content/docs/docs/operations/doctor.md
Original file line number Diff line number Diff line change
Expand Up @@ -2,7 +2,7 @@
title: "Diagnosing an Instance with `sphericon doctor`"
---

`sphericon doctor` reads the same configuration as the server (the environment and `.env` files)
`sphericon doctor` reads the same configuration as the server (the process environment)
and checks an Instance from the outside, so you can find what is wrong without asking for help.
Each failed check prints the fix under it. It changes nothing and sends no mail.

Expand Down
14 changes: 7 additions & 7 deletions src/content/docs/docs/operations/scaling.md
Original file line number Diff line number Diff line change
Expand Up @@ -46,12 +46,12 @@ per client connection. There is no PgBouncer-compatible mode.
The data that grows with traffic is the **Event** table. It is pruned in core by a background job.
The policy is [ADR 0019](https://github.com/getsphericon/sphericon/blob/main/docs/adr/0019-event-retention.md).

| Variable | Default | `0` means | What it controls |
| --------------------------------- | ------- | --------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `SPHERICON_EVENTS_RETENTION_DAYS` | `400` | disabled | Deletes **analytical** Events (opens, clicks, deliveries, customer-tracked actions) older than the window, measured from when the row was inserted. Runs daily at 03:00 UTC, in small batches. |
| Variable | Default | `0` means | What it controls |
| ---------------------------- | ------- | --------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `SPHERICON_EVENTS_RETENTION` | `9600h` | disabled | Deletes **analytical** Events (opens, clicks, deliveries, customer-tracked actions) older than the window, measured from when the row was inserted. Runs daily at 03:00 UTC, in small batches. |

Negative values are rejected at startup. Deleting an Event is irreversible, so choose the window
deliberately; to keep everything, set `SPHERICON_EVENTS_RETENTION_DAYS=0`.
The window is a Go duration: `9600h` is 400 days. Deleting an Event is irreversible, so choose the
window deliberately; to keep everything, set `SPHERICON_EVENTS_RETENTION=0`.

### What is kept

Expand All @@ -68,7 +68,7 @@ deliberately; to keep everything, set `SPHERICON_EVENTS_RETENTION_DAYS=0`.
### Segment look-back cap

A [Segment](/docs/guide/segments) condition that looks back further than the retention window only
sees Events that still exist, so its results are capped by `SPHERICON_EVENTS_RETENTION_DAYS`. For example,
sees Events that still exist, so its results are capped by `SPHERICON_EVENTS_RETENTION`. For example,
"opened an email in the last 500 days" behaves like "in the last 400 days" on a default
instance. This is a documented product limit, not a bug. Evidentiary Events are exempt from the
deletion, so conditions on them are not capped.
Expand All @@ -84,5 +84,5 @@ queue, is the durable record of what happened.
## Disk

Disk follows the Event rate. With the default window, expect the `events` table to level off at
roughly 400 days of analytical traffic plus all evidentiary Events. Lower `SPHERICON_EVENTS_RETENTION_DAYS`
roughly 400 days of analytical traffic plus all evidentiary Events. Lower `SPHERICON_EVENTS_RETENTION`
to cap disk and backup size sooner.
2 changes: 1 addition & 1 deletion src/content/docs/docs/operations/security.md
Original file line number Diff line number Diff line change
Expand Up @@ -60,7 +60,7 @@ After any rotation, record the new value in your secret store before you discard
`SPHERICON_ENCRYPTION_KEY` is a Tink keyset: it holds several keys, one of them primary. New
secrets are encrypted under the primary key and every key in the keyset can still decrypt, so a
rotation is a sequence you can stop after any step. The commands read the keyset from
`SPHERICON_ENCRYPTION_KEY` (or its `_FILE`); `rotate` and `retire` need no database and print the
`SPHERICON_ENCRYPTION_KEY`; `rotate` and `retire` need no database and print the
new keyset on stdout, so capture it:

1. **Rotate.** `sphericon encryption-key rotate` adds a new primary key and prints the new keyset.
Expand Down
7 changes: 3 additions & 4 deletions src/content/docs/docs/self-hosting.md
Original file line number Diff line number Diff line change
Expand Up @@ -410,10 +410,9 @@ through the release that backfills the ids first if you skipped it. After the up
The chart lives in `charts/sphericon` and is published at every release as an OCI artifact,
`oci://ghcr.io/getsphericon/charts/sphericon`, with the chart version equal to the app version.
Create a Secret with `SPHERICON_DATABASE_URL`, `SPHERICON_JWT_SECRET` and `SPHERICON_ENCRYPTION_KEY` first and
pass its name as `existingSecret` (the chart refuses to render without it). To hand the secrets over as
files instead (see [Secrets from files](/docs/configuration#secrets-from-files)), set `secretFiles.secretName` to the Secret
and `secretFiles.keys` to the variables it holds: the chart mounts it at `/run/secrets/sphericon` and sets
each `<KEY>_FILE`; `existingSecret` is then optional.
pass its name as `existingSecret` (the chart refuses to render without it); the chart exports every key of
the Secret as an environment variable, so put any other secret variable, such as `SPHERICON_SMTP_PASS`, in
it too.

```sh
helm install sphericon oci://ghcr.io/getsphericon/charts/sphericon \
Expand Down
Loading