neorelay/UPGRADING.md

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.