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
Related Documents
- EDS Architecture Overview — Architecture context
- Content Authoring Model — Content authoring workflow
- DevOps Overview — Branching model and CI/CD
On this page
h3
true