docs: add self-hosting documentation by adrianjoshua-strutt · Pull Request #8605 · aws-amplify/docs

adrianjoshua-strutt · 2026-06-02T13:18:49Z

Preview: https://d2a8cehsb9j05d.cloudfront.net

Adds documentation for the self-managed hosting feature (defineHosting, definePipeline, ampx deploy).

Pages added

/deploy-and-host/self-hosting/ — Overview
/deploy-and-host/self-hosting/getting-started/ — Install and first deploy
/deploy-and-host/self-hosting/define-hosting/ — Configure hosting (domains, WAF, compute, CDK escape hatches)
/deploy-and-host/self-hosting/define-pipeline/ — Set up CI/CD pipeline
/deploy-and-host/self-hosting/external-pipelines/ — GitHub Actions, GitLab CI

Navigation

Updated src/directory/directory.mjs to add the self-hosting section under deploy-and-host.

Related: aws-amplify/amplify-backend#3211

…line

… Amplify Hosting - Rewrite deploy-and-host/index.mdx with two-path layout (managed vs self-managed) - Add self-hosting card to how-amplify-works overview - Update homepage and platform landing Deploy sections with self-hosting item - Add self-hosting alternative section to hosting stub page - Add self-hosting mention to gen2 migration feature-matrix - Update FeatureLists test to match updated link text

…hing into amplify-hosting - Rename hosting/ to amplify-hosting/ (rewrite stub as full overview page) - Move all fullstack-branching child pages under amplify-hosting/ - Remove fullstack-branching/ section entirely - Update deploy-and-host/index.mdx (remove "Shared development tools", add sandbox note) - Fix all internal links referencing old paths - Keep self-hosting/ and sandbox-environments/ as sibling sections

mergify · 2026-06-02T14:02:44Z

@adrianjoshua-strutt, since a file was deleted from the src/pages and/or src/fragments directories, redirects might need to be set up so these previous pages do not 404. If redirects are needed, please answer these questions for each redirect that is needed:

What is the source address of the redirect? (Where are you trying to redirect from?)
What is the target address of the redirect? (Where are you trying to redirect to?)
Type of redirect? 301 - permanent redirect or 302 - temporary redirect? (More info on Amplify Hosting redirects here: https://docs.aws.amazon.com/amplify/latest/userguide/redirects.html)

…ss all deploy pages - Landing pages: Change "Deploy your app" button from external Amplify console link to internal /deploy-and-host/ overview with both hosting options - NextPrevious component: Fix stale /deploy-and-host/fullstack-branching/ path to /deploy-and-host/amplify-hosting/ - Concepts page: Update "Fullstack Git-based environments" section to mention self-managed hosting; fix em-dashes and banned words (leverage, simply) - Quickstarts (React, Vue, Angular, Next.js pages/app router, Android): Add callout noting self-hosting alternative; update "Publishing changes to cloud" sections to reference both deployment paths - Manual installation: Link to /deploy-and-host/ overview instead of only amplify-hosting - MCP workflows: Add self-managed hosting to CI/CD and deployment sections - deploy-and-host fragment: Rewrite to present both Amplify Hosting and self-managed hosting as equal options - README: Update outdated directory tree to reflect current structure

Split the Deploy section on both the platform-specific and root landing pages into a two-column layout: Left column (Amplify Hosting): - Description of managed Git CI/CD hosting - deploy-cycle.png diagram - Sub-features: sandboxes, fullstack branches, GUI - Link to /deploy-and-host/amplify-hosting/ Right column (Self-managed hosting): - Description of CDK-based self-hosting - Code example showing defineHosting usage - Sub-features: CDK escape hatches, custom CI/CD, domains + WAF - Link to /deploy-and-host/self-hosting/ The Customize section remains unchanged below the Deploy section.

…x CI - Add 301 redirects for hosting/ → amplify-hosting/ path moves - Add 301 redirects for fullstack-branching/ → amplify-hosting/ path moves - Update existing gen1/gen2 redirects to target amplify-hosting/ - Fix generate-sitemap test to reference new amplify-hosting paths - Add codeconnections and xlarge to cspell dictionary

…sting - Create deploy-cycle.svg showing Amplify Hosting flow - Create deploy-cycle-self-hosted.svg showing self-managed flow - Replace PNG image reference with SVG in both index pages - Replace code examples in right column with self-hosting SVG - Remove unused ExportedImage imports

- Fix incorrect flow showing sandbox→git→deploy (wrong) - Correct diagram shows two parallel concepts: 1. Developer sandboxes ↔ cloud (bidirectional, for local dev) 2. Git branches → Amplify Console (for production deploy) - Match original PNG color scheme (#193549 background, #9469d6 purple) - Use two separate cloud icons above each sandbox with bidirectional arrows - Add visual separator between development and deployment sections - Update self-hosted variant with same corrected layout

Redesigned both deploy-cycle diagrams to clearly communicate the three-phase deployment story: 1. DEVELOP - Per-developer cloud sandboxes with localhost, showing ampx sandbox bidirectional sync 2. GIT REPOSITORY - Branches (dev, main, feature) as pills 3. DEPLOY - Per-branch environments with unique URLs Key improvements: - Added localhost:3000 to show sandboxes are for local development - Added per-branch URLs (dev.example.com, app.example.com, etc.) - Removed ugly unfilled cloud emoji paths - Replaced with clean rectangular section containers - Added proper arrow labels (git push, auto-deploy) - Increased viewBox to 600x500 for better spacing and readability - Used proper gradient fills and consistent color palette - Self-hosted variant shows CloudFormation stacks with CloudFront URLs

- Increase SVG font sizes (20px section headers, 16-18px body text) - Reduce viewBox from 600×520 to 520×480 so content fills the space - Fix arrows to connect directly to section box edges (no floating gaps) - Center branch pills and section labels horizontally - Lengthen self-managed hosting feature descriptions to match left column

- Use "beta" and "main" as branch names in both SVGs - Self-hosted: show URLs (beta.example.com, app.example.com) instead of CloudFormation stack names - Self-hosted: remove CloudFormation branding - Self-hosted: simplify arrow label to just "deploy"

…, shorten landing page text

adrianjoshua-strutt · 2026-06-03T11:14:43Z

Redirects are already configured in redirects.json in this PR. All are 301 permanent redirects:

Source	Target	Type
`/<platform>/deploy-and-host/hosting/`	`/<platform>/deploy-and-host/amplify-hosting/`	301
`/<platform>/deploy-and-host/hosting/<*>`	`/<platform>/deploy-and-host/amplify-hosting/<*>`	301
`/<platform>/deploy-and-host/fullstack-branching/`	`/<platform>/deploy-and-host/amplify-hosting/`	301
`/<platform>/deploy-and-host/fullstack-branching/branch-deployments/`	`/<platform>/deploy-and-host/amplify-hosting/branch-deployments/`	301
`/<platform>/deploy-and-host/fullstack-branching/pr-previews/`	`/<platform>/deploy-and-host/amplify-hosting/pr-previews/`	301
`/<platform>/deploy-and-host/fullstack-branching/secrets-and-vars/`	`/<platform>/deploy-and-host/amplify-hosting/secrets-and-vars/`	301
`/<platform>/deploy-and-host/fullstack-branching/share-resources/`	`/<platform>/deploy-and-host/amplify-hosting/share-resources/`	301
`/<platform>/deploy-and-host/fullstack-branching/custom-pipelines/`	`/<platform>/deploy-and-host/amplify-hosting/custom-pipelines/`	301
`/<platform>/deploy-and-host/fullstack-branching/cross-account-deployments/`	`/<platform>/deploy-and-host/amplify-hosting/cross-account-deployments/`	301
`/<platform>/deploy-and-host/fullstack-branching/mono-and-multi-repos/`	`/<platform>/deploy-and-host/amplify-hosting/mono-and-multi-repos/`	301
`/<platform>/deploy-and-host/fullstack-branching/monorepos/`	`/<platform>/deploy-and-host/amplify-hosting/monorepos/`	301

All pages moved from hosting/ and fullstack-branching/ into amplify-hosting/ as part of a nav restructure. The ValidateRedirects CI check passes locally.

osama-rizk · 2026-06-03T12:27:33Z

+import { defineHosting } from '@aws-amplify/hosting';
+
+export const hosting = defineHosting({
+  framework: 'nextjs'


Since we are auto detecting the framework, can omit this framework param and also it is already mentioned in configuration page.

Will do. Thanks!

osama-rizk · 2026-06-03T12:28:14Z

+import { defineHosting } from '@aws-amplify/hosting';
+
+export const hosting = defineHosting({
+  framework: 'nextjs'


same here, Since we are auto detecting the framework, can omit this framework param and also it is already mentioned in configuration page.

- Fix AWS service name references to use full official names on first mention: - CloudFront → Amazon CloudFront (first mention), CloudFront (subsequent) - S3 → Amazon S3 - Lambda → AWS Lambda - Route 53 → Amazon Route 53 - CodePipeline → AWS CodePipeline - CodeBuild → AWS CodeBuild - CloudFormation → AWS CloudFormation - WAF → AWS WAF - CDK → AWS CDK - DynamoDB → Amazon DynamoDB - SQS → Amazon SQS - In tables, headings, and meta descriptions: always use full name - In code blocks: leave as-is - Lambda@Edge stays as-is (official name) - AWS CDK escape hatches: use full name on first mention Files updated: - define-hosting/index.mdx - define-pipeline/index.mdx - self-hosting/index.mdx - external-pipelines/index.mdx - frameworks/index.mdx - getting-started/index.mdx - deploy-and-host/index.mdx - [platform]/index.tsx - index.tsx

- Rename 'SPA' column to 'Static / SPA' in feature matrix - Rename 'Nuxt' to 'Nuxt / Nitro' in framework list and feature matrix - Update Nuxt detection to mention 'nuxt' or 'nitropack' in dependencies - Update SPA description to include 'Static' prefix and use full product names (Amazon S3, Amazon CloudFront) - Maintain table alignment

…-detected)

…d pipeline Add build output directory override, storage configuration, and content security policy sections to define-hosting page. Add self-mutation toggle, cross-account deployments, disable auto-trigger, and custom synth install commands sections to define-pipeline page.

docs: add self-hosting documentation for defineHosting and definePipe…

4f3699e

…line

adrianjoshua-strutt requested a review from a team as a code owner June 2, 2026 13:18

adrianjoshua-strutt requested a review from a team as a code owner June 2, 2026 13:35

github-actions Bot added the redirects-needed Redirects need to be created for deleted pages label Jun 2, 2026

adrianjoshua-strutt added 15 commits June 2, 2026 15:06

feat(landing): add definePipeline code example to Deploy section

bf644f7

fix: use same arrow label on both deploy diagrams

69eb320

docs(self-hosting): add supported frameworks page with feature matrix

2a7a64b

fix: update SVG backgrounds to neutral gray, add 'auto deploy' labels…

6e8b298

…, shorten landing page text

fix: Amplify Hosting SVG should not say 'stack'

3a3de03

chore: upgrade yarn to 4.16.0 and update lockfile metadata to version 10

06bddfe

fix: Amplify Hosting SVG says environment not URL

9a852eb

osama-rizk reviewed Jun 3, 2026

View reviewed changes

osama-rizk requested changes Jun 3, 2026

View reviewed changes

adrianjoshua-strutt added 5 commits June 3, 2026 14:25

fix: remove framework param from minimal defineHosting examples (auto…

8104c9c

…-detected)

fix: add nitropack to spellcheck dictionary

d3f9b21

adrianjoshua-strutt added 2 commits June 3, 2026 19:01

fix: shorten AWS CDK escape hatches description (2 lines instead of 3)

5cef754

fix: CDK escape hatches description - avoid service name clutter

663a61a

osama-rizk approved these changes Jun 4, 2026

View reviewed changes

adrianjoshua-strutt marked this pull request as draft June 4, 2026 10:07

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

docs: add self-hosting documentation#8605

docs: add self-hosting documentation#8605
adrianjoshua-strutt wants to merge 25 commits into
mainfrom
docs/self-hosting

adrianjoshua-strutt commented Jun 2, 2026 •

edited

Loading

Uh oh!

mergify Bot commented Jun 2, 2026

Uh oh!

adrianjoshua-strutt commented Jun 3, 2026

Uh oh!

osama-rizk Jun 3, 2026

Uh oh!

adrianjoshua-strutt Jun 3, 2026

Uh oh!

osama-rizk Jun 3, 2026

Uh oh!

adrianjoshua-strutt Jun 3, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

Uh oh!

Conversation

adrianjoshua-strutt commented Jun 2, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Pages added

Navigation

Uh oh!

mergify Bot commented Jun 2, 2026

Uh oh!

adrianjoshua-strutt commented Jun 3, 2026

Uh oh!

osama-rizk Jun 3, 2026

Choose a reason for hiding this comment

Uh oh!

adrianjoshua-strutt Jun 3, 2026

Choose a reason for hiding this comment

Uh oh!

osama-rizk Jun 3, 2026

Choose a reason for hiding this comment

Uh oh!

adrianjoshua-strutt Jun 3, 2026

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

adrianjoshua-strutt commented Jun 2, 2026 •

edited

Loading