docs: retire Playground from the reader's path and fix stale, internal, and contradictory copy - #432
Open
defang-sam[bot] wants to merge 9 commits into
Open
defang-sam[bot] wants to merge 9 commits into
defang-sam[bot] wants to merge 9 commits into
Conversation
Playground is shut down, so nothing may teach it as a live deploy target. - Rewrite docs/providers/playground.md and docs/concepts/defang-playground.md as past-tense tombstones that point at /docs/providers. The pages stay because they hold inbound links. - Delete the Deploy to Playground tutorial and redirect it to /docs/tutorials/deploy-to-your-cloud. - Drop the default Playground tab from the domains, services, and networking concept pages, keeping the remaining content flat. - Remove the --provider=defang warning entry and the stale Playground transcript line from the Heroku migration tutorial. - Note that managed storage is available when deploying to your own cloud.
Replace the Deploy to the Playground section with Deploy to your cloud: add a step for picking a provider and setting up credentials, show defang compose up --provider=aws, and name the other providers. Update the sample transcript: portal.defang.dev becomes portal.defang.io, and the service URL uses the defang.app pattern instead of an internal shard hostname. Drop the fabricated log lines rather than inventing output we cannot verify. Remove the Pulumi card from Next Steps, since the Pulumi provider has no live deploy target.
The provider only ever deployed to the Defang-hosted environment that has been discontinued, and it does not support your own cloud account yet. Say so, point readers at Compose, and invite them to the Discord if they need it. Remove the fabricDNS / DEFANG_FABRIC interface member, which names an internal backend.
- Replace --mode=production with --mode=high_availability everywhere, and name the mode in prose instead of calling it 'the production mode'. production is not one of the three modes. - The auto-scaling FAQ said Defang has no auto-scaling, which contradicts docs/concepts/scaling. Say yes on AWS and GCP via x-defang-autoscaling, in balanced mode or higher, on the Pro plan. - The provider FAQ restated provider maturity inconsistently. Link /docs/providers for current status instead. - accounts.md said GitHub was the only way to authenticate, which contradicts authentication.md. Name GitHub and GitLab. - Replace the retired Playground domain pattern on accounts.md with the pattern used on the domains page.
The example CD task definition ARN contained a real Defang AWS account ID and a typo in the service name (aws:ecsus-west-2). Replace it with placeholders. Replace project1/tenant1 certificate domains with <project>/<username>.
portal.defang.dev is not the portal host. Replace every occurrence in docs/ and src/ with portal.defang.io, including the 1-Click Deploy link builder. Retarget both 1-Click tutorials at your own cloud account and describe the flow the component actually builds: the link goes through the Portal to log you in, then to GitHub to create your copy of the sample, and a GitHub Actions workflow deploys it. Drop the 'environment: playground' key from the sample workflow and pass a provider instead. Remove the Playground section from the MCP tutorial, keeping the Portal inspection step as a provider-agnostic closer. workspaces.md: 'the repository owner automatically becomes the tenant context' exposed a schema term. Say the owner's workspace is used.
- station.mdx said the section is 'a placeholder so the products have a home in the docs', which exposes editorial reasoning to readers. - Remove banned words: effortless, streamlined, leverage, simply, and the 'heavy lifting' sentence on the GCP page, which now says what Defang provisions for you. - 'Any App, Any Stack, Any Cloud.' read as a fourth tagline directly under the Defang Deploy tagline. Demote it to prose. - Add recipes to the Portal capability list; docs/concepts/recipe links there for them. - Delete src/components/HomepageFeatures, unmodified Docusaurus template copy that nothing imports.
Record the rules this cleanup enforced so they survive the next edit: who reads the docs, which internals never appear in copy, the decided product names and taglines, and the real mode and plan names.
|
Important Review skippedBot user detected. To trigger a single review, invoke the ⚙️ Run configurationConfiguration used: Organization UI Review profile: CHILL Plan: Advanced Run ID: You can disable this status message by setting the Use the checkbox below for a quick retry:
Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out. Comment |
raphaeltm
reviewed
Sep 16, 2026
| ## Structure | ||
|
|
||
| Your GitHub username will be used as your Defang username. Your Defang username is used to group all your [services](/docs/concepts/services) and generate domains for your services with the following structure: | ||
| Your GitHub or GitLab username will be used as your Defang username. Your Defang username is used to group all your [services](/docs/concepts/services) and generate domains for your services with the following structure: |
Contributor
There was a problem hiding this comment.
Username no longer true. Internal tenant id.
raphaeltm
reviewed
Sep 16, 2026
| </TabItem> | ||
| <TabItem value="pulumi" label="Pulumi"> | ||
| :::warning | ||
| As of now, the Pulumi provider does not support [Defang BYOC](./defang-byoc.md). |
Contributor
There was a problem hiding this comment.
This is no longer true, I believe?
raphaeltm
reviewed
Sep 16, 2026
|
|
||
| :::warning | ||
| Pulumi support is currently only available for Defang Playground. We are working on support for Defang BYOC. | ||
| The Defang Pulumi Provider is not currently available. The Defang-hosted environment it deployed to has been discontinued, and it does not yet support deploying to your own cloud account. Use a [Compose file](/docs/concepts/compose) to deploy today. If you need the Pulumi Provider, tell us on the [Defang Discord](https://discord.gg/defang) so we can prioritize it. |
Contributor
There was a problem hiding this comment.
This is no longer true. Check the DefangLabs/pulumi-defang repo
raphaeltm
reviewed
Sep 16, 2026
| 2024-09-19T10:51:39.419693-07:00 app Server running at http://0.0.0.0:3000/ | ||
| * Service app is in state DEPLOYMENT_COMPLETED and will be available at: | ||
| - https://jordanstephens-app--3000.prod1.defang.dev | ||
| - https://app--3000.welcome-to-defang.<your-username>.defang.app |
raphaeltm
requested changes
Sep 16, 2026
Member
|
@defangdevs address comments and update this pr |
…r status - accounts.md, domains.mdx, getting-started.mdx: domains are keyed off an internal tenant ID, not the GitHub/GitLab username - pulumi.md, domains.mdx: the Defang Pulumi Provider is available for AWS, GCP, and Azure — it was not discontinued Addresses @raphaeltm's review comments on PR #432.
Contributor
|
Addressed the review feedback in 54b159b:
@raphaeltm PTAL |
This branch has not been deployed
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
3 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
What this does
An Opus 5 copy review of docs.defang.io against
strategy/language-style-guide.md(defang-global), read as a brand-new developer. The docs' brand layer was already clean; the problem was that the "Get Started" CTA still taught Playground — a shut-down product — as the primary deploy path, and the reference layer had drifted from the CLI.Playground retired everywhere a reader can follow it
defang compose up --provider=aws, and a transcript pointing atportal.defang.ioand a*.defang.appURL (wasportal.defang.dev+prod1.defang.devinternal hosts).providers/playgroundandconcepts/defang-playgroundrewritten as past-tense tombstones;tutorials/deploy-to-playgrounddeleted with a redirect.environment: playgroundworkflow key).Internal identifiers removed
381492210770) was printed in an example ARN under "resources in your AWS account" → placeholder (plus an ARN typo fix).portal.defang.dev→portal.defang.ioin 8 places; Playground domain patterns (prod1.defang.dev) → the real*.defang.apppattern; "tenant context"/tenant1→ workspace/placeholders;fabricDNS/DEFANG_FABRICdropped from the published Pulumi interface.Contradictions fixed
x-defang-autoscaling: true→ corrected (yes on AWS/GCP, balanced mode+, Pro plan).--mode=production(deprecated wire enum) →high_availabilityin 6 places.Style + rules
Screenshots (from the branch, local dev server, real prebuild)
Verification
npx docusaurus buildsucceeds (with realprebuild.shCLI docs); the new redirect validates; remaining broken-link warnings are pre-existing (verified on clean main).playgroundonly in the two tombstones; noportal.defang.dev,prod1.defang,mode=production, or the AWS account ID anywhere indocs/+src/.Follow-ups (not in this PR)
static/samples.jsonstill carriesportal.defang.dev— it is generated from the samples repo; fix belongs in DefangLabs/samples (starter-sample README).using-codespaces-gitpod.mddescribes the sunset Gitpod Classic flow; needs a human decision on replacement.Part of the cross-repo copy review (defang-global, defang-mvp, portal, station PRs linked from the defang-global PR). Review + fixes by Opus 5 subagents.
🤖 Generated with Claude Code