# Upgrading NeoRelay

This source kit is a complete, versioned application source set for upgrading
an existing NeoRelay deployment. It is not a deployment-specific patch and it
does not contain infrastructure configuration, credentials, or persistent
state.

## Compatibility

- Upgrade NeoBear, NeoDrop, NeoGuard, and the NeoDrop manager as one tested set.
- Preserve the existing `{{NEODROP_CRYPTO_CONTEXT}}` value exactly. Changing it
  makes existing encrypted links unreadable.
- Preserve the existing NeoDrop protocol framing and all operator trust
  decisions, including origins, proxy peers, source networks, and state paths.
- `scripts/customize-glowing-bear.pl` targets Glowing Bear revision
  `d182657a3b882cfb54e294f9a56fbdd2954d73b0`. Test any other revision before
  deployment.
- Do not replace operator-managed WeeChat, IRC, proxy, service, DNS, TLS, or
  firewall configuration with values inferred from this kit.

## 1. Verify And Inventory

1. Verify the archive checksum through a trusted channel.
2. Run `sha256sum -c MANIFEST.sha256` from the extracted kit.
3. Record the currently deployed version and hashes of its rendered runtime
   files and integration configuration.
4. Inventory every `{{PLACEHOLDER}}` and map it to the existing deployment's
   protected source of truth. Do not select new values during an application
   update unless the operator has approved a separate configuration change.

## 2. Back Up

Create and test a protected, application-consistent backup of:

- NeoDrop's database and ciphertext object tree as one coordinated snapshot;
- the encrypted manager catalog, catalog key, API token material, and verifier;
- the NeoGuard database and shared authentication key;
- WeeChat configuration, secure data, certificates, and plugin state;
- the current rendered application files and operator integration files.

Stop writers or use storage-specific atomic snapshot procedures. Preserve file
ownership and modes. Confirm that the backup can be restored before upgrading.

## 3. Render A Staging Tree

1. Extract the kit into a new temporary directory, not over the live tree.
2. Resolve placeholders from the existing protected configuration with
   context-appropriate validation and escaping.
3. Supply reviewed branding assets and operator-owned integration files.
4. Recreate `MANIFEST.sha256` after rendering.
5. Confirm the rendered tree contains no unresolved placeholders, credentials,
   private keys, capability URLs, state, logs, or backups.

The generic source kit intentionally contains documented placeholders. A
rendered deployment artifact must not contain any unresolved placeholders.

## 4. Test

Run the checks listed in `README.md`, compile native plugins against the target
WeeChat headers, and validate the operator's proxy and service configuration.
In staging, verify:

- an existing encrypted link still downloads and authenticates correctly;
- a new upload, metadata read, download, checksum, expiry, and deletion;
- manager catalog registration and access to existing entries;
- NeoGuard authenticated reporting and recovery;
- origin, source-address, and trusted-proxy enforcement;
- startup from a restored copy of existing persistent state.

## 5. Deploy

Install the rendered files into a versioned directory or otherwise retain the
complete previous runtime tree. Deploy the compatible browser, server, manager,
and guard components as one release. Run health checks before restoring normal
traffic or writes, then record the deployed version and rendered manifest.

## 6. Roll Back

If validation fails, isolate the new version and restore the previous runtime
files and integration configuration. Preserve the original crypto context and
credentials. Restore persistent state only if the upgrade performed
incompatible writes; restore NeoDrop metadata and ciphertext together. Verify
an existing encrypted link, manager catalog access, and component health after
rollback.