Skip to content

Reshuffle deployment docs: new pages, sidebar restructure, messaging updates#644

Merged
IEvangelist merged 23 commits intomainfrom
davidfowl/deployment-fixes
Mar 31, 2026
Merged

Reshuffle deployment docs: new pages, sidebar restructure, messaging updates#644
IEvangelist merged 23 commits intomainfrom
davidfowl/deployment-fixes

Conversation

@davidfowl
Copy link
Copy Markdown
Contributor

@davidfowl davidfowl commented Mar 30, 2026

Deployment docs reshuffle

Major restructure of the deployment documentation section to improve organization, fill gaps, and align messaging.

New pages created

  • Deploy to Docker Compose (deployment/docker-compose) — deployment workflow pulled from integration page
  • Deploy to Kubernetes (deployment/kubernetes) — deployment workflow with troubleshooting
  • Azure Developer CLI (azd) (deployment/azure/azure-developer-cli) — azd as legacy/alternative path
  • Customize Azure Container Apps (deployment/azure/customize-container-apps) — ACA customization APIs

Pages moved

  • Pipelines (get-started/pipelines → deployment/pipelines) + Japanese translation
  • Deployment manifest format (deployment/manifest-format → deployment/azure/manifest-format) + deprecation notice
  • App lifecycle guide (fundamentals/app-lifecycle → deployment/app-lifecycle) — CI/CD content

Key messaging changes

  • aspire deploy is now the primary Azure deployment path; azd is legacy/alternative
  • Deployment manifest format marked as deprecated
  • Removed stale "preview" labels (aspire deploy and Docker are GA)
  • Removed manifest references from general-purpose docs

Sidebar restructure

Deployment
├── Overview
├── Pipelines (aspire do)
├── Deploy to Docker Compose
├── Deploy to Kubernetes [Preview]
├── Deploy to Azure
│   ├── Deploy using the Aspire CLI
│   ├── Customize Azure Container Apps
│   ├── Azure security best practices
│   └── Azure Developer CLI (azd) [collapsed]
│       ├── Overview
│       └── Deployment manifest format [Deprecated]
├── Deploy JavaScript apps
├── App lifecycle (CI/CD)
└── Advanced [collapsed]
    ├── Deployment state caching
    └── Custom deployment pipelines

Other fixes

  • All new pages have C#/TypeScript AppHost tabs (compiler-verified)
  • Fixed WellKnownSteps → WellKnownPipelineSteps in pipelines prose
  • Added missing using/#pragma directives to code examples
  • Updated Docker package version from preview to 13.2.0
  • Updated stale aspire-8.0.json schema reference
  • Cleaned .NET-centric language from app lifecycle guide
  • Updated 27+ cross-references and all localized links
  • Added redirects for all moved pages

Issues addressed

Related issues filed

Copilot AI review requested due to automatic review settings March 30, 2026 22:14
Copilot AI reviewed Mar 30, 2026
View reviewed changes
Copy link
Copy Markdown
Contributor

Copilot AI left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Pull request overview

Restructures the deployment documentation to improve discoverability and align guidance around modern deployment flows (aspire publish / aspire deploy), while moving legacy azd + manifest-format content into an explicitly “legacy/alternative” path and updating cross-links and sidebars accordingly.

Changes:

  • Reorganized the Deployment section (new pages for Docker Compose, Kubernetes, and Azure customization; moved pipelines/app lifecycle/manifest docs; updated sidebars + redirects).
  • Updated many existing docs to remove/relocate legacy manifest references and refresh messaging (GA vs preview wording, updated links, updated package versions).
  • Added/updated localized links (including a new Japanese deployment/pipelines page) to match the new structure.

Reviewed changes

Copilot reviewed 47 out of 49 changed files in this pull request and generated 1 comment.

Show a summary per file
File Description
.gitignore Ignores tmp-ts-validation/ and fixes indentation.
src/frontend/config/redirects.mjs Adds redirects for moved docs (pipelines, manifest format, app lifecycle).
src/frontend/config/sidebar/deployment.topics.ts Rebuilds Deployment sidebar IA; adds new pages and collapses legacy azd content.
src/frontend/config/sidebar/docs.topics.ts Removes “pipelines” and “app lifecycle” entries from Get Started section.
src/frontend/src/content/docs/index.mdx Updates homepage link to the new pipelines location.
src/frontend/src/content/docs/docs.mdx Updates docs landing page card link to new pipelines location.
src/frontend/src/content/docs/app-host/container-registry.mdx Updates cross-link to pipelines page.
src/frontend/src/content/docs/da/index.mdx Updates pipelines link for Danish locale.
src/frontend/src/content/docs/de/index.mdx Updates pipelines link for German locale.
src/frontend/src/content/docs/es/index.mdx Updates pipelines link for Spanish locale.
src/frontend/src/content/docs/fr/index.mdx Updates pipelines link for French locale.
src/frontend/src/content/docs/hi/index.mdx Updates pipelines link for Hindi locale.
src/frontend/src/content/docs/id/index.mdx Updates pipelines link for Indonesian locale.
src/frontend/src/content/docs/it/index.mdx Updates pipelines link for Italian locale.
src/frontend/src/content/docs/ko/index.mdx Updates pipelines link for Korean locale.
src/frontend/src/content/docs/pt-br/index.mdx Updates pipelines link for Portuguese (Brazil) locale.
src/frontend/src/content/docs/ru/index.mdx Updates pipelines link for Russian locale.
src/frontend/src/content/docs/tr/index.mdx Updates pipelines link for Turkish locale.
src/frontend/src/content/docs/uk/index.mdx Updates pipelines link for Ukrainian locale.
src/frontend/src/content/docs/zh-cn/index.mdx Updates pipelines link for Simplified Chinese locale.
src/frontend/src/content/docs/get-started/what-is-aspire.mdx Updates “Learn more” link to new pipelines location.
src/frontend/src/content/docs/get-started/glossary.mdx Updates terminology and publish-mode examples (artifacts vs manifests; Helm charts).
src/frontend/src/content/docs/get-started/deploy-first-app.mdx Updates Docker package version and cross-links to pipelines.
src/frontend/src/content/docs/get-started/deploy-first-app-csharp.mdx Updates Docker package version and cross-links to pipelines.
src/frontend/src/content/docs/get-started/deploy-first-app-typescript.mdx Updates cross-links to pipelines.
src/frontend/src/content/docs/fundamentals/external-parameters.mdx Removes manifest-specific parameter representation section and updates wording.
src/frontend/src/content/docs/whats-new/aspire-9-2.mdx Updates manifest-format link to its new Azure location.
src/frontend/src/content/docs/whats-new/aspire-13.mdx Updates pipelines link to new Deployment section location.
src/frontend/src/content/docs/ja/whats-new/aspire-13.mdx Updates pipelines link to new Japanese Deployment section location.
src/frontend/src/content/docs/ja/index.mdx Updates pipelines link for Japanese locale.
src/frontend/src/content/docs/ja/docs.mdx Updates docs landing link for Japanese locale.
src/frontend/src/content/docs/ja/get-started/what-is-aspire.mdx Updates pipelines link for Japanese locale.
src/frontend/src/content/docs/ja/get-started/deploy-first-app.mdx Updates pipelines link for Japanese locale.
src/frontend/src/content/docs/ja/deployment/pipelines.mdx Adds a new Japanese “Pipelines and app topology” page under Deployment.
src/frontend/src/content/docs/reference/cli/commands/aspire-do.mdx Updates “Learn more” link to new pipelines location.
src/frontend/src/content/docs/integrations/custom-integrations/hosting-integrations.mdx Updates section framing and removes stale schema reference from example.
src/frontend/src/content/docs/integrations/compute/kubernetes.mdx Replaces embedded publish/deploy guide with pointer to new Kubernetes deployment page.
src/frontend/src/content/docs/integrations/compute/docker.mdx Replaces embedded Compose workflow with pointer to new Docker Compose deployment page.
src/frontend/src/content/docs/integrations/cloud/azure/overview.mdx Removes manifest-focused snippet in favor of Bicep-output-oriented explanation.
src/frontend/src/content/docs/deployment/index.mdx Updates showcase links and removes manifest-format feature spotlight.
src/frontend/src/content/docs/deployment/overview.mdx Updates messaging (GA vs preview), removes legacy manifest section, and refreshes azd guidance.
src/frontend/src/content/docs/deployment/pipelines.mdx Updates pipeline docs (naming, TS notes, examples, and well-known step identifiers).
src/frontend/src/content/docs/deployment/docker-compose.mdx Adds new end-to-end Docker Compose deployment workflow page.
src/frontend/src/content/docs/deployment/kubernetes.mdx Adds new Kubernetes publish + Helm deployment guide with troubleshooting.
src/frontend/src/content/docs/deployment/custom-deployments.mdx Adjusts warning/aside messaging around advanced pipeline APIs.
src/frontend/src/content/docs/deployment/app-lifecycle.mdx Moves/updates app lifecycle guide with more language-neutral phrasing and CI/CD framing.
src/frontend/src/content/docs/deployment/azure/azure-developer-cli.mdx Adds new azd “legacy/alternative path” page and comparison table.
src/frontend/src/content/docs/deployment/azure/manifest-format.mdx Adds deprecation notice and updates manifest-format messaging.
src/frontend/src/content/docs/deployment/azure/customize-container-apps.mdx Adds new Azure Container Apps customization page (domains, existing resources, RG/RBAC, discovery).
Comments suppressed due to low confidence (1)

src/frontend/src/content/docs/deployment/azure/manifest-format.mdx:18

  • The new deprecation aside recommends using aspire publish and aspire deploy with “compute environment integrations” including Kubernetes. Elsewhere in this PR, Kubernetes deployment is described as aspire publish to generate Helm charts, followed by Helm/kubectl (not aspire deploy). Consider rewording this to avoid implying that aspire deploy directly deploys to Kubernetes, or add a clarification that Kubernetes requires applying the published Helm artifacts with Helm.

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

davidfowl and others added 14 commits March 30, 2026 15:33
@davidfowl
Reshuffle deployment docs structure
a3d8e5c 
- Move pipelines doc from get-started to deployment section
- Move manifest-format under deployment/azure with deprecation notice
- Create new Deploy to Docker Compose page
- Create new Deploy to Kubernetes page
- Create new Azure Developer CLI (azd) page (legacy/alternative path)
- Create new Customize Azure Container Apps page
- Remove stale preview labels (aspire deploy and Docker are GA)
- Update Docker package version from preview to 13.1.0
- Remove manifest references from general-purpose docs
- Position aspire deploy as primary Azure deployment path
- Trim integration pages (Docker, K8s) to link to deployment pages
- Update sidebar, redirects, and cross-references
- Update stale aspire-8.0.json schema reference

Addresses: #354, #331, #335, #358, #359

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
@davidfowl
Move Japanese pipelines translation to match new slug
f3f15c1 
Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
@davidfowl
Fix localized pipeline links to new deployment path
64f50e0 
Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
@davidfowl
Fix duplicate K8s sidebar entry and remove pipelines from docs.topics.ts
cb9c5c8 
- Remove duplicate 'Deploy to Kubernetes' sidebar entry
- Remove pipelines from get-started sidebar (already in deployment sidebar)

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
@davidfowl
Add TypeScript AppHost tabs to all deployment pages
4b1f4f5 
- Add C#/TypeScript tabs to 14 AppHost code blocks across 4 pages
- Add 'not yet available' notes for 3 APIs without TS support:
  ConfigureEnvFile, WithImagePushOptions, ConfigureCustomDomain
- Fix Docker package version to 13.2.0
- Add Preview badge to Kubernetes deployment page
- Remove manifest schema ref from hosting-integrations

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
@davidfowl
Fix TypeScript API examples to match actual compiler-verified signatures
9395502 
- addProject needs 3 args (name, path, launchProfile)
- addContainer uses single image:tag string
- Callbacks must be async (publishAsDockerComposeService, etc.)
- Properties use .set() pattern (service.name.set, k8s.helmChartName.set)
- ImagePullPolicy uses enum import, not string literal
- addContainerRegistryFromString for string args
- publishAsExisting takes strings, not ParameterResource
- withResourceGroup removed from TS (takes ParameterResource)
- publishAsAzureContainerApp callback simplified (ContainerAppHandle)

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
@davidfowl
Reorder deployment sidebar: group targets, add Advanced section
1f58ba9 
- Move deploy targets (Docker, K8s, Azure) right after Pipelines
- Move azd to bottom of Azure section (legacy)
- Move Deploy JavaScript apps below targets
- Group state caching + custom pipelines under collapsed Advanced

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
@davidfowl
Fix 3 critical issues found by doc-tester
b63218e 
- K8s: Remove invalid resource.Deployment reference (use comment placeholder)
- ACA: Fix PublishAsExisting to require 2 params (name + resourceGroup)
- ACA: Fix WithResourceGroup — it's on AzureEnvironmentResource, not individual resources

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
@davidfowl
Add TypeScript tab to pipelines page with 'not yet available' note
9a5af57 
Follow existing pattern: show TS tab with :::note when API isn't in TS SDK.

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
@davidfowl
Use tab pattern for unavailable TS APIs instead of standalone Aside
b9ad0bc 
Convert ConfigureEnvFile, WithImagePushOptions, and ConfigureCustomDomain
to show a TypeScript tab with :::note inside, matching the established
pattern used in container-files.mdx and other docs.

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
@davidfowl
Move app lifecycle guide to deployment section
1bb4718 
- Move fundamentals/app-lifecycle.mdx to deployment/app-lifecycle.mdx
- Add to deployment sidebar as 'App lifecycle (CI/CD)'
- Update slug in docs.topics.ts
- Add redirect from old path

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
@davidfowl
Clean .NET-centric language from app lifecycle guide
c9f2388 
- Frame example as C# with note that TS AppHosts follow same pattern
- Replace AppHost.cs references with generic 'AppHost'
- Change '.NET process' to 'local process'
- Add tip about TypeScript AppHost equivalence
- Note --project flag purpose in CI/CD example

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
@davidfowl
Fix doc-tester final round issues
f5b7355 
- Remove app-lifecycle from docs.topics.ts (fixes wrong prev/next nav)
- Fix WellKnownSteps → WellKnownPipelineSteps (8 occurrences in prose)
- Add missing using/pragma to pipelines code example
- Add missing 'using Aspire.Hosting.Docker' to ConfigureEnvFile example
- Add missing ASPIRECOMPUTE003 pragma to AddContainerRegistry example
- Add missing ASPIREACADOMAINS001 pragma to ConfigureCustomDomain example

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
@davidfowl
Fix K8s deploy column: no aspire deploy support for Kubernetes
f8c8b56 
Kubernetes uses aspire publish + Helm/kubectl, not aspire deploy.
Addresses review feedback.

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
@davidfowl davidfowl force-pushed the davidfowl/deployment-fixes branch from bbcd42a to f8c8b56 Compare March 30, 2026 22:34
JamesNK
JamesNK reviewed Mar 30, 2026
View reviewed changes
Copy link
Copy Markdown
Member

@JamesNK JamesNK left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

A few issues found — one will cause a 404 (missing JA redirect), plus a couple of consistency nits.

src/frontend/src/content/docs/deployment/docker-compose.mdx Outdated
Comment on lines +89 to +94
These commands:

- Generate a `docker-compose.yaml` from the AppHost
- Generate environment-specific `.env` files with filled-in values
- Build container images
- Output everything to the `aspire-output` directory
Copy link
Copy Markdown
Member

@JamesNK JamesNK Mar 30, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@IEvangelist There should be a margin bottom on this list. I doesn't look good to not have a space between it and the next title:

Image

@davidfowl
Address PR review feedback from @JamesNK
450e99e 
- docker-compose: mention AddDockerComposeEnvironment in prose, highlight key lines
- docker-compose: change example resource name to avoid 'docker-compose-down-compose'
- kubernetes: rename to 'Publish to Kubernetes', clarify no aspire deploy support
- kubernetes: mention AddKubernetesEnvironment in prose, highlight key lines
- kubernetes: replace plaintext tree with FileTree component
- kubernetes: update sidebar label to match
- redirects: add missing Japanese locale redirect for pipelines
- deploy-first-app: fix lowercase 'when' at sentence start
- customize-container-apps: add TS tab to Resource groups section
- docker-compose: margin-bottom issue is a site-wide CSS concern (noted for @IEvangelist)

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
JamesNK
JamesNK reviewed Mar 30, 2026
View reviewed changes
JamesNK
JamesNK reviewed Mar 30, 2026
View reviewed changes
src/frontend/config/redirects.mjs
'/reference/cli/commands/aspire-exec/': '/reference/cli/commands/aspire-resource/',
'/get-started/configure-mcp/': '/get-started/ai-coding-agents/',
'/get-started/pipelines/': '/deployment/pipelines/',
'/ja/get-started/pipelines/': '/ja/deployment/pipelines/',
Copy link
Copy Markdown
Member

@JamesNK JamesNK Mar 30, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@IEvangelist Some locale specific redirects are here, but on for ja and only for some pages. Should they be removed? Or should more be added?

Copy link
Copy Markdown
Member

@IEvangelist IEvangelist Mar 31, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I believe they should be removed. The default locales should auto redirect.

davidfowl and others added 2 commits March 30, 2026 16:56
@davidfowl
Address round 2 PR feedback from @JamesNK
54da652 
- kubernetes: make TS samples match C# scope (snippet-only, not full builder)
- kubernetes: remove ASPIRE_RESOURCE_SERVICE_ENDPOINT_URL caution (dashboard-only)
- azd: make TS sample match C# scope
- customize-aca: make all TS samples match C# scope (5 blocks fixed)
- customize-aca: link 'Azure Container Apps' to ACA about page
- customize-aca: add TS tab to Resource groups with :::note pattern

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
@davidfowl
Revert Kubernetes rename — keep 'Deploy to Kubernetes' in deployment …
0be7088 
…section

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
@davidfowl davidfowl force-pushed the davidfowl/deployment-fixes branch from f252913 to 0be7088 Compare March 30, 2026 23:58
@davidfowl
Fix C#/TypeScript sample parity across deployment pages
f6e9b96 
- docker-compose: remove builder boilerplate from registry TS sample
- customize-aca: clarify ContainerAppHandle scaling in TS comment
- customize-aca: clean up publishAsExisting TS sample (strings, not params)

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
JamesNK
JamesNK reviewed Mar 31, 2026
View reviewed changes
@davidfowl
Use 'env' as Docker Compose resource name in examples
3a0c7bc 
Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
@JamesNK JamesNK mentioned this pull request Mar 31, 2026
Closed
davidfowl and others added 3 commits March 30, 2026 17:09
@davidfowl
Fix 'front end' -> 'frontend' consistency in deploy-first-app
809b9a8 
Addresses review feedback: standardize on 'frontend' (one word) throughout
prose and mermaid diagram labels.

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
@davidfowl
Fix remaining C#/TS sample mismatches
b14fba2 
- docker-compose: use addParameterFromConfiguration to match C# config binding
- customize-aca: use publishAsExistingFromParameters with parameters to match C#
- ACA scaling: genuine API gap (ContainerAppHandle), comment is accurate

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
@IEvangelist
Clean up content, fix issues with C# APIs being incorrect, link to as…
3aba1e3 
…pire.dev API ref - instead of MS Learn, fix #645
@IEvangelist IEvangelist enabled auto-merge (squash) March 31, 2026 12:40
@IEvangelist IEvangelist merged commit afb88d9 into main Mar 31, 2026
5 checks passed
@IEvangelist IEvangelist deleted the davidfowl/deployment-fixes branch March 31, 2026 13:07
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

@JamesNK JamesNK JamesNK left review comments

Copilot code review Copilot Copilot left review comments

@IEvangelist IEvangelist IEvangelist approved these changes

@mitchdenny mitchdenny Awaiting requested review from mitchdenny mitchdenny is a code owner

@eerhardt eerhardt Awaiting requested review from eerhardt eerhardt is a code owner

@maddymontaquila maddymontaquila Awaiting requested review from maddymontaquila maddymontaquila is a code owner

Assignees

No one assigned

Labels

None yet

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

4 participants

@davidfowl @JamesNK @IEvangelist