# HyperSEO installation

## Requirements

- Node.js 22.13 or newer with npm. This package was tested on macOS with Node
  22.23.1. Get Node from [the official download page](https://nodejs.org/en/download).
- Internet access for `npm ci`, website crawling, and optional Google connections.
- A writable local folder and an available loopback port (3226 by default).
- Optional: Git for packaging customized releases (its fixture test skips if Git
  is unavailable). PHP 8+ for WordPress connector contract tests; your own WordPress
  staging site and Google OAuth project for live integration validation.

No Docker, Convex, paid AI key, cloud database, or hosting account is required to
try the local fixture. Node's SQLite API may print an experimental warning on Node
22; that warning alone is not an installation failure. Windows/Linux instructions
use platform-neutral Node scripts; this release's full installation was checked
on macOS, not independently on Windows or Linux.

## Download and verify

Keep the `.zip.sha256` sidecar beside the ZIP. Before extraction, compare the
SHA-256 checksum:

```bash
# macOS
shasum -a 256 hyperseo-0.3.2.zip
# Linux
sha256sum hyperseo-0.3.2.zip
```

```powershell
# Windows PowerShell
Get-FileHash .\hyperseo-0.3.2.zip -Algorithm SHA256
Get-Content .\hyperseo-0.3.2.zip.sha256
```

The digest must match the sidecar. This detects an altered/corrupt download; the
sidecar is not a digital signature. Extract into a dedicated folder outside
another application's source. `RELEASE.json` lists the source commit and file
hashes. The archive contains source and fonts, not installed dependencies, builds,
local website captures, configuration, database rows, or credentials.

## Fresh installation

In the extracted folder containing `package.json`:

```bash
npm run setup
npm start
```

`setup` checks the runtime, preserves/creates `.env.local`, installs dependencies
with `npm ci --include=dev`, and runs `npm run check` (types, tests, build).
It does not start a cloud deployment, authorize an integration, or enable monitoring.
Dependencies include `tsx`, which the local worker needs at runtime; do not install
with `--omit=dev`. Keep the supplied lockfile and dependency versions.

Open **http://127.0.0.1:3226**. `npm start` supervises both processes. Keep its
terminal open and the computer awake for background jobs. Ctrl+C stops both.
For source development, use `npm run dev`; restart the runner after worker-code or
`.env.local` changes. There is no automatic OS service.

To prepare configuration without installing dependencies or running checks:

```bash
npm run setup -- --config-only
```

This is preparation only; run normal setup afterward. The equivalent manual path
is `npm ci --include=dev`, `npm run check`, then `npm start`.

## Local configuration

The setup command copies `.env.example` to `.env.local` only when the latter is
absent. Defaults work without integrations. The supervisor loads this file before
starting the web app and worker; `npm run worker` also loads it directly. Existing
process environment variables take precedence. Use literal values, not shell
expressions or variable interpolation.

```dotenv
HYPERSEO_ORIGIN=http://127.0.0.1:3226
# Optional private absolute path, quoted if it contains spaces:
# HYPERSEO_DATA_DIR="/absolute/path/to/private/hyperseo-data"
```

The canonical origin must use HTTP, `127.0.0.1`, a port between 1024 and 65535, and
no path/query. To use an available alternate port, change the single origin value,
restart, and update any Google OAuth redirect URI to the exact address shown in
Connections. The runner derives the port and always binds to `127.0.0.1`.
Never stop an unrelated application just to free port 3226.

Private data defaults to `.data` in the extracted project. Alternate storage must
be an absolute folder outside the source project. Do not point it into `public`,
`src`, docs, or exported packages. Both processes must share the same folder and
credential key. Windows path example: `"C:/Users/You/HyperSEOData"`.

Google OAuth secrets and WordPress application passwords are entered privately in
**Connections** and encrypted server-side. Do not put secrets in chat transcripts,
`NEXT_PUBLIC_*` variables, example files, or source control.

## First-run checks

1. Run `npm run doctor`. Expect runtime/npm/SQLite/dependency checks to pass.
2. Start with `npm start`, then use another terminal:

   ```bash
   npm run doctor -- --running
   ```

   Expect HTTP 200 and a current worker heartbeat.

3. In the app, choose Fieldwork Studio. Queue **Monitoring → Check now** and see
   the completed audit. Track an opportunity on the fix board.
4. Review/apply a metadata change **to the test website**, verify its HTML, and
   restore the original. Real website implementation is a separate live action.
5. Confirm missing Google/analytics metrics remain missing and recurrence is off.

Diagnostics do not inspect saved credential values or authorize providers.
`npm run doctor -- --running --json` produces a local report; review it before
sharing. It is not a Google/WordPress health certificate.

## Optional Google and WordPress connections

See [Connect Google](README.md#connect-google) for your own Google project,
read-only OAuth consent, property selection, and report synchronization.
The callback defaults to `http://127.0.0.1:3226/api/google/callback`; use the exact
configured address and your own test-user/provider permissions.

For WordPress, `extras/hyperseo-connector.zip` is included in the source download.
It is also available from Connections after starting the app. Install/activate it
on your staging site first and create a dedicated application password privately.
See [Connect a WordPress website](README.md#connect-a-wordpress-website). The
connector version is independent of the HyperSEO app version. Contract tests use
WordPress stubs; they do not establish live theme/plugin/cache compatibility.

## Existing installations

1. Stop the web/worker runner. Securely copy the **entire** private data folder,
   including `hyperseo.sqlite`, any SQLite sidecars, and `credential.key`. Keep
   backups private; a database without its original key cannot decrypt credentials.
2. Extract the new release into a separate folder. Compare your source edits;
   never blanket-overwrite a customized installation.
3. Copy your `.env.local` privately. If using default `.data`, copy the entire
   stopped data folder into the new installation, or configure its original
   absolute external storage path. Never mix a database with a different key.
4. Run setup and review the reported checks. Start only the intended new runner;
   use the same canonical origin or update Google redirects if you change it.
5. Check your saved websites, history, connections, and worker status. For rollback,
   stop the new runner and restore the old source **and** its matching data backup.

Fresh-install scripts preserve data; they are not source-merge or migration planners.
Current startup creates missing SQLite tables but does not reset existing records.

## Packaging your own source

With reviewed code committed and the checkout clean:

```bash
npm run release
```

This creates a ZIP, checksum, and manifest in ignored `exports/hyperseo-VERSION/`.
Only allowlisted tracked source is included; private paths, symlinks, unexpected
files, and an uncommitted checkout stop packaging. Verify a fresh extraction before
handing out a customized release. See [release checks](docs/RELEASE_CHECKLIST.md).