Implementation Plan

Implementation Plan

Phase 1: Directory Structure

Create two new directories:

  • pages/projects/vyos-migration/

  • partials/projects/vyos-migration/

Phase 2: Extract Partials from Monolith

Extract content from the 758-line monolith into 25 partials. Each partial contains only content (no page headers). Comments at top indicate source and includer.

Partial Source (monolith lines) Type

summary.adoc

39-59

Executive summary table

planning-hardware.adoc

68-93

Hardware requirements table

planning-software.adoc

95-116

Software requirements table

planning-verification.adoc

118-135

Pre-migration verification script

phase-a-dns.adoc

144-189

DNS milestone + checkpoint

phase-b-deployment.adoc

191-241

VyOS deployment + checkpoint

phase-c-security.adoc

243-287

Security + checkpoint

phase-d-testing.adoc

289-313

Pre-cutover + checkpoint

phase-e-vrrp.adoc

315-368

VRRP + checkpoint + failover test

phase-f-advanced.adoc

370-400

Advanced features

ref-premigration.adoc

409-430

Pre-migration runbook links

ref-dns.adoc

432-449

DNS runbook links

ref-ha-deployment.adoc

451-513

HA deployment + SPOF tables

ref-vyos-config.adoc

515-528

VyOS runbook links

ref-emergency.adoc

530-543

Emergency procedure links

ref-network.adoc

545-558

Network infrastructure links

ref-postmigration.adoc

560-569

Post-migration runbook links

rollback-dns.adoc

585-598

DNS rollback

rollback-vyos.adoc

600-614

VyOS config rollback

rollback-complete.adoc

616-631

Full rollback to pfSense

post-migration.adoc

687-726

7-day stabilization checklist

related-docs.adoc

728-757

Cross-reference links

Phase 3: Validation Script to Examples

Move final validation script (lines 635-683) to examples/vyos/migration-final-validation.sh.

Phase 4: Create New Partials

4 partials that don’t exist in the monolith:

Partial Purpose

status-dashboard.adoc

Per-phase status table with completion indicators (matches T16g deployment status pattern)

metadata.adoc

PRJ metadata: ID, author, dates, status, completion date, key hostnames

decisions.adoc

Architecture rationale: why VyOS over OPNsense, why VRRP over CARP, why zone-based firewall, why dual-BIND, parallel deployment risk model

field-notes.adoc

Deployment observations: pfSense decommission (2026-03-07), VRRP failover results, pending items (C/F), scope creep backlog

Phase 5: Create Thin Wrapper Pages

13 pages following the T16g pattern — 5-7 lines each:

= Phase A: DNS Infrastructure
:description: BIND9 DNS record migration — 43 A + 43 PTR + 9 CNAME records
:navtitle: Phase A: DNS Infrastructure
:icons: font

include::partial$projects/vyos-migration/phase-a-dns.adoc[]

Multi-partial pages (index, planning, rollback, validation, reference) include 2-5 partials each.

Phase 6: Update Navigation

Remove from nav.adoc line 211 (Runbooks > Firewall & WAN):

*** xref:runbooks/domusdigitalis-vyos-migration.adoc[VyOS Migration (Master)]

Add to Projects section (~line 147):

** Migrations
*** VyOS Migration (pfSense → VyOS)
**** xref:projects/vyos-migration/index.adoc[Overview]
**** xref:projects/vyos-migration/planning.adoc[Planning]
**** Phases
***** xref:projects/vyos-migration/phase-a-dns.adoc[A: DNS Infrastructure]
***** xref:projects/vyos-migration/phase-b-deployment.adoc[B: VyOS VM Deployment]
***** xref:projects/vyos-migration/phase-c-security.adoc[C: Security & Observability]
***** xref:projects/vyos-migration/phase-d-testing.adoc[D: Pre-Cutover Testing]
***** xref:projects/vyos-migration/phase-e-vrrp.adoc[E: VRRP HA]
***** xref:projects/vyos-migration/phase-f-advanced.adoc[F: Advanced Features]
**** xref:projects/vyos-migration/rollback.adoc[Rollback]
**** xref:projects/vyos-migration/validation.adoc[Validation & Stabilization]
**** xref:projects/vyos-migration/reference.adoc[Reference]
**** xref:projects/vyos-migration/decisions.adoc[Decisions & Risks]
**** xref:projects/vyos-migration/field-notes.adoc[Field Notes]

Phase 7: Delete Monolith

Remove pages/runbooks/domusdigitalis-vyos-migration.adoc.