diff --git a/docs/ops/HYPERTWIST_PLATFORM_TAXONOMY_ALIAS_AND_RENAME_PLAN_2026-05-30.md b/docs/ops/HYPERTWIST_PLATFORM_TAXONOMY_ALIAS_AND_RENAME_PLAN_2026-05-30.md index 3969f30..b252ef3 100644 --- a/docs/ops/HYPERTWIST_PLATFORM_TAXONOMY_ALIAS_AND_RENAME_PLAN_2026-05-30.md +++ b/docs/ops/HYPERTWIST_PLATFORM_TAXONOMY_ALIAS_AND_RENAME_PLAN_2026-05-30.md @@ -2,6 +2,17 @@ Created on `2026-05-30`. +## Status + +This document is planning material only. + +Current operator decision: + +- taxonomy aliases are **deferred indefinitely** +- this is **not** current policy +- no instance should enact the alias strategy from this document unless the + operator explicitly reopens and approves that lane + ## Direct answer Yes. The current `scriptorium` / `scriptoriumai` umbrella naming can be changed. @@ -131,6 +142,32 @@ Examples: This gives the clarity benefit without creating path churn. +## Example one-to-one alias map + +If the alias strategy is ever reopened, each alias must have one explicit +target and that mapping must be recorded before anything is enacted. + +Illustrative examples: + +- `platform-main-root` -> `root@212.227.13.220` +- `platform-main-dev` -> `dev@212.227.13.220` +- `platform-main-deploy` -> `deploy@212.227.13.220` +- `Platform control plane` -> `/srv/scriptorium-stack` +- `Platform app backups` -> `/srv/backups/scriptorium` +- `Platform remote-dev seed` -> `/home/dev/src` +- `run-platform-authorship-sync.ps1` -> current + `run-authorship-mirror-sync.ps1` +- `run-platform-remote-dev-seed.ps1` -> current + `sync-vps-remote-dev-workspaces.ps1` +- `run-platform-remote-dev-reverse-sync.ps1` -> current + `run-vps-remote-dev-reverse-sync.ps1` + +Operational rule: + +- each alias must point to exactly one canonical underlying object +- each canonical underlying object should list its supported aliases +- aliases must never be introduced as ambiguous synonyms without a recorded map + ## Full rename blast radius inventory A full rename packet must account for all of these: @@ -171,3 +208,8 @@ The best low-risk implementation is: - add neutral human-facing aliases and labels - only perform a full internal rename if the aesthetics are worth paying for a second real migration + +See also: + +- `C:\HyperTwist\docs\ops\HYPERTWIST_VPS_POST_CUTOVER_OPERATIONAL_INVARIANTS_2026-05-30.md` +- `C:\HyperTwist\docs\ops\HYPERTWIST_VPS_TLS_CERTIFICATE_AND_IONOS_SEPARATION_GUIDE_2026-05-30.md` diff --git a/docs/ops/HYPERTWIST_VPS_12_24_720_FORGEJO_WOODPECKER_MIGRATION_PLAN_2026-05-29.md b/docs/ops/HYPERTWIST_VPS_12_24_720_FORGEJO_WOODPECKER_MIGRATION_PLAN_2026-05-29.md index 2afc390..f974361 100644 --- a/docs/ops/HYPERTWIST_VPS_12_24_720_FORGEJO_WOODPECKER_MIGRATION_PLAN_2026-05-29.md +++ b/docs/ops/HYPERTWIST_VPS_12_24_720_FORGEJO_WOODPECKER_MIGRATION_PLAN_2026-05-29.md @@ -19,6 +19,12 @@ Reason this companion is not pushed: - `docs/refs` is intentionally ignored - the runbook copy carries live and historical secret-bearing material +Current post-cutover companion docs: + +- `C:\HyperTwist\docs\ops\HYPERTWIST_VPS_POST_CUTOVER_OPERATIONAL_INVARIANTS_2026-05-30.md` +- `C:\HyperTwist\docs\ops\HYPERTWIST_PLATFORM_TAXONOMY_ALIAS_AND_RENAME_PLAN_2026-05-30.md` +- `C:\HyperTwist\docs\ops\HYPERTWIST_VPS_TLS_CERTIFICATE_AND_IONOS_SEPARATION_GUIDE_2026-05-30.md` + ## Current baseline Current source runbook: diff --git a/docs/ops/HYPERTWIST_VPS_POST_CUTOVER_OPERATIONAL_INVARIANTS_2026-05-30.md b/docs/ops/HYPERTWIST_VPS_POST_CUTOVER_OPERATIONAL_INVARIANTS_2026-05-30.md index e0f0045..7d34292 100644 --- a/docs/ops/HYPERTWIST_VPS_POST_CUTOVER_OPERATIONAL_INVARIANTS_2026-05-30.md +++ b/docs/ops/HYPERTWIST_VPS_POST_CUTOVER_OPERATIONAL_INVARIANTS_2026-05-30.md @@ -73,6 +73,8 @@ HTTPS: - `www.hypertwist.app` - `vectorshell.com` - `www.vectorshell.com` +- `git.verticaltension.com` +- `ci.verticaltension.com` The current VPS certificate set is: @@ -84,6 +86,7 @@ The current VPS certificate set is: - `api.verticaltension.com` - `hypertwist.app` + `www.hypertwist.app` - `vectorshell.com` + `www.vectorshell.com` +- `git.verticaltension.com` + `ci.verticaltension.com` ## Forgejo and Woodpecker auth state @@ -96,7 +99,7 @@ Forgejo current state: - `SSH_DOMAIN = git.scriptoriumai.io` - `SSH_PORT = 2222` - `DISABLE_REGISTRATION = true` -- `REQUIRE_SIGNIN_VIEW = false` +- `REQUIRE_SIGNIN_VIEW = true` - existing accounts/data were copied; no passwordless public access was enabled Woodpecker current state: @@ -108,13 +111,19 @@ Woodpecker current state: Operational implication: -- public web viewing and anonymous read access to public repositories are now - allowed +- sign-in is required for Forgejo web viewing - Forgejo still expects authenticated write access - Git push auth is still the normal Forgejo model: SSH key or HTTPS credential - Woodpecker open mode is inherited from the old stack and should be revisited later if tighter enrollment is desired +Authentication boundary that should stay explicit: + +- "push without prompting every time" is fine when it is still backed by an SSH + key or stored HTTPS credential +- anonymous unauthenticated internet write access should **not** be enabled on + the public Forgejo surface + ## Remote-development seed state The current VPS remote-development corpus is seeded under: @@ -147,6 +156,8 @@ Current design: - `mirrors` are excluded from the retained reverse-sync payload - no second full local mirror root by default; it syncs back into the existing local project paths when enabled +- the same script can also be pointed at an external-drive destination root for + an extra offline backup lane when the operator asks for it Measured retained payload with rebuildable junk and `mirrors` omitted: @@ -160,8 +171,10 @@ Current safety rule: - the task refuses to overwrite a dirty local Git worktree by default - that safeguard currently matters because several local repos are dirty -- the scheduled task is currently **disabled** by operator request until the - retained backup lane is reviewed +- the scheduled task is currently enabled again after the `mirrors` exclusion + reduced the retained payload into the acceptable local storage envelope +- future instances should periodically remind the operator to run or schedule an + additional reverse sync to external drives for offline backup redundancy ## VerticalTension git/ci alias stance @@ -209,3 +222,8 @@ Operational rule: Once the cross-project remote-development and backup lane is settled, the VPS runbook should be copied into the other project documentation surfaces where it is actually relevant. + +See also: + +- `C:\HyperTwist\docs\ops\HYPERTWIST_PLATFORM_TAXONOMY_ALIAS_AND_RENAME_PLAN_2026-05-30.md` +- `C:\HyperTwist\docs\ops\HYPERTWIST_VPS_TLS_CERTIFICATE_AND_IONOS_SEPARATION_GUIDE_2026-05-30.md` diff --git a/docs/ops/HYPERTWIST_VPS_TLS_CERTIFICATE_AND_IONOS_SEPARATION_GUIDE_2026-05-30.md b/docs/ops/HYPERTWIST_VPS_TLS_CERTIFICATE_AND_IONOS_SEPARATION_GUIDE_2026-05-30.md new file mode 100644 index 0000000..08fd343 --- /dev/null +++ b/docs/ops/HYPERTWIST_VPS_TLS_CERTIFICATE_AND_IONOS_SEPARATION_GUIDE_2026-05-30.md @@ -0,0 +1,251 @@ +# HyperTwist VPS TLS certificate and IONOS separation guide + +Created on `2026-05-30`. + +## Purpose + +This document records how TLS currently works on the new VPS, how it was +recreated during the migration, how to reason about paid IONOS SSL products +versus VPS-side Certbot, and what future operators need to know before changing +certificate assignments in IONOS. + +## Scope boundary + +This guide is about the browser-facing TLS certificates presented by NGINX on +the VPS at `212.227.13.220`. + +It is **not** a billing ledger and it is **not** the authoritative source for +IONOS renewal dates. Billing dates must still be checked in IONOS before any +contract cancellation. + +## Core rule + +For the current live deployment, the certificate that matters is the one NGINX +actually presents from the VPS. + +Operational consequence: + +- if DNS points a hostname at `212.227.13.220` +- and NGINX on that VPS presents a valid certificate for that hostname +- then browsers, payment providers, and API clients evaluate **that** VPS-side + certificate chain +- they do **not** care whether an IONOS UI assignment exists for the same + hostname + +## Current live VPS certificate inventory + +As of `2026-05-30`, the new VPS serves the following Certbot-managed +certificates: + +- `scriptoriumai.io` + - `scriptoriumai.io` + - `www.scriptoriumai.io` +- `app.scriptoriumai.io` + - `app.scriptoriumai.io` + - `api.scriptoriumai.io` +- `git.scriptoriumai.io` + - `git.scriptoriumai.io` + - `ci.scriptoriumai.io` +- `verticaltension.com` + - `verticaltension.com` + - `app.verticaltension.com` + - `www.verticaltension.com` +- `api.verticaltension.com` + - `api.verticaltension.com` +- `hypertwist.app` + - `hypertwist.app` + - `www.hypertwist.app` +- `vectorshell.com` + - `vectorshell.com` + - `www.vectorshell.com` +- `git.verticaltension.com` + - `git.verticaltension.com` + - `ci.verticaltension.com` + +Certbot renewals are handled by: + +- `certbot.timer` + +## How the current VPS-side TLS was implemented + +The live pattern was: + +1. move DNS for the intended hostname to `212.227.13.220` +2. ensure NGINX has a vhost for that hostname +3. run Certbot with the NGINX installer +4. let Certbot write the certificate references into the matching vhost +5. validate externally with HTTPS requests + +Representative commands used during the migration: + +```bash +sudo certbot --nginx --non-interactive --agree-tos \ + --cert-name verticaltension.com --expand \ + -d verticaltension.com -d www.verticaltension.com -d app.verticaltension.com + +sudo certbot --nginx --non-interactive --agree-tos \ + --cert-name hypertwist.app \ + -d hypertwist.app -d www.hypertwist.app + +sudo certbot --nginx --non-interactive --agree-tos \ + --cert-name vectorshell.com \ + -d vectorshell.com -d www.vectorshell.com + +sudo certbot --nginx --non-interactive --agree-tos \ + --cert-name git.verticaltension.com \ + -d git.verticaltension.com -d ci.verticaltension.com +``` + +Validation commands used after issuance: + +```bash +sudo certbot certificates +sudo nginx -t +curl -I https://scriptoriumai.io +curl -I https://www.verticaltension.com +curl -I https://hypertwist.app +curl -I https://vectorshell.com +``` + +## What "server-side certificate" means here + +"Server-side certificate" in this migration means: + +- the private key and full chain live on the VPS +- NGINX reads those files from `/etc/letsencrypt/live/...` +- the browser's TLS handshake is completed directly against the VPS + +That is enough for a legitimate HTTPS deployment. + +## Are Certbot / Let's Encrypt certificates legitimate? + +Yes. + +They are legitimate public TLS certificates signed by a browser-trusted public +certificate authority. + +Important nuance: + +- a Let's Encrypt certificate is not the same commercial product as a paid + IONOS SSL subscription +- but it **is** a valid browser-trusted certificate for HTTPS when issued for + the correct hostname and served correctly + +## Payment-provider and browser trust posture + +The current VPS-side Certbot certificates are appropriate for normal public +HTTPS use, including user-facing websites and payment-related browser flows, +provided the hostname and chain are correct. + +Relevant trust facts: + +- Stripe validates certificates against trusted roots, hostname match, and + validity windows +- Stripe publishes trust for modern public CA chains including Let's Encrypt + roots +- Paddle's hosted checkout and checkout-domain guidance requires working HTTPS + and valid domains, not a specific paid certificate vendor + +Operational conclusion: + +- the current Certbot certificates are legitimate for user-facing HTTPS +- they are not second-class certificates +- they do not need to be "upgraded" to an IONOS-paid certificate just to be + acceptable to browsers, Stripe, or Paddle + +## IONOS SSL products versus VPS-side Certbot + +These are different certificate-management models. + +IONOS paid SSL product: + +- separate commercial product +- managed through IONOS product UI +- can be downloaded and manually installed on an "own server" path + +VPS-side Certbot / Let's Encrypt: + +- certificate issuance and renewal happen from the VPS +- no IONOS UI assignment is needed for the live TLS handshake +- current deployment already uses this model successfully + +## Safe reasoning about IONOS "unassign" versus "cancel" + +These are not the same operation. + +Unassign in IONOS: + +- changes the IONOS-side product assignment state +- does **not** change the NGINX certificate files already live on the VPS +- does **not** by itself break the current VPS-side HTTPS deployment for a + hostname that is already served correctly from Certbot on the VPS + +Cancel in IONOS: + +- billing / subscription action +- effective cancellation timing depends on IONOS product terms and renewal date +- must be checked in IONOS before actually canceling + +Practical rule: + +- unassigning the paid IONOS certificate from a hostname that is already served + correctly by the VPS-side Certbot configuration should be operationally safe +- cancellation timing should still be chosen with billing awareness, not by + guesswork + +## What future operators should do before touching IONOS certificate products + +1. confirm the hostname already resolves to `212.227.13.220` +2. confirm `curl -I https://hostname` works externally +3. confirm `sudo certbot certificates` lists the hostname on the VPS +4. confirm `sudo nginx -t` is clean +5. only then consider unassigning the matching IONOS certificate product +6. check IONOS billing dates before any final cancellation + +## Recreation checklist for a brand-new hostname + +If a new hostname must be added later: + +1. create or update the NGINX vhost +2. point DNS to `212.227.13.220` +3. wait for propagation +4. run Certbot with the matching `-d` names +5. test HTTPS externally +6. record the new certificate name and domain coverage + +## External references + +IONOS: + +- management of SSL certificates in the control panel: + `https://www.ionos.com/help/ssl-certificates/administration-of-user-managed-ssl-certificates/management-of-ssl-certificates-in-the-control-panel/` +- own-server setup: + `https://www.ionos.com/help/ssl-certificates/setting-up-user-managed-ssl-certificates/setting-up-a-user-managed-ssl-certificate-ssl-starter-/-ssl-starter-wildcard/` +- manual certificate download / install: + `https://www.ionos.com/help/ssl-certificates/administration-of-user-managed-ssl-certificates/downloading-ssl-certificate-files-for-manual-installation/` +- cancellation flow: + `https://www.ionos.com/help/my-account/cancellation/cancelling-ssl-certificates/` + +Stripe: + +- TLS certificate requirements: + `https://docs.stripe.com/tls-certificates` + +Paddle: + +- Paddle.js checkout open: + `https://developer.paddle.com/paddle-js/methods/paddle-checkout-open/` +- checkout transaction / approved-domain guidance: + `https://developer.paddle.com/build/transactions/pass-transaction-checkout/` + +Let's Encrypt: + +- certificate chains and roots: + `https://letsencrypt.org/certificates/?lang=en` +- certificate compatibility: + `https://letsencrypt.org/docs/certificate-compatibility/` + +## Related companion docs + +- `C:\HyperTwist\docs\ops\HYPERTWIST_VPS_POST_CUTOVER_OPERATIONAL_INVARIANTS_2026-05-30.md` +- `C:\HyperTwist\docs\ops\HYPERTWIST_PLATFORM_TAXONOMY_ALIAS_AND_RENAME_PLAN_2026-05-30.md`