docs: add self-hosting documentation - #8605
Conversation
github-actions
Bot
added
the
redirects-needed
|
@adrianjoshua-strutt, since a file was deleted from the
|
|
Redirects are already configured in
All pages moved from |
3f94a6d to
48e921c
Compare
Adds documentation for the self-managed hosting feature (defineHosting, definePipeline, ampx deploy), restructures the deploy-and-host section into Amplify Hosting and Self-managed hosting, and adds preview labeling. RFC: aws-amplify/amplify-backend#3211
48e921c to
2a437c2
Compare
Corrections to match the shipped @aws-amplify/hosting 1.0.0 API:
- compute: remove nonexistent 'runtime' option
- cdn: replace nonexistent cachePolicy{defaultTtl,maxTtl} with ssrDefaultTtl (Duration); fix geoRestriction to { type, countries }
- storage: encryption 'S3' -> 'S3_MANAGED'
- pipeline: bakeTime is a Duration (was a number); computeType is ComputeType enum (was a string); fix getStageConfig() usage (undefined guard + .config nesting)
- pipeline: synth step synthesizes (cdk synth) instead of the invalid 'ampx deploy --frontend --backend' combo; 'ampx deploy --pipeline' cannot take --identifier
- frameworks: customAdapter is a FrameworkAdapterFn (function), not an object; add SvelteKit
- external pipelines: add --yes to all CI deploy commands (the command prompts otherwise) and document the flag
Content:
- add Secrets and environment variables page and wire nav + cross-links
- document default-on monitoring and skewProtection options
Release framing:
- remove preview banners and 'not for production' language; drop stale 'install the preview via RFC' instruction (ships as 1.0.0 on npm)
- cspell: add 'maxage', 'prerendered'
bobbor
left a comment
bobbor
left a comment
There was a problem hiding this comment.
left some small comments that require clarification
| name: 'production', | ||
| requireApproval: true, | ||
| bakeTime: 30, | ||
| bakeTime: Duration.minutes(30), |
There was a problem hiding this comment.
keep this a number pls.
similar to all other configurations where CDK durations are alternatives.
There was a problem hiding this comment.
I looked into this before changing it and I don't think a number compiles today. In the published @aws-blocks/pipeline@0.2.1 (what @aws-amplify/hosting@1.0.0 depends on), PipelineStageConfig.bakeTime is typed as cdk.Duration only — not Duration | number:
readonly bakeTime?: cdk.Duration;and the upstream package's own JSDoc example uses bakeTime: Duration.minutes(30). The Duration | number convention does apply elsewhere (e.g. compute.timeout), just not to bakeTime yet — so bakeTime: 30 would be a type error for consumers on the released version.
Happy to switch it to a number if you'd prefer the docs to lead the API — but that'd need bakeTime to accept number in a released @aws-blocks/pipeline. Is that shipped/planned? If you point me at the version I'll update the example (and we can note the minimum version).
| const customAdapter: FrameworkAdapterFn = async (projectDir) => { | ||
| // Build your project, then return a DeployManifest that points the | ||
| // hosting construct at the built static assets and server handler. | ||
| return buildMyFrameworkManifest(projectDir); |
There was a problem hiding this comment.
by removing the example (serverEntry, buildCommand etc.) it is no longer clear what the custom adapter should do.
Also, is an (async) adapter function the only way to provide a custom adapter?
There was a problem hiding this comment.
Good call — restored a concrete example (808d7a9). To answer the question directly: an adapter function is the only way to provide a custom adapter, and it's a single form — a synchronous FrameworkAdapterFn, i.e. (projectDir: string) => DeployManifest (from @aws-blocks/hosting; there's no object form, and it isn't async). The example now returns a concrete static-only DeployManifest (staticAssets + empty compute/routes) so it's clear what the adapter must produce, with a note that SSR frameworks populate compute and routes.
…Fn with a concrete DeployManifest example Addresses review: the previous change removed the example without showing what the adapter must return. A custom adapter is the only way to add an unsupported framework and takes a single form — a synchronous (projectDir) => DeployManifest. Show a concrete static-only manifest (staticAssets/compute/routes) and note SSR uses compute + routes.
Framework is auto-detected, and the supported-framework list plus the override are already documented on the Supported frameworks and Configure hosting pages. Replace the inline list with links (addresses review feedback).
| **Static / React SPA / Vite / CRA** — Fallback when no server framework is detected. Your app is built as static files and served directly from Amazon S3 through Amazon CloudFront with no server compute required. | ||
|
|
||
| **Custom frameworks** — If your framework is not auto-detected, pass a `customAdapter` function to `defineHosting()`. An adapter is a `FrameworkAdapterFn`: it receives the project directory, runs your build, and returns a `DeployManifest` describing the static assets and server handler to deploy. | ||
| **Custom frameworks** — If your framework is not auto-detected, provide a `customAdapter`. This is the only way to add an unsupported framework, and it takes a single form: a synchronous `FrameworkAdapterFn` — `(projectDir: string) => DeployManifest`. The function inspects/builds the project at `projectDir` and returns a `DeployManifest` that tells the hosting construct where the built static assets live, which compute functions to create for SSR, and how to route requests. |
There was a problem hiding this comment.
Added a definition (bbf725f). A DeployManifest is the framework-agnostic contract between an adapter and the hosting construct — a plain JSON object describing what to deploy, so the construct needs no framework-specific knowledge. Top-level fields: version, staticAssets ({ directory, immutablePaths?, noCachePaths?, spaFallback? }), compute (named SSR functions; empty for static), routes (path → compute/static), plus optional cache (ISR), imageOptimization, middleware, and redirects/rewrites/headers. Every built-in adapter produces one; the full schema is in @aws-amplify/hosting's DeployManifest type.
Addresses review question 'What is a DeployManifest?' — add a short explanation (framework-agnostic adapter↔construct contract) and its top-level fields before the example.
|
|
||
| A **`DeployManifest`** is the framework-agnostic contract between an adapter and the hosting construct: a plain JSON object describing what to deploy, so the construct never needs framework-specific knowledge. Every built-in adapter produces one. Its top-level fields: | ||
|
|
||
| - `version` — manifest schema version (currently `1`). |
There was a problem hiding this comment.
The DeployManifest is described as "a plain JSON object".
But a "schema version" implies a schema. Do we have one?
So which one is it?
compare to amplify_outputs.json schema
There was a problem hiding this comment.
Good catch — that wording was contradictory. It's a TypeScript type, not a JSON-Schema-backed document, so I've fixed the text (036d53f).
To answer directly: there is no separate published JSON Schema for DeployManifest (nothing equivalent to the amplify_outputs.json schema you linked). It's a TS type exported from @aws-amplify/hosting, and the adapter returns it in-process at synth time — you never author or validate a .json file. The type itself is the contract, enforced by TypeScript.
The version: 1 field is a literal format-version marker so the manifest shape can evolve compatibly across releases; it isn't a reference to an external schema. So: it's a JSON-serializable object described by a TypeScript type — not a schema-file-validated document.
…chema doc Addresses review: 'plain JSON object' + 'schema version' was contradictory. Clarify it's a TypeScript type (the type is the schema), returned in-process by the adapter; no separate published JSON Schema, and version is a format-evolution marker.
|
Tick the box to add this pull request to the merge queue (same as
|
* docs(self-hosting): restore preview banner Put back the preview callout and the '(Preview)' section title that were removed during review of #8605. ampx deploy still ships as a preview release, so the docs should say so. Also adds the banner to the secrets and environment variables page, which was added after the banner was removed. * docs(self-hosting): point preview banner at GitHub issues instead of the closed RFC * docs(self-hosting): address review — shared PreviewBanner, info style, reconcile --yes - Replace the seven inline banner copies with a shared <PreviewBanner /> component registered in mdx-components (like Callout), so it can't drift and removal at GA is a single change. Drops the unused PREVIEW-BANNER marker comments. - Use an info callout (matching the AWS Blocks preview notice) so warning styling stays reserved for actionable notes like the CDK bootstrap prerequisite. - Drop '(Preview)' from the section title; the banner carries the status. - External pipelines: describe what the ampx deploy prompt actually says, note that --yes accepts it without changing preview status, and rename example identifiers from 'production' to 'my-app' (also in getting started).
3 participants
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 CINavigation
Updated
src/directory/directory.mjsto add the self-hosting section under deploy-and-host.Related: aws-amplify/amplify-backend#3211