Onboarding Guide

Executive Summary

This guide covers onboarding for two scenarios: adding a new consuming site to the RHEA block library (repoless model), and onboarding a new developer to the RHEA project. The process follows a phased approach from project initiation through post-deployment verification.

New Consuming Site Onboarding

In the repoless model, a new consuming site does not get its own code repo. Instead, a new family is added to the abbvie-migrated/eds-site-config repository via an automated GitHub Issue Form, and its configuration deploys to the EDS Admin API on merge. See the eds-site-config README and docs/onboarding.md for the full mechanics.

Phase 1: Project Initiation (repoless via eds-site-config)

# Action Description Owner
1 Request intake Submit site request via the AbbVie EDS intake process Requesting team
2 Architecture review Confirm EDS/RHEA is the appropriate platform (see Migration Strategy gating questions) Architecture team
3 AEM author setup Provision content folder + Cloud Manager program/env in AEM Cloud Service AEM admin
4 Open onboarding issue Issues → New issue → "Onboard a new EDS site family". Provide family_name, org, git_repo, admin_emails (+ per-env hostnames/zone IDs if Cloudflare-fronted) DevOps lead
5 Scaffold PR onboard-site.yml scaffolds sites/<family>/... and opens a PR (branch onboard/<family>-issue-<n>) Automated
6 Manual edits + review Fill in program/env IDs and config_admin tech-account in site.json, review, and merge Developer
7 Auto-deploy On merge, deploy-cloud.yml (and deploy-worker.yml if Cloudflare-fronted) apply the config Automated
8 Cloudflare secrets (CF-fronted only) Add <FAMILY>_<ENV>_CLOUDFLARE_API_TOKEN GitHub secrets before first deploy DevOps lead
Publish-URL fallback
For non-Cloudflare-fronted sites, leave the per-env hostnames blank in the issue form. The scaffolder derives hosts from the EDS publish URLs (<branch>--<eds_site>--<org>.aem.{live,page}) and records hosts.using_publish_urls: true.

Phase 2: Setup and Development

# Action Description Owner
1 Content fragments Author /nav, /footer, and /isi/ fragments for the new site Content author
2 Theme customization Override design tokens as needed for site-specific branding Developer
3 Block overrides Create site-specific block overrides if any RHEA defaults need modification Developer
4 Sidekick installation Install AEM Sidekick browser extension and configure for the new site All team members
5 Local development Set up local dev environment (npm install, npm start) Developer
6 Content authoring Begin authoring pages in AEM Universal Editor Content author
7 Preview validation Verify content and blocks render correctly on preview URLs QA / Developer
8 Analytics configuration Configure data layer events and tracking metadata Developer
9 ISI setup Author ISI content fragments and configure per-page ISI metadata Content author

Phase 3: Pre-Release

# Action Description Owner
1 Accessibility audit Verify WCAG compliance across all pages QA
2 Performance validation Confirm Lighthouse 100 scores on representative pages Developer
3 Cross-browser testing Test on target browsers and devices QA
4 Content review Final content and legal review (especially ISI for pharma sites) Content / Legal
5 Stakeholder sign-off Obtain approval from site owner Project manager

Phase 4: Deployment

# Action Description Owner
1a DNS (Cloudflare-fronted) Point the env's live + preview hostnames at Cloudflare; DNS Proxied (orange-cloud), SSL/TLS Full (strict). The routing worker handles origin mapping DevOps
1b DNS (non-CF) No custom DNS needed — use the EDS publish URL <branch>--{eds_site}--aa-pdcoe.aem.live directly DevOps
2 Publish content Publish all pages from AEM author via Sidekick Content author
3 Live verification Verify live site at the production URL (or publish URL) QA / Developer
4 Monitoring setup Confirm RUM analytics and custom data layer are reporting DevOps

Phase 5: Post-Deployment

# Action Description Owner
1 Smoke test End-to-end verification of critical user flows QA
2 Performance baseline Record baseline Lighthouse and Core Web Vitals scores Developer
3 Documentation Update site registry and operational documentation Developer
4 Knowledge transfer Brief the support team on site-specific configuration Developer
5 Handoff Transfer operational ownership to the site team Project manager

Rollback Plan

# Action Description Owner
1 Identify issue Determine whether the issue is content, code, or infrastructure Developer
2 Content rollback Unpublish affected pages via Sidekick; previous published version is restored Content author
3 Code rollback Revert the problematic commit on main and push Developer
4 Verify rollback Confirm the site is restored to the previous working state QA
EDS content rollback is near-instant. Unpublishing a page via Sidekick immediately reverts the live CDN to the previously published version. Code rollbacks take effect as soon as the revert commit is pushed to main.

Developer Onboarding

Prerequisites

Requirement Version Purpose
Node.js 22.x Runtime for build scripts and AEM CLI
npm Bundled with Node.js Package management
Git Latest Version control
AEM Sidekick Latest Chrome extension Content preview and publish
GitHub access abbvie-migrated org membership Repository access
AEM Author access Provisioned account Content authoring (if applicable)

Setup Steps

# Action Command / Location
1 Clone repository git clone git@github.com:abbvie-migrated/rhea.git
2 Install dependencies npm install
3 Start dev server npm start
4 Install Sidekick Chrome Web Store: AEM Sidekick
5 Configure Sidekick Add project URL in Sidekick settings
6 Verify preview Open http://localhost:3000 and confirm blocks render

Key Documentation to Read

Document Priority Description
EDS Architecture Overview Required Understand the solution stack, repoless model, and environments
Implementation Patterns Required Block and rendering patterns for the RHEA version you are working on
Development Required Block dev, scripts, theming, testing (in the RHEA repo)
DevOps Overview Required Branching model and CI/CD
Authoring Guide Reference Block catalog and authoring (Confluence)

Offboarding Checklist (Site Decommission)

  • Notify all stakeholders of decommission timeline
  • Redirect existing URLs to replacement destination
  • Remove DNS CNAME records + Cloudflare worker routes (Cloudflare-fronted only)
  • Unpublish all pages in AEM Author
  • Remove the family's sites/<family>/ config from eds-site-config (via PR); the deploy kill-switch can pause deploys during teardown
  • Remove AEM author content folder
  • Remove Sidekick configurations
  • Revoke the <FAMILY>_<ENV>_CLOUDFLARE_API_TOKEN secrets (Cloudflare-fronted only)
  • Update site registry documentation
  • Remove analytics/monitoring dashboards
  • Document decommission in architecture decision log
  • Final confirmation that site is no longer accessible
On this page
h3
true