VNOX-Server/deploy/central/README.md
loki5512344 c18ccadf99
chore(server): checkpoint deployed services and unfinished forums
User requested a checkpoint and stopped all agents. Deployed artifacts remain the last verified releases; unfinished settings/categories/forums are preserved as WIP. See TODO/roadmap for verification and remaining release/updater work.
2026-11-01 15:31:20 +01:00

5.6 KiB

Central Hub deployment

Current target: central.loki-code.dev, Ubuntu22.04, Nginx443 terminating HTTPS; Hub listener 127.0.0.1:37623 (randomly selected free port). The foundation has no public email-send/registry/friends/DM endpoints. Sign-in endpoints are GitHub and, when SMTP is configured, email one-time codes (hub/AUTH.md). See hub/README.md for exact capability status. SMTP sender display name is Vnox, address noreply@loki-code.dev.

The unverified community directory is now available through GET/POST /v1/servers and owner-only DELETE /v1/servers/{id}. It is separate from cryptographic node registration; see HTTP contract.

Directory deployment: 2026-11-01

  • Hub: d6d406b-directory-7d4ee740d4d9; static musl binary SHA256 7d4ee740d4d93bcc738563838f37e81385d7fe9ca47933924639ce691621a7e0.
  • Web: directory-c885e4689579, served by the existing Nginx /servers fallback.
  • Hub source is committed base d6d406bbf5a50d73d1a5069b1cb57f728ad3e4c5 plus directory-only changes; source.tar.gz and release.json are retained beside the installed binary. Pending account-profile changes were excluded.
  • Production migrations: 1, 2, 3, 4, 5, 7. Migration 6 is the unpublished profile feature; the directory has no dependency on it. Do not renumber applied migrations.
  • Private paired backup, taken while Hub was stopped: /var/backups/vnox-central/deploy-directory-20261101T112022Z/. Issuer identity and email-auth key were preserved. This local snapshot does not complete the roadmap's off-host backup/retention milestone.
  • Verified real public readiness, anonymous session, directory JSON, authenticated mutation gate (anonymous POST returns 401), desktop/mobile page rendering and absence of JavaScript errors. Browser mutation QA uses local fixtures; Hub integration tests verify the persisted authorization and ownership flow.
  • vnox-server.service remained running throughout the update.

Rollback to the preceding Hub binary must account for SQLx migration 7: the old binary rejects unknown applied migration versions. Stop Hub and preserve a current paired snapshot before restoring a compatible database and switching releases. Restoring the pre-deployment database discards subsequent writes; do not do this as a routine binary-only rollback.

Layout

  • /opt/vnox-central/releases/<git-revision>-<binary-hash>/vnox-hub: immutable release.
  • /opt/vnox-central/current: symlink to selected release.
  • /etc/vnox-central/hub.env: real config, root-owned0600, outside Git.
  • /var/lib/vnox-central/: private service data0700, issuer0600 and SQLite.
  • /etc/systemd/system/vnox-central.service: dedicated non-login service user.
  • /etc/nginx/sites-available/central.loki-code.dev: dedicated virtual host.

Only copy explicitly authorized SMTP keys from the existing service in-process. Do not dump Docker environment/config, source secrets into shell logs, add them to command arguments, publish them in preview pages or commit them. Displaying a successful SMTP test is enough; it does not require revealing credentials.

Build and publish

Build from VNOX-Server/, after tests/review, on the installed Rust toolchain:

CC_x86_64_unknown_linux_musl=musl-gcc cargo build --locked --release \
  --target x86_64-unknown-linux-musl -p vnox-hub
sha256sum target/x86_64-unknown-linux-musl/release/vnox-hub

The static musl build avoids depending on a newer local glibc than Ubuntu22.04. Build and verify before uploading. Install into a new revision/hash directory, verify its remote SHA256, switch current atomically, restart only vnox-central, and verify readiness before pointing/reloading the Nginx proxy. Keep the preceding release for rollback; do not replace identity or DB on update.

Install the service/config templates with local paths/port adjusted as needed. Create vnox-central system user and private state dir first. SMTP credentials are supplied only in protected hub.env; example credentials do not work.

Certificate and renewal

Provision HTTP ACME webroot before requesting the cert:

certbot certonly --webroot -w /var/www/vnox-acme -d central.loki-code.dev \
  --non-interactive --agree-tos
nginx -t
systemctl reload nginx

Keep the ACME path available after enabling the HTTP→HTTPS redirect. Certbot's timer handles renewal; a deploy hook validates/reloads Nginx after renewal. Check certificate chain/hostname from outside the VPS, not only with nginx -t. Run renewal staging checks without unnecessary random sleep when unattended.

Verification

systemctl is-active vnox-central
curl --fail http://127.0.0.1:37623/ready
curl --fail https://central.loki-code.dev/ready
curl --fail https://central.loki-code.dev/v1/info

Use a transient systemd service with the same protected EnvironmentFile to run vnox-hub --check-smtp as the service user. It connects/authenticates and issues NOOP without sending a message. Actual delivery needs a separately authorized recipient/test. Previews use dummy tokens and must not be mistaken for working verification links.

Restart once and verify the issuer ID/public key remain unchanged and /ready returns200. Confirm the backend listener is loopback-only, key/env modes are private, other Nginx virtual hosts still work, and SIGTERM exits cleanly.

Back up issuer and SQLite consistently (SQLite backup API/checkpoint or stopped service), with encrypted/private storage; test paired restore. Do not back up only DB and silently generate a new issuer if its key is missing. Future DM payload/attachment backup policy is separate from account/registry state.