Hostname swap follow-up — Steps 2-7 roadmap (after additive funnel lands) #280

New issue

Open

opened 2026-04-11 21:04:12 +00:00 by forgejo_admin · 0 comments

forgejo_admin commented

2026-04-11 21:04:12 +00:00

Contributor

Type

Feature

Lineage

Decomposition from forgejo_admin/pal-e-platform#278 (Hostname swap step 1). Round 1 review of #278 (review-972-2026-04-11) correctly identified that scoping all 7 migration steps in one ticket violated the 5-minute rule. Step 1 (additive funnel) is now scoped in #278; this ticket holds the roadmap for Steps 2-7 as a planning record. Each step will be filed as its own executable ticket once the prior step lands and we have working knowledge.

This ticket is a roadmap, not an executable unit. It will not be dispatched to a dev agent. Its job is to make the migration plan visible on the board so #278 doesn't look like a one-off and so future-Ava knows what to file next.

Repo

forgejo_admin/pal-e-platform

User Story

As the Superuser (Lucas)
I want a single visible roadmap for the remaining 6 steps of the hostname swap
So that I can see the whole migration arc on the board even though each step is filed and reviewed independently as it becomes executable

Traces to: story:reader-browse on project-pal-e-docs.

Architecture

arch:notes — the notes component in arch-domain-pal-e-docs (id 1410)
arch:k8s-deploy — known traceability debt

Context

The full 7-step plan (Step 1 is in #278, Steps 2-7 are below):

Step	Repo	Description	Depends on
1	pal-e-deployments	Add additive `api.pal-e-docs` funnel via kustomize overlay	#256 (CORS)
2	pal-e-sdk	Bump default `BASE_URL` constant from `pal-e-docs` to `api.pal-e-docs`. Bump SDK minor version. Publish.	Step 1
3	pal-e-mcp	Bump SDK dependency to the new version. Restart MCP. Verify `list_notes` succeeds against new hostname.	Step 2
4	pal-e-api	Update `PAL_E_DOCS_CORS_ORIGINS` env var (per #256's env-driven design) to add `https://pal-e-docs.tail5b443a.ts.net` (the soon-to-be frontend hostname)	#256 lands
5	pal-e-docs-app	Update `VITE_PAL_E_DOCS_API_URL` from `pal-e-docs.tail5b443a.ts.net` to `api.pal-e-docs.tail5b443a.ts.net`. Rebuild image. Redeploy.	Step 2
6	pal-e-deployments	Destructive swap. Repoint `pal-e-docs.tail5b443a.ts.net` ingress backend from the FastAPI service in `pal-e-docs` namespace to the SvelteKit service in `pal-e-production` namespace. Either via ExternalName service in `pal-e-docs` namespace OR by moving the ingress to `pal-e-production` namespace (decide during execution; both satisfy the same-namespace backend constraint).	Steps 2, 3, 4, 5
7	pal-e-deployments	Decommission or redirect `pal-e-production.tail5b443a.ts.net`. Decision: redirect to `pal-e-docs.tail5b443a.ts.net` for one rotation cycle, then decommission once analytics show zero direct hits.	Step 6

File Targets

None — this ticket is a roadmap, not an executable unit. No source files are modified. Per-step file targets live in the per-step sibling tickets, which will be filed individually as each prior step ships. The "files" this ticket touches are the Forgejo issue queue itself (filing future tickets) and the board (this ticket as a visible planning anchor).

Filing Plan

Each step will be filed as its own executable ticket when the prior step's PR is in flight (not waiting for merge — file the next ticket as soon as the current one is reviewable, so the pipeline stays full).

Naming convention for sibling tickets: Hostname swap step N — <description> so they're easy to find and order.

Why not file all 6 right now? Three reasons:

Step 6 has an unresolved tactical decision (ExternalName vs cross-namespace ingress move) that needs working knowledge from Steps 1-5 to choose well.
Steps 4 and 5 have a coordination window that depends on actual deploy timing, not on advance planning.
Filing 6 tickets up-front creates 6 review-gate cycles before the first PR ships. Pipelining the filing matches feedback_smaller_scopes_parallel better than batch-filing.

Acceptance Criteria

This ticket has no executable acceptance criteria — it's a roadmap. It is "done" when all 6 sibling tickets have been filed, executed, and merged. Until then it stays in backlog as a visible planning anchor.

Step 1 (#278) merged
Step 2 (sdk bump) filed, reviewed, merged
Step 3 (mcp bump) filed, reviewed, merged
Step 4 (CORS env update) filed, reviewed, merged
Step 5 (frontend env update + rebuild) filed, reviewed, merged
Step 6 (destructive swap) filed, reviewed, merged
Step 7 (decommission/redirect old hostname) filed, reviewed, merged
After Step 6: curl -I https://pal-e-docs.tail5b443a.ts.net/notes/arch-westside-emails returns content-type: text/html (frontend serving)
After Step 6: curl -I https://api.pal-e-docs.tail5b443a.ts.net/notes/arch-westside-emails returns content-type: application/json (API serving)

Test Expectations

This is a roadmap. Per-step test expectations live on the per-step tickets. The only "test" for this ticket is verifying that all 6 sibling tickets exist and are linked here when the ticket is closed.

Constraints

Do NOT dispatch this ticket to a dev agent — it has no executable target
Do NOT file all 6 sibling tickets at once — file them as the prior step ships
When closing this ticket, link to all 6 sibling tickets for traceability

Checklist

All 6 sibling tickets filed and merged
Final cutover validated end-to-end
Stale rename cleanup ticket (#279) executed after dust settles

forgejo_admin/pal-e-platform#278 — Step 1 (additive funnel)
forgejo_admin/pal-e-api#256 — CORS middleware (dependency)
forgejo_admin/pal-e-platform#279 — stale rename cleanup (executes after this whole roadmap completes)
arch-domain-pal-e-docs (id 1410)
convention-spa-no-subpath-proxy
review-972-2026-04-11 — the review that drove the decomposition into this roadmap

### Type Feature ### Lineage Decomposition from `forgejo_admin/pal-e-platform#278` (Hostname swap step 1). Round 1 review of #278 (review-972-2026-04-11) correctly identified that scoping all 7 migration steps in one ticket violated the 5-minute rule. Step 1 (additive funnel) is now scoped in #278; this ticket holds the **roadmap for Steps 2-7** as a planning record. Each step will be filed as its own executable ticket once the prior step lands and we have working knowledge. This ticket is a **roadmap, not an executable unit.** It will not be dispatched to a dev agent. Its job is to make the migration plan visible on the board so #278 doesn't look like a one-off and so future-Ava knows what to file next. ### Repo `forgejo_admin/pal-e-platform` ### User Story As the Superuser (Lucas) I want a single visible roadmap for the remaining 6 steps of the hostname swap So that I can see the whole migration arc on the board even though each step is filed and reviewed independently as it becomes executable Traces to: `story:reader-browse` on `project-pal-e-docs`. ### Architecture - `arch:notes` — the `notes` component in `arch-domain-pal-e-docs` (id 1410) - `arch:k8s-deploy` — known traceability debt ### Context **The full 7-step plan** (Step 1 is in #278, Steps 2-7 are below): | Step | Repo | Description | Depends on | |---|---|---|---| | 1 | pal-e-deployments | Add additive `api.pal-e-docs` funnel via kustomize overlay | #256 (CORS) | | 2 | pal-e-sdk | Bump default `BASE_URL` constant from `pal-e-docs` to `api.pal-e-docs`. Bump SDK minor version. Publish. | Step 1 | | 3 | pal-e-mcp | Bump SDK dependency to the new version. Restart MCP. Verify `list_notes` succeeds against new hostname. | Step 2 | | 4 | pal-e-api | Update `PAL_E_DOCS_CORS_ORIGINS` env var (per #256's env-driven design) to add `https://pal-e-docs.tail5b443a.ts.net` (the soon-to-be frontend hostname) | #256 lands | | 5 | pal-e-docs-app | Update `VITE_PAL_E_DOCS_API_URL` from `pal-e-docs.tail5b443a.ts.net` to `api.pal-e-docs.tail5b443a.ts.net`. Rebuild image. Redeploy. | Step 2 | | 6 | pal-e-deployments | **Destructive swap.** Repoint `pal-e-docs.tail5b443a.ts.net` ingress backend from the FastAPI service in `pal-e-docs` namespace to the SvelteKit service in `pal-e-production` namespace. Either via ExternalName service in `pal-e-docs` namespace OR by moving the ingress to `pal-e-production` namespace (decide during execution; both satisfy the same-namespace backend constraint). | Steps 2, 3, 4, 5 | | 7 | pal-e-deployments | Decommission or redirect `pal-e-production.tail5b443a.ts.net`. Decision: redirect to `pal-e-docs.tail5b443a.ts.net` for one rotation cycle, then decommission once analytics show zero direct hits. | Step 6 | ### File Targets **None — this ticket is a roadmap, not an executable unit.** No source files are modified. Per-step file targets live in the per-step sibling tickets, which will be filed individually as each prior step ships. The "files" this ticket touches are the Forgejo issue queue itself (filing future tickets) and the board (this ticket as a visible planning anchor). ### Filing Plan Each step will be filed as its own executable ticket when the prior step's PR is in flight (not waiting for merge — file the next ticket as soon as the current one is reviewable, so the pipeline stays full). **Naming convention for sibling tickets:** `Hostname swap step N — <description>` so they're easy to find and order. **Why not file all 6 right now?** Three reasons: 1. **Step 6 has an unresolved tactical decision** (ExternalName vs cross-namespace ingress move) that needs working knowledge from Steps 1-5 to choose well. 2. **Steps 4 and 5 have a coordination window** that depends on actual deploy timing, not on advance planning. 3. **Filing 6 tickets up-front creates 6 review-gate cycles** before the first PR ships. Pipelining the filing matches `feedback_smaller_scopes_parallel` better than batch-filing. ### Acceptance Criteria This ticket has no executable acceptance criteria — it's a roadmap. It is "done" when all 6 sibling tickets have been filed, executed, and merged. Until then it stays in `backlog` as a visible planning anchor. - [ ] Step 1 (#278) merged - [ ] Step 2 (sdk bump) filed, reviewed, merged - [ ] Step 3 (mcp bump) filed, reviewed, merged - [ ] Step 4 (CORS env update) filed, reviewed, merged - [ ] Step 5 (frontend env update + rebuild) filed, reviewed, merged - [ ] Step 6 (destructive swap) filed, reviewed, merged - [ ] Step 7 (decommission/redirect old hostname) filed, reviewed, merged - [ ] After Step 6: `curl -I https://pal-e-docs.tail5b443a.ts.net/notes/arch-westside-emails` returns `content-type: text/html` (frontend serving) - [ ] After Step 6: `curl -I https://api.pal-e-docs.tail5b443a.ts.net/notes/arch-westside-emails` returns `content-type: application/json` (API serving) ### Test Expectations This is a roadmap. Per-step test expectations live on the per-step tickets. The only "test" for this ticket is verifying that all 6 sibling tickets exist and are linked here when the ticket is closed. ### Constraints - Do NOT dispatch this ticket to a dev agent — it has no executable target - Do NOT file all 6 sibling tickets at once — file them as the prior step ships - When closing this ticket, link to all 6 sibling tickets for traceability ### Checklist - [ ] All 6 sibling tickets filed and merged - [ ] Final cutover validated end-to-end - [ ] Stale rename cleanup ticket (#279) executed after dust settles ### Related - `forgejo_admin/pal-e-platform#278` — Step 1 (additive funnel) - `forgejo_admin/pal-e-api#256` — CORS middleware (dependency) - `forgejo_admin/pal-e-platform#279` — stale rename cleanup (executes after this whole roadmap completes) - `arch-domain-pal-e-docs` (id 1410) - `convention-spa-no-subpath-proxy` - `review-972-2026-04-11` — the review that drove the decomposition into this roadmap