@crvouga/atlas 0.17.0 → 1.1.0

package/dist/server/src/storage.d.ts

@@ -0,0 +1,68 @@
+/**
+ * @module Required S3 storage configuration
+ *
+ * The Atlas server keeps ALL reports and ALL user state (the garbage collection policy and saved settings) in
+ * S3-compatible object storage, and nowhere else: no local folder, no memory, no database. So the storage settings
+ * are required, come only from environment variables (they hold secrets), and have no defaults for where or as whom
+ * to connect. `resolveS3Config` checks every variable in one pass and reports all the problems together;
+ * `startupFailure` renders them as a banner that cannot be missed. `S3_VARIABLES` is the single description of the
+ * variables: the banner, `.env.example` and the documentation table are all made from it.
+ *
+ * @see docs/server.md#required-s3-storage
+ */
+type Env = Readonly<Record<string, string | undefined>>;
+/** One environment variable of the storage configuration. */
+export type S3Variable = {
+    readonly name: string;
+    readonly required: boolean;
+    /** Shown in the banner and the documentation. Never a real secret. */
+    readonly meaning: string;
+    readonly example: string;
+    /** Secrets are never printed, not even when invalid. */
+    readonly secret?: true;
+    /** Returns what is wrong with a value that is set, or null when it is fine. */
+    readonly check: (value: string) => string | null;
+};
+/** Every variable that configures storage, required ones first. */
+export declare const S3_VARIABLES: readonly S3Variable[];
+/** The storage settings once checked: everything needed to open the bucket, with credentials spelled out. */
+export type S3Config = {
+    readonly endpoint: string;
+    readonly bucket: string;
+    readonly region: string;
+    readonly prefix: string;
+    readonly pathStyle: boolean;
+    readonly accessKeyId: string;
+    readonly secretAccessKey: string;
+    readonly sessionToken?: string;
+};
+/** The state of one variable after checking, for the banner. */
+export type S3Finding = {
+    readonly variable: S3Variable;
+    readonly status: 'ok' | 'missing' | 'invalid' | 'unset';
+    readonly problem?: string;
+};
+/** The storage configuration could not be used. `findings` has every variable, not only the first problem. */
+export declare class S3ConfigError extends Error {
+    readonly findings: readonly S3Finding[];
+    readonly reason: string;
+    constructor(findings: readonly S3Finding[], reason?: string);
+}
+/** Looks at every storage variable and returns what each is. Nothing here throws. */
+export declare function inspectS3Env(env: Env): readonly S3Finding[];
+/**
+ * The storage settings from the environment. Throws {@link S3ConfigError}, whose message lists every variable and
+ * marks each missing or invalid one, when any required variable is absent or any set variable is malformed.
+ *
+ * @example
+ * const s3 = resolveS3Config(process.env);
+ */
+export declare function resolveS3Config(env: Env): S3Config;
+/** Where the storage is, without a secret: what the log may say. */
+export declare const describeS3: (config: S3Config) => string;
+/**
+ * The banner printed when the server cannot start because of storage: why storage is required, then EVERY variable by
+ * name with what is wrong with it. Values of secrets are never printed.
+ */
+export declare function startupFailure(findings: readonly S3Finding[], reason: string, detail?: string): string;
+export {};

package/dist/server/src/storage.js

@@ -0,0 +1,125 @@
+/**
+ * @module Required S3 storage configuration
+ *
+ * The Atlas server keeps ALL reports and ALL user state (the garbage collection policy and saved settings) in
+ * S3-compatible object storage, and nowhere else: no local folder, no memory, no database. So the storage settings
+ * are required, come only from environment variables (they hold secrets), and have no defaults for where or as whom
+ * to connect. `resolveS3Config` checks every variable in one pass and reports all the problems together;
+ * `startupFailure` renders them as a banner that cannot be missed. `S3_VARIABLES` is the single description of the
+ * variables: the banner, `.env.example` and the documentation table are all made from it.
+ *
+ * @see docs/server.md#required-s3-storage
+ */
+const hostOf = (value) => {
+    try {
+        const url = new URL(value);
+        if (url.protocol !== 'https:' && url.protocol !== 'http:')
+            return 'must start with https:// (or http:// for a local S3 server)';
+        if (url.username || url.password)
+            return 'must not contain a user name or password; credentials have their own variables';
+        if (url.search || url.hash)
+            return 'must be just the address, with no query or fragment';
+        return null;
+    }
+    catch {
+        return 'is not a URL; write it like https://s3.eu-west-1.amazonaws.com';
+    }
+};
+/** Every variable that configures storage, required ones first. */
+export const S3_VARIABLES = [
+    { name: 'ATLAS_S3_ENDPOINT', required: true, meaning: 'S3 API endpoint of the object storage service', example: 'https://s3.eu-west-1.amazonaws.com', check: hostOf },
+    { name: 'ATLAS_S3_BUCKET', required: true, meaning: 'Bucket that holds reports and user state; it must already exist', example: 'my-atlas-reports',
+        check: value => (/^[a-z0-9][a-z0-9.-]{1,61}[a-z0-9]$/.test(value) ? null : 'must be 3-63 lowercase letters, digits, dots or hyphens, starting and ending with a letter or digit') },
+    { name: 'ATLAS_S3_REGION', required: true, meaning: 'Region of the bucket (`auto` for Cloudflare R2, `us-east-1` for most self-hosted servers)', example: 'eu-west-1',
+        check: value => (/^[a-z0-9][a-z0-9-]*$/.test(value) ? null : 'must be lowercase letters, digits and hyphens, like eu-west-1') },
+    { name: 'ATLAS_S3_ACCESS_KEY_ID', required: true, meaning: 'Access key id of an account that may list, read, write and delete in the bucket', example: 'AKIAEXAMPLE', secret: true,
+        check: value => (/^\S+$/.test(value) ? null : 'must not contain spaces or line breaks') },
+    { name: 'ATLAS_S3_SECRET_ACCESS_KEY', required: true, meaning: 'Secret key that goes with the access key id', example: 'change-me', secret: true,
+        check: value => (/^\S+$/.test(value) ? null : 'must not contain spaces or line breaks') },
+    { name: 'ATLAS_S3_PREFIX', required: false, meaning: 'Folder inside the bucket for everything Atlas writes (default: the bucket root)', example: 'atlas',
+        check: value => (/^[\w./-]+$/.test(value) && !value.split('/').includes('..') ? null : 'may contain only letters, digits, `.`, `_`, `-` and `/`, and no `..`') },
+    { name: 'ATLAS_S3_PATH_STYLE', required: false, meaning: 'Address the bucket as endpoint/bucket/key (default: yes; set 0 for virtual-hosted style)', example: '1',
+        check: value => (['1', '0', 'true', 'false'].includes(value) ? null : 'must be 1, 0, true or false') },
+    { name: 'ATLAS_S3_SESSION_TOKEN', required: false, meaning: 'Session token, only for temporary credentials', example: '', secret: true,
+        check: value => (/^\S+$/.test(value) ? null : 'must not contain spaces or line breaks') }
+];
+/** The storage configuration could not be used. `findings` has every variable, not only the first problem. */
+export class S3ConfigError extends Error {
+    findings;
+    reason;
+    constructor(findings, reason = 'the S3 configuration is missing or invalid') {
+        super(startupFailure(findings, reason));
+        this.findings = findings;
+        this.reason = reason;
+        this.name = 'S3ConfigError';
+    }
+}
+/** Looks at every storage variable and returns what each is. Nothing here throws. */
+export function inspectS3Env(env) {
+    return S3_VARIABLES.map(variable => {
+        const raw = env[variable.name];
+        if (raw === undefined || raw.trim() === '')
+            return { variable, status: variable.required ? 'missing' : 'unset' };
+        const problem = variable.check(raw.trim());
+        return problem ? { variable, status: 'invalid', problem } : { variable, status: 'ok' };
+    });
+}
+/**
+ * The storage settings from the environment. Throws {@link S3ConfigError}, whose message lists every variable and
+ * marks each missing or invalid one, when any required variable is absent or any set variable is malformed.
+ *
+ * @example
+ * const s3 = resolveS3Config(process.env);
+ */
+export function resolveS3Config(env) {
+    const findings = inspectS3Env(env);
+    if (findings.some(finding => finding.status === 'missing' || finding.status === 'invalid'))
+        throw new S3ConfigError(findings);
+    const value = (name) => env[name]?.trim() ?? '';
+    const style = value('ATLAS_S3_PATH_STYLE');
+    return {
+        endpoint: value('ATLAS_S3_ENDPOINT').replace(/\/+$/, ''), bucket: value('ATLAS_S3_BUCKET'), region: value('ATLAS_S3_REGION'),
+        prefix: value('ATLAS_S3_PREFIX').replace(/^\/+|\/+$/g, ''), pathStyle: style === '' ? true : style === '1' || style === 'true',
+        accessKeyId: value('ATLAS_S3_ACCESS_KEY_ID'), secretAccessKey: value('ATLAS_S3_SECRET_ACCESS_KEY'),
+        ...(value('ATLAS_S3_SESSION_TOKEN') ? { sessionToken: value('ATLAS_S3_SESSION_TOKEN') } : {})
+    };
+}
+/** Where the storage is, without a secret: what the log may say. */
+export const describeS3 = (config) => `s3://${config.bucket}/${config.prefix ? `${config.prefix}/` : ''} on ${new URL(config.endpoint).host} (${config.region})`;
+const RULE = '='.repeat(78);
+/**
+ * The banner printed when the server cannot start because of storage: why storage is required, then EVERY variable by
+ * name with what is wrong with it. Values of secrets are never printed.
+ */
+export function startupFailure(findings, reason, detail) {
+    const width = Math.max(...findings.map(finding => finding.variable.name.length));
+    const mark = (finding) => finding.status === 'missing' ? '[MISSING]' : finding.status === 'invalid' ? '[INVALID]' : finding.status === 'ok' ? '[ok]     ' : '[not set]';
+    const line = (finding) => {
+        const { variable } = finding;
+        const note = finding.status === 'invalid' ? `${finding.problem}` : variable.meaning;
+        return `  ${mark(finding)} ${variable.name.padEnd(width)}  ${note}`;
+    };
+    const required = findings.filter(finding => finding.variable.required);
+    const optional = findings.filter(finding => !finding.variable.required);
+    const bad = findings.filter(finding => finding.status === 'missing' || finding.status === 'invalid').map(finding => finding.variable.name);
+    return [
+        '', RULE,
+        '  ATLAS CANNOT START: S3 STORAGE IS NOT USABLE',
+        RULE,
+        `  Why:    ${reason}.`,
+        '  Reason: Atlas stores ALL reports and ALL user state (the garbage collection policy and saved',
+        '          settings) in S3-compatible object storage, and nowhere else. There is no local-disk,',
+        '          in-memory or database fallback, so the server refuses to start without working S3.',
+        ...(detail ? ['', `  S3 said: ${detail}`] : []),
+        '',
+        '  Required environment variables:',
+        ...required.map(line),
+        '',
+        '  Optional environment variables:',
+        ...optional.map(line),
+        '',
+        bad.length ? `  Fix these ${bad.length}: ${bad.join(', ')}` : '  Every variable is well-formed, so the values themselves are wrong; check them against the storage service.',
+        '  See .env.example for a complete example and docs/server.md#required-s3-storage.',
+        '  Exiting with status 2.', RULE, ''
+    ].join('\n');
+}

package/dist/server/src/user-state.d.ts

@@ -0,0 +1,31 @@
+import type { ObjectStore } from '../../reports/src/object-store.js';
+import { type UserState } from '../../schema/src/user-state.js';
+/** Where the user state lives, relative to the store (the bucket plus `ATLAS_S3_PREFIX`). */
+export declare const USER_STATE_KEY = "server/state.json";
+/** The user state as stored: the document, its `revision` and whether the object `exists` yet. */
+export type StoredUserState = {
+    readonly state: UserState;
+    readonly revision: string;
+    readonly exists: boolean;
+};
+/** Raised when the stored user state cannot be trusted. The message says where it is and what to do. */
+export declare class UserStateError extends Error {
+}
+/** The user state of one server: read it, or change it against the revision that was read. */
+export type UserStateStore = {
+    /** Reads the document. Throws {@link UserStateError} when it exists but is unreadable or invalid. */
+    read(): Promise<StoredUserState>;
+    /**
+     * Applies `change` to the stored state and writes the result, if `revision` is still the stored one. Throws a
+     * `UserStateError` starting with "Settings changed" for a stale revision.
+     */
+    update(revision: string, change: (state: UserState) => UserState): Promise<StoredUserState>;
+};
+/**
+ * The user state kept in `store` at {@link USER_STATE_KEY}.
+ *
+ * @example
+ * const userState = userStateStore(s3Backend.store);
+ * const { state } = await userState.read();
+ */
+export declare function userStateStore(store: ObjectStore): UserStateStore;

package/dist/server/src/user-state.js

@@ -0,0 +1,74 @@
+/**
+ * @module User state in S3
+ *
+ * Reads and writes the user state document (`UserStateSchema`: the garbage collection policy and the saved settings) as
+ * one JSON object at `server/state.json` in the object store, which in a running server is the S3 bucket. This is the
+ * only place user state is kept: not a file, not a database, not the browser. A missing object is an empty state
+ * ("nothing chosen yet"); an object that cannot be read or does not match the schema is an error that stops the
+ * server from starting and is never overwritten, so a transient or corrupt read can never silently reset anyone's choices.
+ * Saving refuses a stale revision (the SHA-256 of the stored text), serialised within this process. An object store has
+ * no conditional writes, so two servers saving at the same instant could still race; run one server per bucket.
+ *
+ * @see docs/server.md#user-state-and-garbage-collection
+ */
+import { createHash } from 'node:crypto';
+import { readUtf8, writeUtf8 } from '../../reports/src/object-io.js';
+import { UserStateSchema } from '../../schema/src/user-state.js';
+/** Where the user state lives, relative to the store (the bucket plus `ATLAS_S3_PREFIX`). */
+export const USER_STATE_KEY = 'server/state.json';
+/** Raised when the stored user state cannot be trusted. The message says where it is and what to do. */
+export class UserStateError extends Error {
+}
+const digest = (text) => createHash('sha256').update(text).digest('hex');
+/**
+ * The user state kept in `store` at {@link USER_STATE_KEY}.
+ *
+ * @example
+ * const userState = userStateStore(s3Backend.store);
+ * const { state } = await userState.read();
+ */
+export function userStateStore(store) {
+    let pending = Promise.resolve();
+    const read = async () => {
+        let text;
+        try {
+            text = await readUtf8(store, USER_STATE_KEY);
+        }
+        catch (error) {
+            throw new UserStateError(`The user state ${USER_STATE_KEY} could not be read from S3: ${error instanceof Error ? error.message : String(error)}`);
+        }
+        if (text === null)
+            return { state: { schemaVersion: 1 }, revision: digest(''), exists: false };
+        let json;
+        try {
+            json = JSON.parse(text);
+        }
+        catch {
+            throw new UserStateError(`The user state ${USER_STATE_KEY} in S3 is not valid JSON. Atlas will not overwrite it: fix or delete that object, then restart.`);
+        }
+        const parsed = UserStateSchema.safeParse(json);
+        if (!parsed.success)
+            throw new UserStateError(`The user state ${USER_STATE_KEY} in S3 is invalid (${parsed.error.issues.map(issue => `${issue.path.join('.') || '(document)'}: ${issue.message}`).join('; ')}). Atlas will not overwrite it: fix or delete that object, then restart.`);
+        // The document as written, once it is known to be valid: defaults are not filled in, so a setting nobody chose stays unchosen.
+        return { state: json, revision: digest(text), exists: true };
+    };
+    return {
+        read,
+        update(revision, change) {
+            const run = pending.then(async () => {
+                const held = await read();
+                if (held.revision !== revision)
+                    throw new UserStateError('Settings changed. Reload them before saving.');
+                const next = { ...change(held.state), schemaVersion: 1 };
+                const checked = UserStateSchema.safeParse(next);
+                if (!checked.success)
+                    throw new UserStateError(checked.error.issues.map(issue => `${issue.path.join('.') || '(document)'}: ${issue.message}`).join('; '));
+                const text = `${JSON.stringify(next, null, 2)}\n`;
+                await writeUtf8(store, USER_STATE_KEY, text, 'application/json');
+                return { state: next, revision: digest(text), exists: true };
+            });
+            pending = run.catch(() => undefined);
+            return run;
+        }
+    };
+}

package/docs/agents.md

@@ -144,7 +144,7 @@ workspace selection and test scripts. An existing `atlas.yml` not generated by A
 workflows may still need manual integration. Non-JavaScript suites need their language/tool setup in CI.
 
 Without a server, start with [local verification](quickstart.md). To run a server later, `atlas serve`
-starts one (`http://127.0.0.1:8080`, data in `./atlas-data`); [the server guide](server.md) covers configuration
+starts one (`http://127.0.0.1:8080`; it needs S3-compatible storage configured with the `ATLAS_S3_*` variables, see `.env.example`); [the server guide](server.md) covers configuration
 and authentication. Keep synthetic failure checks in a scratch store rather than a shared production report.
 
 ## What an agent can rely on

package/docs/deploying.md

@@ -2,14 +2,14 @@
 
 This is the production setup. A project runs **one Atlas server**. Developers' machines and every CI job send
 their results to it, as they finish or when they are done, and it shows everyone, developers and the business
-alike, the whole project at once, live. It keeps results on its own disk by default, or in an object-store bucket
-if you prefer; either way nothing is partitioned by run, branch or person: results are layered. The server's API,
+alike, the whole project at once, live. It keeps results (and all its user state) in an S3-compatible bucket and
+nowhere else; nothing is partitioned by run, branch or person: results are layered. The server's API,
 configuration and protocol are in **[the Atlas server](server.md)**; this page is the path to production.
 
 ```
   a developer's worktree ─┐                                       ┌─▶ developers   (browser, live)
-  a CI job, any branch ───┼─ atlas report publish|stream ─▶ SERVER ◀┤   atlas serve: keeps layers in ./atlas-data
-  a device lab, nightly ──┘   (immutable layers, over HTTP)  or S3  ├─▶ business      or in a bucket (--write)
+  a CI job, any branch ───┼─ atlas report publish|stream ─▶ SERVER ◀┤   atlas serve: keeps layers in S3
+  a device lab, nightly ──┘   (immutable layers, over HTTP)  ──▶ S3  ├─▶ business      (required, nothing else)
                                                                     └─▶ CI gate     atlas report status
 ```
 
@@ -18,7 +18,7 @@ Why this holds together:
 - **Publishing never conflicts.** A layer is one immutable file named by its content. Two machines that
   publish at once write different files; a retry writes the same one. There is no lock, no index to
   corrupt, nothing to merge.
-- **The server is replaceable.** What it knows is its write backend (a folder, or a bucket). Replace it, restore it
+- **The server is replaceable.** What it knows is in its bucket. Replace it, restore it
   from a backup, or run a copy on a laptop: they show the same report, because a report is a function of the
   layers ([the contract](report-contract.md)).
 - **One view.** The newest completed result of every check, in every environment, from anyone. A
@@ -36,13 +36,15 @@ Why this holds together:
 
 ## 1. Where results are kept
 
-**By default, on the server's own disk** (`./atlas-data`, or the volume you mount at `ATLAS_DATA`). Nothing else
-needs to exist: skip to [section 3](#3-send-results-from-ci-and-from-laptops). Back that folder up like any data
-directory; starting a new server on a restored copy shows the same report.
+**The server keeps everything in one S3-compatible bucket** (reports and user state, such as the garbage collection
+policy), set by the required `ATLAS_S3_ENDPOINT`, `ATLAS_S3_BUCKET`, `ATLAS_S3_REGION`, `ATLAS_S3_ACCESS_KEY_ID` and
+`ATLAS_S3_SECRET_ACCESS_KEY` variables ([details](server.md#required-s3-storage), template in
+[`.env.example`](https://github.com/crvouga/atlas/blob/main/.env.example)). Without them it refuses to start, listing
+every variable and what is wrong. There is no disk or database to fall back to, so the server is replaceable:
+a new one started on the same bucket shows the same report.
 
-**To keep results in a bucket instead** (so a replaced server loses nothing, or CI already has bucket access),
-name it and make it the place uploads go: `ATLAS_STORE=project=s3://my-bucket/atlas/my-project ATLAS_WRITE=project`.
-The rest of this section is that setup. A store is named by a URL. Keys never go in it.
+**Clients and CI** name stores by URL, and a client may publish straight to a bucket or folder as well as to the
+server. A store is named by a URL. Keys never go in it.
 
 | Store | URL |
 | --- | --- |
@@ -190,18 +192,16 @@ A run is uploaded only when its privacy scan passed: the same rule the static cl
 ## 4. The server
 
 ```sh
-atlas serve                    # ATLAS_STORE says where; listens on :8080
+atlas serve                    # ATLAS_S3_* says where; listens on :8080
 ```
 
-It serves the client, the report and the project's specs and runs from all configured backends. It also
-accepts uploads and announces new results on its event stream. Uploads go to `--data` by default;
-use a named `--store project=s3://… --write project` to put uploads in a shared bucket, with publisher permissions.
+It serves the client, the report and the project's specs and runs from its bucket. It also
+accepts uploads and announces new results on its event stream. The bucket's credentials need list, read, write and delete
+permissions (`atlas report policy` prints a least-privilege policy; delete is for the garbage collection you define in the UI).
 
 | Flag | Environment | Meaning |
 | --- | --- | --- |
-| `--store <url>` (repeatable) | `ATLAS_STORE` | Where layers are. Several stores are one report: repeat the flag, or separate them in the variable with commas or new lines. |
-| `--data <dir>` | `ATLAS_DATA` | Local upload backend. Default `./atlas-data`. |
-| `--write <id>` | `ATLAS_WRITE` | Backend that accepts uploads. Default `data`. |
+| | `ATLAS_S3_ENDPOINT`, `ATLAS_S3_BUCKET`, `ATLAS_S3_REGION`, `ATLAS_S3_ACCESS_KEY_ID`, `ATLAS_S3_SECRET_ACCESS_KEY` | **Required.** The S3-compatible bucket that holds all reports and user state. Optional: `ATLAS_S3_PREFIX`, `ATLAS_S3_PATH_STYLE`, `ATLAS_S3_SESSION_TOKEN`. |
 | `--port <n>` | `ATLAS_PORT` or `PORT` | Default 8080. `0` picks a free one. |
 | `--host <h>` | `ATLAS_HOST` or `HOST` | Default `127.0.0.1`. Listening beyond this machine requires tokens or `--insecure`. |
 | `--site <dir>` | `ATLAS_SITE` | The built client. Default: `./atlas-site`, else built once into `~/.cache/atlas/site`. |
@@ -228,9 +228,10 @@ updated `latest`. Pull request builds and failed publications are labelled accor
    Leave the start command unset: the image includes the server and the prebuilt viewer.
 2. Add `ATLAS_TOKEN` with a long random value (generate one with `openssl rand -hex 24`). It grants admin
    access; optionally add separate `ATLAS_PUBLISH_TOKEN` and `ATLAS_READ_TOKEN` for publishers and readers.
-3. Attach a volume at `/data` and set `RAILWAY_RUN_UID=0`: Railway mounts volumes as root, while the image
-   normally runs as `bun` ([Railway volume permissions](https://docs.railway.com/volumes#permissions)).
-   Keep one replica. The volume retains reports and server settings when the image is replaced.
+3. Add the five required storage variables (`ATLAS_S3_ENDPOINT`, `ATLAS_S3_BUCKET`, `ATLAS_S3_REGION`,
+   `ATLAS_S3_ACCESS_KEY_ID`, `ATLAS_S3_SECRET_ACCESS_KEY`) for a bucket you own. The service keeps nothing on its own
+   disk, so no volume is needed and a replaced image loses nothing; without the variables it exits and lists each one.
+   Keep one replica.
 4. Set the healthcheck path to `/readyz` and generate a public domain. The image listens on `0.0.0.0` and
    honors Railway's `PORT`; leave `ATLAS_PORT` unset. Open the domain and sign in with your token as the
    password (any username), or use the viewer's token sign-in.
@@ -244,8 +245,7 @@ Projects publish to that domain with `ATLAS_STORE=https://YOUR-DOMAIN` and their
 [sending results](#3-send-results-from-ci-and-from-laptops). Hosting Atlas needs no project checkout; publishing
 your project's test results still needs the integration described there.
 
-For bucket storage instead, set `ATLAS_STORE=project=s3://my-bucket/atlas/my-project`, `ATLAS_WRITE=project`,
-and the bucket credentials. Keep the `/data` volume for server settings and local state.
+Then open `/admin` to define the garbage collection policy; until you save one, nothing is deleted.
 
 ### Deploy without authentication
 
@@ -261,12 +261,11 @@ In Railway, create a **Docker image** service with:
 ghcr.io/crvouga/atlas-insecure:latest
 ```
 
-Leave the start command unset. Attach a persistent volume at `/data`, set `RAILWAY_RUN_UID=0`, keep one
+Leave the start command unset. Add the required `ATLAS_S3_*` storage variables, keep one
 replica, set the healthcheck to `/readyz` and generate a public domain. Leave `ATLAS_PORT` unset so Railway's
 `PORT` is used. Enable **Settings → Source → Configure Auto Updates → Anytime** to follow `latest`.
 Do not set `ATLAS_TOKEN`, `ATLAS_PUBLISH_TOKEN` or `ATLAS_READ_TOKEN`, or add `auth.tokens` to
-`/data/atlas.server.json`: configured tokens still enable authentication. When reusing a volume from an
-authenticated deployment, remove its saved auth tokens first. Open the domain directly, including `/admin`
+a configuration file: configured tokens still enable authentication. Open the domain directly, including `/admin`
 for settings (leave the token field blank and choose **Load settings**).
 
 Verify anonymous reads and uploads without an Authorization header:
@@ -287,7 +286,7 @@ leave its `ATLAS_TOKEN` unset. Use the same publishing commands described in
 For local Docker:
 
 ```sh
-docker run --pull always -p 8080:8080 -v atlas-data:/data ghcr.io/crvouga/atlas-insecure:latest
+docker run --pull always -p 8080:8080 --env-file .env ghcr.io/crvouga/atlas-insecure:latest
 ```
 
 Both images publish full commit tags for pinning or rollback. A new GHCR package must be made Public
@@ -297,10 +296,11 @@ once before Railway can pull without registry credentials; see
 ### Docker
 
 The same published image works anywhere Docker runs. It already contains the client (the same
-for every project: the server tells the page where its data is), and keeps results on the volume at `/data`:
+for every project: the server tells the page where its data is), and keeps nothing on its own disk: it needs the
+`ATLAS_S3_*` variables (copy `.env.example` to `.env` and fill it in):
 
 ```sh
-docker run --pull always -p 8080:8080 -v atlas-data:/data \
+docker run --pull always -p 8080:8080 --env-file .env \
   -e ATLAS_TOKEN=$(openssl rand -hex 24) ghcr.io/crvouga/atlas:latest
 ```
 
@@ -309,17 +309,15 @@ back, replace `latest` with the full commit SHA. To build from this repository,
 [`examples/deploy/Dockerfile`](https://github.com/crvouga/atlas/blob/main/examples/deploy/Dockerfile) is the
 alternative for building from an npm version or a local package tarball.
 
-For a bucket as the system of record add `-e ATLAS_STORE=project=s3://my-bucket/atlas/my-project -e ATLAS_WRITE=project -e AWS_REGION=us-east-1`.
-On ECS, EKS or EC2, attach the combined **both** policy (including `server/live/*` for producer leases) to the task, service account or
-instance and set no keys.
+The bucket's account needs the combined **both** policy (including `server/live/*` for producer leases and `server/state.json`
+for user state) plus `s3:DeleteObject` for garbage collection. The server does not use ambient AWS roles: pass the keys.
 
 **Try it on one machine.** [`examples/deploy/compose.yaml`](https://github.com/crvouga/atlas/blob/main/examples/deploy/compose.yaml)
-starts the published image on a volume; `compose.s3.yaml` starts it with an S3 server and a bucket as its storage.
+starts the published image with an S3 server (SeaweedFS) and a bucket as its storage; `compose.s3.yaml` is the same stack without tokens.
 Publish to `http://localhost:8080` from your project and open it.
 
 **Kubernetes.** [`examples/deploy/kubernetes.yaml`](https://github.com/crvouga/atlas/blob/main/examples/deploy/kubernetes.yaml):
-one copy (the server is a singleton for the project), results in the bucket, readiness on `/readyz`, an IRSA
-service account.
+one copy (the server is a singleton for the project), results in the bucket (keys from a Secret), readiness on `/readyz`.
 
 **Without a container.** `bun add -d @crvouga/atlas`, then `bunx atlas client build --no-data --out
 atlas-site` and `bunx atlas serve`. Everything it can be told is in
@@ -392,12 +390,13 @@ Narrow it by choice, per consumer, never by moving data:
   listing (one request per thousand layers) runs at the start and every 30 refreshes (five minutes by
   default), which is also how a layer recorded with an old timestamp is found. One small `GET` per new
   layer, once.
-- **Retention.** Atlas deletes nothing. `atlas report doctor` shows what the bucket holds.
-- **Disaster recovery.** The write backend (the data folder, or the bucket) is the only state. Back it up, replicate or version it as you
+- **Retention.** Atlas deletes nothing until you define a garbage collection policy in the UI (`/admin`); it is kept in the bucket as JSON and
+  then removes only superseded layers older than you allow ([details](server.md#user-state-and-garbage-collection)). `atlas report doctor` shows what the bucket holds.
+- **Disaster recovery.** The bucket is the only state (reports and user state). Back it up, replicate or version it as you
   do any data; a server is rebuilt from nothing in the time it takes to read the layers (below). It listens at once
   and answers `/readyz` 503 until it has, so a liveness probe never kills one that is still reading.
-- **A second bucket.** Another team's layers, a device lab, an archive: pass several `--store`s. They are one
-  report, attributed to the store they came from.
+- **A second bucket.** The server reads one bucket. To combine another team's layers or an archive into the
+  report, copy them in with `atlas report merge --into <store>`; clients and `atlas report status` may read several stores.
 
 ## 7. Performance
 

package/docs/reference/cli.md

@@ -16,7 +16,7 @@ atlas — executable statecharts
                [--no-retry] [--output <dir>]
   atlas merge  [--config atlas.config.ts] [--output <dir>] <run-dir> <run-dir>...
   atlas export --specs <dir> --format scxml|mermaid|markdown|json [--out <file>]
-  atlas server [--data <dir>] [--port 8080] [--store <url>]...   one Atlas node: API, projects and client
+  atlas server [--port 8080]                                     one Atlas node: API, projects and client; needs ATLAS_S3_* (atlas serve --help)
   atlas client build [--no-data] [--out <dir>]                    build the project-agnostic Atlas client
   atlas dev    [--port 5180]                                     develop the Atlas server and client on one host
   atlas init   [--server <url>] [--write]                         integrate this project: detect its suites, print the plan (atlas init --help)
@@ -53,14 +53,18 @@ atlas init — integrate a project with an Atlas server
 ```text
 atlas serve: the Atlas server
 
-  atlas serve [--config atlas.server.json] [--data <dir>] [--port 8080] [--host 127.0.0.1]
-              [--store <url|id=url>]... [--write <id>] [--site <dir>]
+  atlas serve [--config atlas.server.json] [--port 8080] [--host 127.0.0.1] [--site <dir>]
               [--outline-branch <b>] [--branch <name>]... [--ignore-modified] [--refresh <seconds>]
               [--anonymous-read] [--insecure] [--no-log]
 
   One process serves the client and the API. Test results are uploaded to it from anywhere (laptops, CI) and it
-  shows everyone the combined report, live. It keeps its data in --data (default ./atlas-data) and can read more
-  backends (--store): S3, other servers, folders. Uploads go to the data folder unless --write names another.
+  shows everyone the combined report, live.
+
+  Storage is required. ALL reports and ALL user state (the garbage collection policy, saved settings) are kept in
+  S3-compatible object storage and nowhere else; there is no local-disk, in-memory or database fallback. Without
+  these environment variables the server prints every one of them with what is wrong, and exits with status 2:
+    ATLAS_S3_ENDPOINT  ATLAS_S3_BUCKET  ATLAS_S3_REGION  ATLAS_S3_ACCESS_KEY_ID  ATLAS_S3_SECRET_ACCESS_KEY
+  Optional: ATLAS_S3_PREFIX, ATLAS_S3_PATH_STYLE, ATLAS_S3_SESSION_TOKEN. See .env.example.
 
   Tokens (ATLAS_TOKEN admin, ATLAS_PUBLISH_TOKEN, ATLAS_READ_TOKEN, or "auth.tokens" in the config) are required
   to listen beyond this machine unless --insecure. Every option has an environment variable (docs/deploying.md).
@@ -71,11 +75,12 @@ atlas serve: the Atlas server
 ```text
 atlas dev: the Atlas server and the client, for working on either
 
-  atlas dev [--port 5180] [--host 127.0.0.1] [--data <dir>] [--store <url|id=url>]... [--config atlas.server.json]
+  atlas dev [--port 5180] [--host 127.0.0.1] [--config atlas.server.json]
 
   Starts the server (API only, on a port of its own) and the client's dev server, which proxies /api to it, so the
   browser talks to one host and a change to the client shows at once. In production `atlas serve` does both from
-  one process.
+  one process. Storage is the same as for `atlas serve`: the required ATLAS_S3_* environment variables name the S3
+  bucket that holds all reports and user state; without them it exits with status 2 and lists every variable.
 ```
 
 ## atlas report

package/docs/reference/http-api.md

@@ -116,7 +116,7 @@ Responses: `200` Settings editor.; `401` No token, or an unknown one. Send `Auth
 
 `GET /api/settings` · role: admin
 
-Returns editable persisted storage/report settings, active settings, a revision, and configuration precedence. Authentication settings are excluded. Requires an admin Bearer token. Embedded applications may manage settings outside this API.
+Returns the editable report and live-run settings saved in the user state in S3, active settings, a revision, and configuration precedence. Storage and authentication settings are excluded. Requires an admin Bearer token. Embedded applications may manage settings outside this API.
 
 Responses: `200` Settings and revision.; `401` No token, or an unknown one. Send `Authorization: Bearer <token>`.; `403` The token is known but its role may not do this.; `503` Configuration is managed by the embedding application.
 
@@ -124,12 +124,40 @@ Responses: `200` Settings and revision.; `401` No token, or an unknown one. Send
 
 `PUT /api/settings` · role: admin
 
-Replaces editable storage/report settings, preserving authentication and other file fields. Atomically persists a validated configuration; no report data is moved. Environment variables and flags override these values after restart. Requires an admin Bearer token, same-origin requests in browsers, and a current revision.
+Replaces the editable report and live-run settings in the user state in S3 (`server/state.json`), preserving the garbage collection policy and other fields. Persists a validated configuration; no report data is moved. Environment variables and flags override these values after restart. Requires an admin Bearer token, same-origin requests in browsers, and a current revision.
 
 - `If-Match` (header, required): The quoted revision returned by GET /api/settings.
 
 Responses: `200` Saved settings and new revision. Restart required.; `401` No token, or an unknown one. Send `Authorization: Bearer <token>`.; `403` The token is known but its role may not do this.; `409` Settings changed; reload before saving.; `413` Settings exceed the body limit.; `422` Invalid configuration.; `428` A quoted settings revision is required.; `503` Configuration is managed by the embedding application.
 
+### Read the garbage collection policy
+
+`GET /api/settings/gc` · role: admin
+
+Returns the policy kept in the user state in S3 (`server/state.json`), or `policy: null, saved: false` when none has been saved yet, in which case garbage collection is off and nothing is deleted. Also returns the revision to send back when saving and the last pass over each project. Requires an admin Bearer token. If the stored user state is unreadable the answer is 503 and the stored object is left untouched.
+
+Responses: `200` The policy, its revision and the last passes.; `401` No token, or an unknown one. Send `Authorization: Bearer <token>`.; `403` The token is known but its role may not do this.; `503` The user state in S3 cannot be read, or settings are managed by the embedding application.
+
+### Save the garbage collection policy
+
+`PUT /api/settings/gc` · role: admin
+
+Replaces the policy in the user state in S3 and leaves the rest of that document alone. The server reads the policy from S3 each time it collects, so the new policy applies at the next pass, without a restart. Requires an admin Bearer token, same-origin requests in browsers, and the current revision.
+
+- `If-Match` (header, required): The quoted revision returned by GET /api/settings/gc.
+
+Responses: `200` The saved policy and the new revision.; `401` No token, or an unknown one. Send `Authorization: Bearer <token>`.; `403` The token is known but its role may not do this.; `409` The state changed; reload before saving.; `413` The body exceeds the limit.; `422` Invalid policy.; `428` A quoted revision is required.; `503` The user state in S3 cannot be read, or settings are managed by the embedding application.
+
+### Collect garbage now, or preview it
+
+`POST /api/settings/gc/run` · role: admin
+
+Applies the policy saved in S3 to every project now, instead of waiting for the schedule. Only report layers that were read and no longer decide any result, older than the policy allows and beyond its `keepLatest`, are deleted, with the captured files only they used. With `dryRun=1` nothing is deleted and each run reports what it would delete (a disabled policy is previewed as if enabled). Answers 409 when no policy has been saved, and, without `dryRun`, when the saved policy is disabled. Requires an admin Bearer token and a same-origin request in browsers.
+
+- `dryRun` (query): `1` or `true` to only count what would be deleted.
+
+Responses: `200` One run per project.; `401` No token, or an unknown one. Send `Authorization: Bearer <token>`.; `403` The token is known but its role may not do this.; `409` No policy has been saved, or it is disabled.
+
 ### Is the process up
 
 `GET /healthz` · role: none